Compare AsciiDoc and Markdown | Hacker News Reader

Compare AsciiDoc and Markdown

docs.asciidoctor.org

182 pointsmad2021134 comments

I just wrote an entire book in asciidoc and honestly I don't like a lot of the decisions and the syntax, the tooling is also quite messy and hard to use/configure.

Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown.

EDIT: so that people get an idea, I use asciidoc because it provides callouts, sidebars, captions, figures, cross references, LaTeX (via hard-to-use plugins), themes, fonts, etc. when converting to pdf or epub, etc.

This question may be a bit naive, but it comes from somebody who has never used asciidoc but used a lot of LaTeX to make reports, poster, presentations, ...

Why are you using asciidoc to write a book, instead of LaTeX ? I see the advantage of using this for documentation, but for an entire book ?

My guess: To convert it into an ebook.

You can convert latex into ebooks I believe, it’s just completely overkill most of the time.

LaTeX is pretty imposing for non-academic newbies. And if you're not writing a book that includes a bibliography or a lot of complex math equations, then it's arguably overkill.

On the other hand, if you already know the gist of Markdown, then you could pick up reStructuredText or AsciiDoc in less than an hour. They're more feature-rich than markdown, without adding too much squeeze for the juice.

I like to use Markdown for authoring (it's a lot simpler than LaTeX!), but use Pandoc to convert to PDF (which uses a LaTeX template).

If needed, you can also sprinkle the Markdown with LaTeX, such as to enforce page breaks at specific points.

There’s no point using latex if your book has almost no formulas. If your book has a lot of them, then yes I would say using latex makes sense.

> There’s no point using latex if your book has almost no formulas...

In a book one often needs to keep track of local references (to figures, tables, sections, etc). How this could be reasonably done in markdown flavors?

Asciidoc already supports that. You don’t even need to differentiate in the syntax, it knows when you are referring to a table, a figure, a section, code listing, etc.

And in reStructuredText you can make any place in your document a "source" and any place a "sink" of a reference. Is it the same in AsciiDoc, or are only special things like listings etc. referencable?

LaTeX books are ugly.

We need an open source alternative to https://www.princexml.com/samples/

Or at least one not that expensive.

> We need an open source alternative to https://www.princexml.com/samples/

TeXmacs: https://www.texmacs.org

As far as I know e.g. this book https://www.editions-ellipses.fr/accueil/4856-le-petit-pytho... has been written with TeXmacs, and antoher is in preparation by the same author. Also, Joris van der Hoeven has written a guide to TeXmacs ("The Jolly Writer") using TeXmacs

Having written my fair share of Latex, I will chime in that I despise the language. Verbose, too many special characters I need to escape (copy and pasting text becomes a chore), slow to compile, mystery number of compilation steps, and horrible debugability.

None of these are showstoppers, but quite a few paper cuts that leave me reaching for Latex only as a last resort. There are tooling and workflows one can adopt to minimize the pain, but it requires a lot of setup if I just want to get some text on a page.

I have stupidly optimistic hopes that something like [Skribilo](https://www.nongnu.org/skribilo/) would take over in this space, but I know that is foolhardy. Would require a generation of physicists and mathematicians to give up their hard-won Latex knowledge.

The answer is in my opinion the following:

You use LaTeX when you have to for some specific thing, perhaps equations, but at other times, you can stick with the simpler syntax of (AsciiDoc|reStructuredText|Org-Mode).

That's what I do at least.

RestructuredText (usually used within Sphinx) is the only alternative in the same class. Unfortunately there are hardly any comparisons. Maybe there are no people who have significant experience with both.

I reckon reStructuredText is the best syntactic and semantic foundation of all the ones I’ve seen, but there are a few things it could do with changing. Most significantly, reStructuredText is designed for being written in a sane text editor, where indenting stuff is easy; but this doesn’t work well for use in a plain <textarea> as web applications of it will commonly go for, where any indentation must be applied manually by the writer. So I’d say it’d be good to get a new syntax construct for fenced, rather than indented, directives. For example, this is what reStructuredText has:

  .. directive-name:: first-line-options
     :subsequent-options: and their values
     :and-more: if you want

     Then the directive’s body.

And here’s a strawman fenced syntax:

  ```directive-name:: first-line-options
  :subsequent-options: and their values
  :and-more: if you want

  Then the directive’s body.
  ```

Of course, once you’re touching something like that you’d want to touch more things to make it all consistent again, but it’d all be perfectly possible. (Would you use backtick? Dunno. I hear it’s hard to access on some keyboard layouts like German.)

As it stands, reStructuredText is based around having visually-pretty source: monospacedly-aligned tables, indentation for hierarchy, that sort of thing. (Headings feel like the only major thing that doesn’t use very significant whitespace.) I almost always like this, but there are definitely some situations when it’d be nice not to work that way.

Would you go all-in on fenced things rather than indented things? I dunno. Probably.

> Would you use backtick? Dunno. I hear it’s hard to access on some keyboard layouts like German.

It's fine, you have to press the key right next to the backspace key plus shift. Not exactly ergonomic, but easy to discover on basically any standard QWERTZ keyboard. I'd definitely like a fenced alternative. I'm okay with indentation-based code, but somehow I really dislike using it in my writing.

What makes it annoying to use is that it's a deadkey

I think it would easier to build a website with a more feature-rich <textarea> alternative, than it would be to push that clunky syntax onto end-users.

reStructuredText and AsciiDoc are already straddling the line between Markdown and full-featured markup languages. If you need more than this, then you should probably bite the bullet and just use LaTeX or some other markup.

> I think it would easier to build a website with a more feature-rich <textarea> alternative, than it would be to push that clunky syntax onto end-users.

The <textarea> we always have with us. Anything extensively indentation-based is doomed as a general-purpose web markup language (where you’re typing in that markup language—WYSIWYG/WYSIWYM editors are another matter), because all <textarea> “enhancements” will behave differently and will be at least a little painful.

> reStructuredText and AsciiDoc are already straddling the line between Markdown and full-featured markup languages.

I think that’s the wrong framing. All three have roughly the same goals, just Markdown is… worse. And yeah, I’m going to stick with that. Markdown is a low-quality hack that unfortunately (in my mind) gained popularity, a textbook case of “worse is better”, because its dodgy HTML foundation and simple processing model made it far easier to adopt (with many painful incompatibilities between implementations) than something like reStructuredText which is actually sound but takes a lot more effort to implement, so that there’s really only one implementation of it.

reStructuredText and AsciiDoc are full-featured presentation-agnostic markup languages. Markdown is itself fairly minimally-featured, which works out because it’s tied to HTML, which carries the burden of supporting more extensive functionality (though not very well).

LaTeX is a full-featured presentation-locked markup language. It is not at all suitable as an alternative for the likes of reStructuredText, as reStructuredText is much more flexible on presentation options. With something like Sphinx, you can target HTML, LaTeX, Windows’ old-style help, man pages, and more.

rST doesn't support nesting markup (bold and italic? nope. code styling in a link? nope.). It's decent for writing software docs, but not good at all (in my opinion) for writing blog posts or other prose.

Code styling in a link sounds useful, but bold and italic generally shouldn't be combined[0].

[0]: https://practicaltypography.com/bold-or-italic.html

Bold and italic at the same time? What is the devils work?

Yeah, nesting inline markup is definitely something I’d want to add. Note that code styling in a link is actually possible, just convoluted:

  Using |foo|__.

  .. |foo| replace:: substitution with the ``replace`` directive
  __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions

Funny thing is that, from what I recollect of investigating this matter a decade ago, there was never any fundamental objection to nested inline markup in reStructuredText, it just… hasn’t happened.

I think it might be a complicated thing to add cleanly for all possible use-cases in the implementation. I remember, how knots in my head formed, when I thought about implementing nested inline markup in a markdown parser. For example if you have nestings like: A B C b c a (where the upper case letter marks the start and lower case letter the end of a markup)

The main implementation of reStructuredText is a custom parser, which might be a hassle to modify to accomodate all cases of nesting, including duplicate ones like: A B A text b a a.

But perhaps all the difficulty in this stems from making the symbols used for starting an inline markup the same as for ending it. Otherwise it would be trivial to count opening and closing "parentheses".

> And here’s a strawman fenced syntax:

You might find MyST interesting! Personally I’m counting on it to succeed (after painfully realising reStructuredText never will )

https://myst-parser.readthedocs.io/en/latest/

RestructuredText was chosen over Asciidoc for the Linux Kernel Documentation:

  - https://lwn.net/Articles/692704/

  - https://www.kernel.org/doc/html/latest/#other-documentation

Back in 2016.

There is a lot of comparison made in that decision.

Here's a comparison.

https://hyperpolyglot.org/lightweight-markup

Aside, I still don't understand why restructuedText never took off. The language is so expressive and well-documented, there are anchored references and tables, you can write you academic papers in it and just generate PDFs from it afterwards. There are so many constructs that Markdown and friends don't have.

I have significant experience with both. I've written complex documentation in RsT (Sphinx) and Markdown (Azure Devops, Jupyter, and RMarkdown).

For basic use cases (sections, lists, text formatting), they're both similar in functionality, but Markdown has the advantage of having lightweight, memorable syntax. I would argue that Markdown's syntax is also aesthetically more pleasing (RsT uses a lot of punctuation).

For advanced use cases however (long docs, with math/code listings, complex cross refs, footnotes, callouts, etc.), RsT feels more powerful out of the box. I'm sure Markdown has extensions that can help it achieve similar functionality, but it almost feels like Markdown wasn't designed for advanced use cases.

To use a very imperfect analogy, Markdown to me feels like Microsoft Word (easy to get started on), whereas RsT feels like LaTeX (very code-centric). Although either can be used for any use case, Markdown seems like the right choice for most web-centric use cases, whereas RsT seems slightly more suitable to complex documentation.

I made a highly extensible markup language (inline macros, plugins, etc.) a while ago called Quaint[1] that I've been meaning to dive back into at some point. Out of curiosity, do you reckon it'd fit your use cases?

[1] https://breuleux.github.io/quaint/index.html

My one comment: what I like about Markdown is that the "code" itself is readable, you don't have to effectively transform it to HTML, as is it almost looks like some text with a few characters here and there to emphasize things. Quaint's .q files look too much like source code to me, you wouldn't want to read them as is.

Could you be more specific as to what looks too much like source code? The most common difference between the two would be *multi word emphasis* vs _[multi word emphasis]. The former may be less conspicuous, but both read fine to me.

Sure. What I mean is that quaint files (e.g. [1] and [2]) look like simplified HTML ; you're defining functions, div hierarchy, formatting and such. I cannot comfortably read the .q, I have to read the rendered HTML. On the other hand, this [3] looks like a text file with ASCII formatting ; the fact that it compiles to HTML is almost incidental.

[1]: https://github.com/breuleux/blog/blob/master/content/about.q [2]: https://github.com/breuleux/quaint-doc/blob/master/content/i... [3]: https://raw.githubusercontent.com/breuleux/earl-grey/master/...

I mean, okay, I can see that, but they're not really equivalent examples, are they? The README isn't setting up a carousel, dealing with custom styles, or embedding an interactive example. There isn't really any way to implement these two Quaint examples that won't look like code. [1] or [2] are more representative of using Quaint like Markdown, although in that situation it's less clear what the advantages are, because there's not a lot in there that Markdown would do poorly.

[1] https://raw.githubusercontent.com/breuleux/blog/master/conte...

[2] https://raw.githubusercontent.com/breuleux/blog/master/conte...

In any case, it does appear the discoverability of straightforward examples leaves something to be desired, so thank you for making me realize that.

To me the advantages of Quaint is that I can easily define custom operators to do nonstandard things unobtrusively. For instance, if for some reason I want to emphasize some words in italic orange, I can easily set it up so that e.g. /xyz would highlight xyz in italic orange. Silly example, but there are a lot of valid use cases.

Did you do everything yourself? I'm wondering because I've always assumed that everybody you hand your book to down the line (editor and publisher) is going to want to use Word.

I’m sure there’s publishers that will take PDFs

Even places that use Adobe's InDesign for typesetting tend to work from Word files. I asked because I'm wondering if that has started to change.

My publisher (manning publications) uses asciidoc. But I think they convert the whole thing to something else at the very end of the process.

What tools are you using to write a book in asciidoc?

I really like AsciiDoc and would encourage anyone to give it a try, especially for things like software documentation (in all forms).

I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL.

The problem is simply that github, gitlab, and friends adopted Markdown and so it's got a heavy head start. Asciidoc is competing with small snippet documentation like README files written in Markdown and wiki pages in Confluence, Sharepoint, and the like. Asciidoc is pinched in the middle. I do hope it gets better adoption.

There is nothing really preventing GitHub and others from implementing a AsciiDoc/tor converter. AsciiDoctor is already written in Ruby, which is probably what they use on the backend for Markdown conversion. Hugo supports it as well, and I'm sure there are other static site generators. I agree 100% about documentation on Confluence or Sharepoint. Seriously, will not even work at a company that is heavily invested in either at this point.

Github already supports Restructured Text (reST) in READMEs, and some other markdown flavours. Do not know about AsciiDoc but looks interesting.

As can be seen here, GitHub renders Asciidoc just fine: https://github.com/asciidoctor/asciidoctor.js

Alas, no support[1] for include.

[1]: https://github.com/github/markup/issues/1095

According to GitHub Docs [1], GitHub supports several markup languages, including Markdown, AsciiDoc, Textile, ReStructuredText, Rdoc, Org, Creole, MediaWiki, and Pod.

[1] https://docs.github.com/en/github/managing-files-in-a-reposi...

GitLab also support AsciiDoc.

SourceHut unfortunately does not. You can go through the hoops of POSTing to its GraphQL API from CI a new README from any format to HTML.

You can also embed diagrams and flowcharts with Mermaid into Asciidoc, not only in Markdown.

https://docs.gitlab.com/ee/user/asciidoc.html#mermaid

Examples for Mermaid layouts in the GitLab handbook: https://about.gitlab.com/handbook/tools-and-tips/mermaid/

> There is nothing really preventing GitHub and others from implementing a AsciiDoc/tor converter

Github already supports AsciiDoc via AsciiDoctor.

> I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL

There'd a middle-ish ground we're going with at work - you have the documentation alongside the code in git, and your CI/CD also uploads it to Confluence/whatever for less technical folks/searchability/etc.

( Tools used are Gitlab CI, mark and Confluence, but they don't really matter, the workflow does).

Yeah, you could add a job to your CI that runs a compiler and outputs the result to a web page that can be accessed by all. I'm sure there's ways and means to have a web based editor that can commit into version control as well.

I didn't know it already existed. I'm working on something similar via a Github app which watch new commits made on master and offer to the commiter to upload its new .md files on the wiki.

As you said having the dev doc on an external tool is really a plus. You can have comments, you can add tags, easier to search, and give access to non technical people

I really like the sound of this. That’s how Google’s internal technical docs worked. Write markdown in src repo, get nice, searchable doc site in return.

Anyone know if a tool like that already exists to turn README.md files into a website?

There are a few ones, the only one that comes to mind is Docusaurus from iirc Facebook.

I have both a centralized Confluence instance and the documentation in GitHub. A GitHub action converts the markdown to Confluence to stay in sync. It's very handy, because developers like to document in markdown on GitHub, but business people tend to favor Confluence. One additional feature you get from this is the search over all repos, which doesn't work without additional tooling in GitHub.

It wouldn't be so bad if Confluence/whatever could just render the Asciidoc from the source repository. But they are generally closed systems. There's no way in or out of Confluence without significant headaches.

The really fun part of having docs in confluence is that if Confluence goes down, you lose access to ops playbooks.

I’ve had similar fun experience with Slack-ops when slack goes down.

One of the better, yet sad jokes, because it must have been one, was, when they announced "markdown support" in Confluence wiki, but barely any markdown worked. One has to ask oneself, who coded up that half-assed parser there, that manages to parse less markdown, than basically any half-serious markdown parser in any language, that I have ever used. Enterprise software for you.

Edit: Now that I think about it, the whole product palette of Atlassian seems to have issues making use of any decent markdown parser out of the myriads of parsers out there, that they could use. For example HTML in markdown on Bitbucket also does not properly work, so generating a table of contents is useless on Bitbucket as well.

The only reason there isn’t an official Markdown spec is that John Gruber blocked the effort at creating one. A bunch of people made a great spec that eliminates all the ambiguities and tried to make it “Standard Markdown”.

Gruber then threatened them with legal action (since he holds the copyright on the word Markdown and for some reason hates proper specifications), so they had to rename their spec “CommonMark”.

Most of the big Markdown-using services (GitHub, GitLab, Reddit, Stack Overflow, etc.) implement this spec, so it is basically the Markdown spec, all but in name.

It can be found at https://spec.commonmark.org/

From what I remember, John McFarlane and his Pandoc project helped a lot in getting CommonMark adopted.

Github used to have its own "Github-flavored Markdown" before CommonMark came along.

Correct, he (jgm on GitHub) is still by far the biggest contributor to the spec: https://github.com/commonmark/commonmark-spec/graphs/contrib...

I'm not a Gruber fan but I think his actions in this case are totally defensible. Every month on HN there's a post about some OSS project mod stepping down due to abuse and insane expectations from the community.

Gruber wrote a tool that solved his own personal problem, shared it with the world because why not, and then made damn sure he wasn't going to have to deal with any fallout put on him for his sharing.

Gruber did the exact opposite than stepping down. Even now, he insists on controlling the name “Markdown”, despite having abandoned the project over 15 years ago.

It would be a bit like Tim Berners-Lee trying to police how people use “WWW” today. He might theoretically be within his legal rights, but he’d still be a jerk for doing so.

So then name it something else than Markdown? Gruber invented and published it, its fair that he gets to protect the name.

Renaming it would defeat the purpose of standardisation. Instead of unifying the language, it would create confusion among users who know what Markdown is but do not know “CommonMark” or vice versa.

And no, I do not think it fair or reasonable that whoever first coined a term gets to control its meaning forever. Especially when he just reused an existing dictionary word.

Basically, Gruber is asserting that because he came up with the concept, he gets to decide that no one can fix its flaws and clear up its ambiguities, and because the problems that stance causes to thousands of people do not affect him, we can all just kiss his self-righteous posterior.

Then let's stop referencing it as Markdown and let's all use the CommonMark name.

Ah yeah, try to educate millions of end-users about the new name, change the file extensions on 15 years worth of files, update reams of documentation, libraries and applications.

Does that sound even remotely feasible? I think not.

For better or worse, we’re stuck with the name, because trying to change it and failing would just create more compatibility problems and confusion.

Much like the eternal GIF pronunciation controversy or tabs vs. spaces, we’ll all just have to grin and bear it, because Gruber is not likely to change his mind.

“it also fulfills the objective of ensuring your content is maximally reusable”

This is a bit of a trap when it comes to teams chasing the goal of modular documentation.

AsciiDoc let’s you include other AsciiDoc files, so teams modularize content with the idea that all these modules are potentially reusable.

But unlike code which, say, might use a method that is available bc another file has been included/imported, an AsciiDoc include doesn’t reveal any of its content. It’s just a file name that will be replaced with the content of that file upon render.

This means you literally cannot read modularized content from source - you need to open up every included file and read each out of context.

Available tooling also presents previewed/rendered includes as if they are part of the parent document, which removes the ability to identify modularized content from the output.

In my experience this results in documentation that is modularized by diktat - usually after being authored in a Google Doc. Reuse never happens, in fact nobody but the author really knows what content was modularized in the first place.

The Conditional Content piece of 'component content" is one that's consistently ignored by every Big Iron vendor that I've ever talked to.

Which is 100% nuclear stupid, because, as you point out, you can't do component content without conditional content. And once you start doing conditional content, you need to have a damn good idea of what your whole product architecture looks like: what works with what, which packages are packages, obsolescence, blah blah blabbity blah. At industry conferences this makes me mad enough to spit, and all those goobers are suckering these writer teams into paying $7000 per person per (EDIT)month (!!) for a system that's going to be nothing but heartache in thirty six months.

Luckily, Asciidoc does have conditional directives, but the include directive is wayyyyy too primitive for what it's being used for right now (also as you point out). The `ainclude` directive is in extension right now, and it will probably be brought into core as a subdoc directive.

Having said that, it really is the best game in town, for generating both modern HTML alongside old-timey PDFs and DocBook XML, all from the same source.

Markdown's single best idea is that it is very readable "raw". While AsciiDoc is better than, say, html, it seems that's mostly a lucky accident because it's close to Markdown. Where it diverges, it looks like it fell from the XML tree.

Example:

   .Lightweight Markup
   NO THIS TEXT IS NOT LIGHT

Now, in fairness, Markdown doesn't have any methods to do that. But for quotes, Markdown gets it right:

    > this is a quote
    > and that's obvious

While AsciiDoc uses a block that doesn't have any meaning for the casual reader:

    -----
    Quote Quote
    -----

You can use Markdown-style syntax as well

https://docs.asciidoctor.org/asciidoc/latest/blocks/blockquo...

If I remember it correctly the origin story is „Docbook as non-XML syntax“, so it really fell from the XML tree.

Actually, Docbook started as an SGML vocabulary and only in version 5 became XML-first. And SGML, as it relates to this thread, is a parser generator you can use to perform markdown-to-HTML conversion (including full HTML inlining), or AsciiDoc/rST or your own custom extension syntax to whatever XMLish angle-bracket markup you wish. So apologies, but considering we have SGML since 1986 or earlier, discussing surface syntax (markdown vs AsciiDoc vs rST vs orgmode or whatever) seems kindof moot and merely a matter of personal preference really.

Markdown may be less precise from a technical perspective. But it is easier to use for most people and just good enough.

AsciiDoctor is a great framework for writing documentation and manuals. And there is also markdown support, so you can reuse/embed your existing documenentation.

The point of Markdown is having a very tiny set of features: headers, paragraphs, lists, links, pre-formatted text, etc. You can learn this in minutes.

Having Markdown with more features is against what makes Markdown useful: minimalism.

I disagree... Markdown is no longer a single unified version. There are multiple implementation, extensions, etc. The original Markdown spec by itself isn't that useful and there is a reason so many extensions have been made for it. It can maintain simplicity while still adding new features. Pandoc has some great examples of Markdown extensions that are really useful.

The core features are pretty much universal and used in a lot of apps (chats, forums, git repositories, project management). Custom flavors maybe not rendered correctly at times but this doesn't make documents unreadable

The core features used in a lot of apps include different flavors, like GitHub Markdown and others. The closest thing you have to a unified Markdown is CommonMark and even that is forked for GFM. Yes, headers, bold and italics text, and lists are nice but there is a lot more to take into account when you are trying to supplement docs that other extensions add.

There are dialects of Markdown but they all respect the core features.

true, but please notice that you can use asciidoc as a larger subset of md

Which is not something I want. If I wanted something more complex I would use TeX.

The funny thing is that on their page markdown has better syntax highlighting than their own markup language

It's been a bit of a disappointment for me to discover that AsciiDoc's grammar is so complex that they didn't even describe it in a spec. Their spec is a collection of tests.

This must be contributing a lot to the adoption difficulty (at least for resource-limited open-source projects). There's a good chance you will not find an AsciiDoc parser library for your favourite programming language.

There is one for go which is my favorite language. And there is also one for python and javascript. Did you check ?

If you mean libasciidoc for Go, it does not support all the AsciiDoc features [1]. The JS parser is transpiled [2] from the Ruby implementation (which is not a bad thing, it's just something most languages can't have).

My favourites are Rust and Haskell. Neither of them had a parcer until recently (even though the original implementation has been around for a few years now). Both are at early development stages at the moment.

[1]: https://github.com/bytesparadise/libasciidoc/blob/master/LIM...

[2]: https://asciidoctor.org/docs/asciidoctor.js/

The AsciiDoc Working Group has been formed to write a complete and comprehensive specification: https://asciidoc-wg.eclipse.org/

If you are interested in an AsciiDoc processor in Haskell, you can read: https://www.tweag.io/blog/2021-06-15-asciidoc-haskell-pandoc...

We had Guillem Marpons at the last AsciiDoc WG meeting and he was willing to work toward a spec-compliant implementation and help us with the spec.

I didn't know about the specification effort. It's great news!

I'm very impressed with what asciidoc-hs plans to do! Especially looking forward to LSP support and stuff like incomplete/incremental parsing.

I feel like this is the tech comparison equivalent of straw-manning.

Take xrefs for instance. They say that the Markdown is:

   See [Usage](#_usage).

   <h2 id="_usage">Usage</h2>

and that the AsciiDoc is:

   See <<_usage>>.

   == Usage

I mean, clear win for AsciiDoc, right? So I Google "cross reference" "markdown and get this SO post as the first hit: https://stackoverflow.com/questions/5319754/cross-reference-... – 802 point answer saying to do this:

   Take me to [pookie](#pookie)

   <a name="pookie"></a>

I just switched my blog to Jekyll recently so I checked to see what Jekyll does to section headings under the hood (you most want to turn section headings into anchor points, no?) Turns out it automatically turns `<h2>Usage</h2>` into

   <h2 id="usage">Usage</h2>

So clearly Jekyll does the right thing out of the box. Then all you have to do is:

   See [Usage](#_usage).

somewhere else. What I'm getting at is this. Don't pretend your competitor is lamer than it is when doing comparison tables because it'll disincline people to check you out if they find out you've done that. You should steel-man your competitor and _still_ beat them. FWIW I think that Markdown (and its variants) always try to choose a syntax that aligns with how you'd write idiomatic non-HTML text-only styling. I mean compare the unordered and ordered list examples. Markdown chose right, AsciiDoc chose wrong. Objectively speaking, you'd choose the Markdown way naturally. I grant you, sometimes the choices are a little forced but what are you going to do, eh?

You can click the "Edit this page" button and submit an improvement.

Having said that, the fact remains that you don't have a standard syntax to add an id on a section title (without using HTML directly).

Jekyll might does the right thing but Jekyll is not Markdown. Does it work elsewhere? If not then your document is not really portable.

> I mean compare the unordered and ordered list examples. Markdown chose right, AsciiDoc chose wrong. Objectively speaking, you'd choose the Markdown way naturally.

In a trivial example, Markdown's syntax looks more natural. It might well be the more appropriate syntax for a short README, which expects to be read as plain text at least as often as rendered to HTML.

In real use, i.e. when editing a non-trivial example, AsciiDoctor's multiple-star/dot syntax makes it easier to keep track of things.

You can also use the Markdown-style indentation instead anyway: https://docs.asciidoctor.org/asciidoc/latest/lists/ordered/#...

In pandoc's extended Markdown you can just write

    # Usage

    See [Usage].

https://pandoc.org/MANUAL.html#extension-implicit_header_ref...

FreeBSD has recently switched from DocBook to AsciiDoc for its documentation: https://docs.freebsd.org/en/books/fdp-primer/asciidoctor-pri...

Markdown was also an option but it was missing too many features for a documentation set of this size.

That's actually a likely switch, since AsciiDoc was specifically designed to optimally support Docbook features. So that switch should be painless.

For the type of documentation that I do, I find that the single biggest win with AsciiDoc is it's table functionality.

Specifically the two things that are really nice is:

A) You can write out a table row over multiple lines. Default syntax/mode makes it really easy to do a cell per line.

B) You can embed (more) complex formatting easily into the table. So stuff like lists, block quote/code block, whatever.

There's something about org-mode markup syntax that's really nice.

I use org-mode every day for organization and documentation in org-roam. I barely touch the text markup features though. Most of the time I don't mess with exporting either. (org-mode exports to LaTeX, HTML, or practically anything via pandoc)

Have you written much using org-mode as a replacement for asciidoc/markdown etc? I should probably try to find some examples of longer-form org-mode docs and see if I can use those features.

For years I've been maintaining my course materials in org-mode and exporting to HTML each semester. I'm in the middle of consolidating the materials into a PDF book via LaTeX export for students to print out if they want. I really like the typeset look of the resulting PDF, even though there are no equations or formulas (I'm a part-time law professor). I'm doing just-in-time learning of the necessary LaTeX via Stack Exchange; it's crude, but effective.

To be sure, the Emacs dependency is something of an entry barrier for org-mode. It helps that I've been using Emacs and various text formatters — Scribe, Final Word, and now pandoc — going back some 40 years.

I much prefer Asciidoctor to Markdown when writing documents that's longer than a single A4 page, since it has the ability to combine multiple files into a single document if needed.

Have you considered using pandoc[1]?

  pandoc file1.md file2.md .... -o final.md

  pandoc file1.md file2.md .... -o final.pdf

[1] https://pandoc.org/

That's just concatenation though.

Asciidoctor has very good support for `include`, so you can include a file in the middle of another file. Furthermore, you can even do partial include where you only include a section of another the file in the current file.

I have setups where each of my files can work as a standalone document with proper Title and Appendix. These files can be compiled into another file where all the individual title are change to sub-title, and all the appendices are group together into one section.

The worst part of AsciiDoc I think is its name.

It sounds so archaic.

It does tend to make one worry that all the tools will be hideously un-unicode aware and mangle any non-ASCII documents.

I would like to imagine that in this day and age that isn't the case, but the name works against it.

Particularly when the syntax bakes in things like support for converting certain ASCII sequences into Unicode characters [0]

[0] https://docs.asciidoctor.org/asciidoc/latest/text/quotation-...

Yes, I finally got around to adding some "quail" stuff to my .emacs so that I can directly type various kinds of quotation mark and dash rather than rely on complex conversion rules that sometimes go wrong.

The lack of first-class support for balanced quotation marks seems to be a major problem for computers. I think a lot of computer code, particularly scripts, would be easier to read and less buggy if the languages had been designed by someone with balanced quotation marks on their keyboard.

As a thought experiment, imagine what Lisp would look like if '(' and ')' were the same character and you had to use the same work-arounds that shell scripts use for open quotation mark and close quotation mark being the same character. Instead of (a ((b c) d)) we'd write |a \|\\\|b c\\\| d\||. That's fine, right? We can live with that?

Perhaps we should think ourselves lucky that 0 and O are not the same character, and 1 and l, like they were on the first mechanical typewriters.

Mind you, there's one similar annoyance that predates typewriters and continues to plague us in Unicode: apostrophe and closing single quotation mark are logically quite different things, but they're the same character: ’

> Yes, I finally got around to adding some "quail" stuff to my .emacs

Why into .emacs and not into the global keyboard configuration? Don't you ever write text outside of emacs?

Yes, good question. One reason is that I haven't found a convenient portable way of modifying Linux keyboard configurations. Another is that sometimes I'm SSH-ing in from a machine that isn't even Linux.

I have used xkbcomp to replace a character I don't need with one I do, but the recipe tends to require maintenance and I don't know how to program dead keys with that approach. Perhaps there's a better way nowadays.

I was somehow expecting the answer to be: "Yes, I do all my keyboard input from inside emacs, including running the shell".

For linux-portable keyboard configuration, you may find that an unholy mix of setxbmap (to set up the grand options) and xmodmap (to modify a few particular keys) is what works best for you. At least it does for me.

> sometimes I'm SSH-ing in from a machine that isn't even Linux.

ah! the horror!

Came here to say this. UTF-8/16 represents such a relief from the previous text-encoding nightmares that I run away from any tooling that does not use it.

If anyone else was a web dev in the 90s, you know what I’m talking about.

AsciiDoctor supports Unicode just fine.

We've integrated it with PO4A[0] and CrowdIn.com to support a translation workflow, and so far have one document in Chinese: [1].

Another (tiny) example is [2] with an emoji star, you can "Edit this page" and see the Unicode source.

[0] https://po4a.org/

[1] https://docs.gbif.org/collections-idea-paper/zh/

[2] https://ipt.gbif.org/manual/en/ipt/2.5/data-hosting-centres#...

The issue is that the name strongly implies that it doesn't. If a system is named "Doesn'tSupportImportantThingSys" don't be surprised when people don't bother to check the documentation to find that it actually does support the important thing. They'll just skip it.

^ this.

ASCII is so old that I picture ANSI colour blocks as it’s successor, and both of those are firmly in the “nightmarish text encoding days”

You want archaic? It could be worse. It could be EbcdicDoc.

Wow, using Perl scripts to convert output from my AS/400's DB2 instance into ASCII so that I could import them into Oracle 8i and display them on an ASP page... that was a memory I had hoped to forget.

Yeah, as someone whose name contains non-ASCII characters, the association with ASCII is not exactly a positive one. I’ve wasted so much time dealing with data in non-Unicode encodings over my career that the mere word ASCII makes me want to punch something.

While we are at it: Why not orgmode? It‘s much more versatile.

But I still go back to markdown because everyone (and almost every tool I use) will accept it.

I also prefer .org files for anything. It does almost everything Markdown does with just as simple syntax, but then can be used for any more comprehensive purpose by being fully LaTeX compatible. Although I think this strong coupling with Emacs has unfortunately caused it to stay in that niche, even though most of those scripted interactions aren't really important for the common use-cases.

It also doesn't help that Emacs seems to be the only complete and correct parser; I tried org files as Readme in git repos, and for example Gitlab really struggles. Pandoc isn't fully compatible either.

2nd. I'm a heavy org-mode user but the problem w/org-mode is that it's got emacs in front of it, and you are just not going to get uptake. Pandoc's not really a solution, either, apart from a one-time extraction of org-mode to whatever other format is desired. As soon as you get multiple non-emacs editors, your pandoc trip is over.

It always bothered me that these ascii processors don't use /for italics/. It just looks visually like italics.

I think it's because it's too ambiguous. Forward slashes are very common in written language (similar to apostrophes/single quotes), so users would a lot of escaping to do.

The thing with Markdown is that it does most of what you need to do with it, until it doesn't, when you can bring Pandoc to bear and put full-on LaTeX in your Markdown and it will render it however you want. I wrote a dissertation this way with inlined Rmarkdown code. It was great.

I wrote my doctoral thesis (biology) this way (markdown + LaTeX + pandoc) and honestly, it was disappointing how much raw LaTeX I had to end up writing anyway. I had to rewrite all my tables & figures in LaTeX because it was easier than trying to figure out the odd layouts markdown + pandoc produced.

If I had to do something of similar scale and complexity from scratch today, I'd look for a better solution.

We use Dropbox Paper for team documents(not source code documentation). I actually like it.

The thing that makes MarkDown documents less appealing is the inability to handle images seamlesslessly(drag and drop). Most of the time, our documents involve images to explain stuff. Uploading them somewhere, and then manually adding a tag and correctly copy/paste the url in MD makes it less appealing that just drag & drop an image in a WYSIWYG editor and spending the focus on _documentation_.

What I’d like is a MArkDown Editor that also simply allows me to drag and drop images and it should handle uploading and linking the images transparently.

Funny enough the GitHub file/issue editing UI handles drag and drop image uploading really well.

> What I’d like is a MArkDown Editor that also simply allows me to drag and drop images

Have a look at Typora [0]. It's my main Markdown editor for this reason (and others).

[0] https://typora.io/

Check this free markdown WYSIWYG editor https://marktext.app/. I guess it is inspired by Typora which is the first I saw. It is very impressive. Not sure about the image drag and drop. That is app specific.

I wished we had that for ASCIIDoc because it looks more powerful than the half backed Markdown.

As someone who's spent the last several years maintaining a couple large, vaguely complex documents (CP-CPS documents for certificate authorities), AsciiDoc has been a winner. It's simple enough to be readable in git diffs and be updated by non-tech folks like managers, but supports enough features that doing things like tables, nested lists, and certificate structure notation to be workable. And it's WAY more manageable using git to build and publish to PDFs (using Pandoc) than trying to use Word docs.

As of today, there are so many incredible tools for Markdown — like Brett Terpstra’s Marked 2 and Christian Tietze’s Tableflip right off the bat — that make it so much more versatile. Obviously there are flaws, but if you find yourself working mostly in the same syntax all the time (I’m a MultiMarkdown man myself) it’s easy to make sure all your tools play well with one another.

Markdown's one of those special things that's good enough and simple enough. It doesn't do everything, but what it does do is easy to learn and use, and covers a large number of use cases.

Inline code was conspicuously missing in the comparison, which is more unwieldy in asciidoc (requires backtic and plus instead of just backtic). That’s probably the markdown feature I use most often.

You only need to use backtic and plus when you want to disable text substitutions (a concept that does not exist in Markdown).

Most of the time, using backtic is enough: `text`.

Comparing AsciiDoc to Markdown (instead of for instance reSructured Text/reST) is clever, but I don't think there's any widespread controversy about the shortcomings of Markdown. So that's just an easy win.

I've seen this premise a lot (quoting from the article)

»The most compelling reason to choose a lightweight markup language for writing is to minimize the number of technical concepts an author must grasp in order to be immediately productive.«

What relevant documentation markup languages have this issue?

If we already agree that documentation should be written as code, let's embrace it and not be scared of showing syntax. It's our tools that matter here - syntax highlighting, previewing, CI feedback.

I see much more that people writing markup languages get extremely motivated from their first victories with coding something.

Don't be afraid of showing people syntax -- Wikipedia got pretty far with a less-than-optimal markup language!

I think the real issue with AsciiDoc is something more along these lines: https://xkcd.com/927/

I'm working in a large organization where we are failing to streamline and spread documentation practices because of many different standards and practices popping up everywhere.

I like a lot how the Python community has centered around Sphinx and Read the Docs. It's great that for instance Sphinx support both Markdown and reST in that regards -- but then when things like Hugo/Docsy, AsciiDoc, Github Wikis, groovydoc etc. starts popping up, the unification of documentation practices in a large organization becomes harder -- and also of course across the specter of Open Source projects.

I'm using markdown for 90 percent, then for the 10 percent use HTML

I've also used Textile https://textile-lang.com/

But it's less supported, so I stopped using it.

Honestly, I see both as abominations which didn't accomplish what they've been rooting for – a rich text with minimal burden.

*strong*

/italic/

_underline_

-strikeout-

Can't be parsed by pandoc. As much as it may be the better format, that makes it unusable.

Reply on news.ycombinator.com