
Asciidoctor – A fast, open-source text processor and publishing toolchain - gouggoug
https://asciidoctor.org/
======
smartmic
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)

~~~
warent
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
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.

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

------
emmanueloga_
"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-...](https://docs.oasis-
open.org/docbook/docbook/v5.1/os/docbook-v5.1-os.html)

------
dom96
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
Likewise. Pro Git 2e was written using Asciidoc, and it made it
easier/possible to do things like indexing and figure titles.

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

~~~
j0e1
Mind explaining how this is superior to Markdown?

~~~
gouggoug
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
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.

~~~
mmsimanga
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.

~~~
mkobit
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](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.

------
xrd
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...](https://play.google.com/store/apps/details?id=com.EditorHyde.app))
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.

------
wuyishan
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

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

~~~
phalangion
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
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.

------
a-nikolaev
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.

------
jdeisenberg
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
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...](https://asciidoctor.org/docs/asciidoc-syntax-quick-
reference/#source-code) and search for callouts)

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

~~~
pvorb
This thread already is about Asciidoctor, not Asciidoc.

------
Iwan-Zotow
Waiting for utf8doctor to cure 'em all

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

------
kwccoin
Wonder about this:

[https://asciidoctor.org/docs/asciidoc-vs-
markdown/](https://asciidoctor.org/docs/asciidoc-vs-markdown/)

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

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

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

------
graphememes
So it's just a specification?

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

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

