7 ms·

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

169 points by gouggoug 8y ago

sirsuki 8y ago
How does AsciiDoctor compare to Pandoc? Based on the AsciiDoctor hype page it seems to describe the same features Pandoc offers.
- phalangion 8y ago
  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.
  - sirsuki 8y ago
    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.
- mr_tristan 8y ago
  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-asciidoctor-stylesheet-factory/ https://asciidoctor.org/docs/produce-custom-themes-using-asc... https://github.com/darshandsoni/asciidoctor-skins 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.
jdeisenberg 8y ago
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.
- gouggoug 8y ago
  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/#source-code https://asciidoctor.org/docs/asciidoc-syntax-quick-reference... and search for callouts)
secure 8y ago
+1: If you’ve been using asciidoc, check out asciidoctor. It’s compatible (compatible enough for me) and produces much better looking output :)
- pvorb 8y ago
  This thread already is about Asciidoctor, not Asciidoc.
dom96 8y ago
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 https://book.picheta.me
- ben_straub 8y ago
  Likewise. Pro Git 2e was written using Asciidoc, and it made it easier/possible to do things like indexing and figure titles.
xte 8y ago
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".
gouggoug 8y ago
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.
- Numberwang 8y ago
  It is amazing, but I had to move everything to markdown since asciidoc is basically dead at this point.
- j0e1 8y ago
  Mind explaining how this is superior to Markdown?
  - gouggoug 8y ago
    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.
    - chubot 8y ago
      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.
arminiusreturns 8y ago
Between asciidoc and emacs org mode for me, currently still using asciidoc for somethings while I work on my html export from org mode
xrd 8y ago
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.app 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.
psychometry 8y ago
The site should on its homepage have a simple features table comparing it to other solutions like Markdown and LaTeX.
smartmic 8y ago
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 http://hyperpolyglot.org/lightweight-markup
- xrd 8y ago
  Well worth the read. I agree.
- warent 8y ago
  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
  - smartmic 8y ago
    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.
  - smartmic 8y ago
    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.
wuyishan 8y ago
I recently came across mdtk (https://github.com/ynohat/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
ktosobcy 8y ago
AsciiDoctor is great, the only thing missing is outputing chunked html directly without having to deal with docbook for example (maven setup)
graphememes 8y ago
So it's just a specification?
edoceo 8y ago
I love this tool, and the embedded plantuml is amazing.
Iwan-Zotow 8y ago
Waiting for utf8doctor to cure 'em all
emmanueloga_ 8y ago
"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 http://asciidoc.org/userguide.html 2: https://docs.oasis-open.org/docbook/docbook/v5.1/os/docbook-v5.1-os.html https://docs.oasis-open.org/docbook/docbook/v5.1/os/docbook-...
kwccoin 8y ago
Wonder about this: https://asciidoctor.org/docs/asciidoc-vs-markdown/ https://asciidoctor.org/docs/asciidoc-vs-markdown/
pragmaticlurker 8y ago
it's a pity that the asciidoctor-pdf Ruby GEM is quite old now
a-nikolaev 8y ago
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.

169 points by gouggoug 8y ago

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

phalangion 8y ago
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.
- sirsuki 8y ago
  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.
mr_tristan 8y ago
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-asciidoctor-stylesheet-factory/ https://asciidoctor.org/docs/produce-custom-themes-using-asc... https://github.com/darshandsoni/asciidoctor-skins 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.

jdeisenberg 8y ago

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.

gouggoug 8y ago
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/#source-code https://asciidoctor.org/docs/asciidoc-syntax-quick-reference... and search for callouts)

secure 8y ago

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

pvorb 8y ago
This thread already is about Asciidoctor, not Asciidoc.

dom96 8y ago

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 https://book.picheta.me

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

xte 8y ago

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".

gouggoug 8y ago

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.

Numberwang 8y ago
It is amazing, but I had to move everything to markdown since asciidoc is basically dead at this point.
j0e1 8y ago
Mind explaining how this is superior to Markdown?
- gouggoug 8y ago
  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.
  - chubot 8y ago
    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.

arminiusreturns 8y ago

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

xrd 8y ago

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.app 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.

psychometry 8y ago

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

smartmic 8y ago

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 http://hyperpolyglot.org/lightweight-markup

xrd 8y ago
Well worth the read. I agree.
warent 8y ago
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
- smartmic 8y ago
  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.
- smartmic 8y ago
  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.

wuyishan 8y ago

I recently came across mdtk (https://github.com/ynohat/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

ktosobcy 8y ago

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

graphememes 8y ago

So it's just a specification?

edoceo 8y ago

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

Iwan-Zotow 8y ago

Waiting for utf8doctor to cure 'em all

emmanueloga_ 8y ago

"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 http://asciidoc.org/userguide.html 2: https://docs.oasis-open.org/docbook/docbook/v5.1/os/docbook-v5.1-os.html https://docs.oasis-open.org/docbook/docbook/v5.1/os/docbook-...

kwccoin 8y ago

Wonder about this: https://asciidoctor.org/docs/asciidoc-vs-markdown/ https://asciidoctor.org/docs/asciidoc-vs-markdown/

pragmaticlurker 8y ago

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

a-nikolaev 8y ago

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.