Asciidoctor – A fast, open-source text processor and publishing toolchain | Hacker News Reader

Asciidoctor – A fast, open-source text processor and publishing toolchain

asciidoctor.org

169 pointsgouggoug42 comments

There are so many markup languages and conversion possibilities, just have a look on the to-from option from pandoc.

Personally, I prefer reStructuredText, its design feels more consistent in comparison to the ambiguous implementations of the various markdown dialects.

In Asciidoc, I do not like that lower lever headings occupy more markers than higher level ones. Visually,

=== This heading

appears more important than

== This heading

By the way, a good comparison is at http://hyperpolyglot.org/lightweight-markup

Well worth the read. I agree.

There's a couple reasons why I think it would be bad if higher level headings would be considered more important. First, in HTML, <h1> is the top heading which directly maps to

= heading

If you were to do it the other way around, there's no easy way to know which would would map to h1

======= this?

============= this?

The second reason why is because you have to have a baseline of maximum-importance. It's like ticket priorities capping out at P0 for maximum priority. The first intuitive thought would be that P5 should be more important than P0, but if you don't set a baseline of maximum importance, then there will always be someone who feels their thing is slightly more important.

========== Top level heading

=========== Super top level heading

============== Extra super top level heading deluxe

From a technical implementation point of view, I agree. But I had the viewpoint of a visually guided human, the non-technical type.

That is also why I stick to reStructeredText, they circumnavigate ATX-style headers at all.

Concerning the baseline, doesn't the HTML5 standard just specify 6 ranks from <h1> … <h6>? Would be at least a candidate for common agreement on the lowest (highest) rank.

HTML5 also supports nestet <section> with their <h> tags. I’m not sure if there is a maximum nesting level in this case.

Another argument in favor of adding markers for lower levels is that indenting the first character of a header typically indicates lower level headings in a table of contents.

    Chapter 1 ............... 5
     Section 1a ............. 7
     Section 1b ............ 11
    Chapter 2 .............. 17
     Section 2a ............ 21

is nicely similar to

    # Chapter 1
    Lorem ipsum dolor sit amet.
    ## Section 1a
    Lorem ipsum dolor sit amet.
    ## Section 1b
    Lorem ipsum dolor sit amet.
    # Chapter 2
    Lorem ipsum dolor sit amet.
    ## Section 2a
    Lorem ipsum dolor sit amet.

I think this is a bikeshedding criticism more than something that requires serious concern. Asciidoctor simply supports more out-of-the-box and officially than reStructuredText. Preferring reStructuredText to Asciidoctor this way is like comparing Python to Ruby for syntax alone. Function is just as important.

In Asciidoctor, I can:

* Use GraphViz (and other diagram) docs to describe architectural components.

* Actually test my example code, using named, delineating comments in my test suite and including the code between those comments as an example in my file.

* Support for WARNING, NOTE, etc. callout "admonitions"

* Auto-numbered list blocks with "."

Some of these may be possible with reStructuredText, and can definitely be supported with third party plugins, but all of this is first-party and amazing.

Note: IntelliJ's Asciidoctor plugin is incredible and it live renders mathematical equations AND graphing support in addition to everything else.

Sounds like org-mode. All hail Emacsen.

"AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain-text markup conventions."

And Asciidoctor is a toolchain for working with AsciiDoc.

One thing to have in mind is that AsciiDoc syntax is incredibly complex [1]: it maps to the already complicated-on-its-own-right DocBook standard [2]. It has a lot of bells and whistles that one may want to use on a real print book, but maybe not for general documentation.

I feel like if you are not writing something that you actually intend to print, Asciidoc (and DocBook) are overkill.

1: http://asciidoc.org/userguide.html

2: https://docs.oasis-open.org/docbook/docbook/v5.1/os/docbook-...

I've written my book in Asciidoc [1]. It's a brilliant tool and far more powerful than Markdown but it does have some quirks (for example, you need to escape "C++").

1 - https://book.picheta.me

Likewise. Pro Git 2e was written using Asciidoc, and it made it easier/possible to do things like indexing and figure titles.

I've entirely replaced markdown and been using asciidoctor for both documentation and general writing.

Asciidoctor is far superior to Markdown and as easy to use and is also supported on Github.

Mind explaining how this is superior to Markdown?

Here's a comparison: https://asciidoctor.org/docs/asciidoc-vs-markdown/

(Note: This appears to be written by the AsciiDoc team)

Asciidoc has many more feature and as easy to use as Markdown. Markdown definitely does the job for very quick documentation, but when it comes to more in depth documentation I've found asciidoc to be much better.

I'll use an example: I often need to create "Warning Notes" (aka "Admonitions") in my documentation. Those notes need to stand out, but they also need to not break the flow of reading. I need them to be visible, but easy to spot with the eye and ignore. It makes reading the doc and ignoring less important information easier. With Markdown, I can't create those notes.

Other interesting and useful thing is the ability to use variables. This allows me to make the documentation dynamic. Imagine, for example, a documentation that has many CURL requests examples that must include an X-Auth-Token. I can dynamically generate the documentation with the Auth-Token of the user reading the doc, allowing them to Copy/Paste the examples without having to modify them first.

FWIW, I use a macro processor with markdown. Markdown supports arbitrary inline HTML, which makes it very convenient to use like this. You can create a macro for the warning box. I have another one to insert not just code snippets, but the result of running the code snippet.

I've used asciidoc before, and I don't recall it having arbitrary programmability? I'd be interested in how that works.

Can you please elaborate on how exactly you create the macros? I started using asciidoc because I could not find a neat way of embedding code snippets (stored in separate file) into markdown text. Asciidoc has this as built in feature.

This is one of my favorite features, too. I've found it works amazing when you generate the documentation or render it locally. Unfortunately, it doesn't work in "safe" mode sites like GitHub or GitLab where having a lightweight include feature for samples or tests would be useful.

For macros in AsciiDoc, I've made do with the little bit of support mentioned at https://asciidoctor.org/docs/user-manual/#pass-macros . Everything I found for Markdown always required an additional tool or "something else". I like that AsciiDoctor, for the most parts, has nearly everything I want built-in.

I'm not suggesting this as the right solution, but I wrote a lot of assignments for my MSc with Markdown + build scripts + a heavy amount of Perl.

Variously this did things like running embedded unit tests in code examples, validating XSL schemas, making sure GraphViz images were created and up-to-date, running a Z-Notation type-checker, and code that created both SQL and Relational Algebra from a simplified SQL-like DSL.

I'm not saying this is a superior approach to AsciiDoc, just that it's amazing what you can create when you turn your mind to avoiding working on your MSc assignments and let your OCD about creating perfect assignments run wild.

I wrote a script which preprocesses the .md file, passes certain sections to shell scripts, and inserts the result of the script back into the .md file.

It's very much a Unix stdin-stdout thing. My whole blog [1] uses this, especially the code examples highlighted with pygments, and also links to the glossary, etc.

I dumped a snapshot here [2] awhile ago. It may or may not be of use if asciidoc already works for you.

The bad thing about this format is that it's not pure markdown anymore, so Vim syntax highlighting gets messed up sometimes. If I had to do it again, I would probably try to hook into a CommonMark [3] library to parse HTML blocks. So basically certain <div></div> blocks would get transformed into others.

How does asciidoc do it?

[1] http://www.oilshell.org/blog/

[2] https://github.com/oilshell/blog-code/tree/master/tools-snap...

[3] http://www.oilshell.org/blog/2018/02/14.htm

For me - ability to structure documents nicely with `include::`

If you want to edit and preview asciidoc files on Android, you can use Teddy Hyde (https://play.google.com/store/apps/details?id=com.EditorHyde...) inside your GitHub repositories. I edit Jekyll blogs using it.

My book was written in asciidoc for O'Reilly. Honestly, the asciidoc docs are a mess, for example, trying to add a header to a set of documents is much more challenging than it needs to be.

I recently came across mdtk (https://github.com/ynohat/mdtk) which renders text-based input (not asciidoc, but md) into nice documents by configurable packagers (currently revealjs & typora). Also provides option to extend md with custom logic, such as variable interpretation

How does AsciiDoctor compare to Pandoc? Based on the AsciiDoctor hype page it seems to describe the same features Pandoc offers.

Pandoc and AsciiDoctor are fairly similar in their purpose. Pandoc aims to provide conversion between a bunch of different formats, while AsciiDoctor primarily focuses on the AsciiDoc format, a "competitor" for markdown.

I prefer AsciiDoc over Markdown because it is just a bit more robust. While both are equally simple to use for the most common use cases of marking up a document and adding bold, italics, headings, and code snippets, AsciiDoc has features to add figure captions, cross references, and other slightly more robust features that I use for a lot of my writing.

Oh believe me I love AsciiDoc. I would use it all the time if half the tools out there would support it. Sadly, as it stands most forums and chat apps still think Markdown is the only format ever to be invented.

Eh, I'd say they're pretty different goals and use cases in reality. Pandoc is great for translation into other formats, where the other format then is applied final styling using downstream tools.

AsciiDoctor is for the Asciidoc format, but, generally includes some nice tooling for commonly used output formats.

Yes, you can use pandoc to convert asciidoc to something else, but in general, I've noticed that asciidoctor has great support for HTML themes:

https://asciidoctor.org/docs/produce-custom-themes-using-asc...

https://github.com/darshandsoni/asciidoctor-skins

The PDF styling directly out of the asciidoctor tool, on the other hand, isn't as advanced. So going from asciidoc to DocBook can make sense here, and I think is probably still done to do things like create truly professional looking PDFs.

What to use? Depends on your toolchain. I almost never need anything but HTML and PDF.

I've found that people, used to Markdown, can jump into Asciidoc and use `asciidoctor` easily.

I think, this is a wonderful tool. The Asciidoc format is much better specified than Markdown, which is okay for a short text like a Github readme, but lacks consistency between rendering engines, and is not really feature rich for anything more serious than a short text.

The Asciidoctor tool also comes with a very high-quality default CSS style, which makes it very appealing and ready to use. Thumbs up from me for the work on this tool and the format.

One thing I have found useful but difficult to do in both markdown and AsciiDoc: I have a block of code, and I want to highlight, say, a variable name by making it italic or bold. Or, I have several lines that have changed from one example to the next, and I want to somehow show that those lines are the ones that have been modified by some form of marker (“change bar”) or highlighting.

One solution, though not exactly what you want, is to use "Code block with callouts"(go here https://asciidoctor.org/docs/asciidoc-syntax-quick-reference... and search for callouts)

+1: If you’ve been using asciidoc, check out asciidoctor. It’s compatible (compatible enough for me) and produces much better looking output :)

This thread already is about Asciidoctor, not Asciidoc.

Waiting for utf8doctor to cure 'em all

Wonder about this:

https://asciidoctor.org/docs/asciidoc-vs-markdown/

I love this tool, and the embedded plantuml is amazing.

AsciiDoctor is great, the only thing missing is outputing chunked html directly without having to deal with docbook for example (maven setup)

Between asciidoc and emacs org mode for me, currently still using asciidoc for somethings while I work on my html export from org mode

So it's just a specification?

it's a pity that the asciidoctor-pdf Ruby GEM is quite old now

The site should on its homepage have a simple features table comparing it to other solutions like Markdown and LaTeX.

Mh in the past many work came from another project ConTeXt from Pragma-ade a sort of LaTeX with an easy DSL and a tons of style. however many other are in a similar state while LaTeX survive, the others, included mythical languages like *roff or docbook die or remain marginal...

Long story short: thanks for sharing your work, that's good and if it serve you it's a very smart move but I do not expect a real "success".

Reply on news.ycombinator.com