Markdown's Big Brother: Say Hello to AsciiDoc
64 comments
·February 6, 2025acidburnNSA
boxed
I've used it for a few years but still have to look up how to do references and links every time. The API has some hilariously bad parts too (you must mark a section link above the heading, but in the AST it's then not part of the section.. why!?). It's also quite slow, and has silent failures that produce garbage in the output sometimes.
danmur
It's a bit more effort but it just can't be beat for documentation.
andrewl-hn
We’ve used AsciiDoc for some of our documentation and for generating slide decks.
It is obviously a nice system but over time our frustration with it grew. Every other piece of software we have uses Markdown: GitHub, work chat, chats of open source projects we work with, things like StackOverflow, HackMD, personal note taking apps, the list goes on and on. Every new person joining our team had to adjust to AsciiDoc just for some of the work they would be doing while staying with Markdown for everything else.
We pulled the plug last year and migrated everything we had to Markdown, and while sometimes I need to use HTML tags to do something advanced I don’t mind it as much as I thought I would.
ffaser5gxlsll
The frustration for me is then which "flavored" version of markdown you're now using, because the evolution seems to always be "MD is simple and popular" until gets extended with subtle differences. Those subtle semi-random differences in flavors get tiring really fast.
CrimsonRain
What's the frustration about? Basic things are same everywhere.
If you need complex things, you already have enough skills to figure that out. Also there's almost always a help button around that lists what it supports.
citrin_ru
For me the frustration is that you cannot learn markdown once and use it in different places - for non-trivial things you always have to use a reference for a particular flavor.
latexr
> over time our frustration with it grew. Every other piece of software we have uses Markdown
Doesn’t seem fair to call that a frustration with AsciiDoc. The frustration is around it, caused by everything else.
> GitHub
Supports and renders AsciiDoc for documentation. But granted, preference is given to markdown in things like comments.
CrimsonRain
Adoc is too cumbersome and the tooling around it are always subpar; sometimes unusable. It also is trying to be somewhat of a replacement of html and is really bad at it.
Markdown + html or simply Hugo is way better.
pindab0ter
Markdown being so ubiquitous is what makes it valuable, IMO. Do you think AsciiDoc has the potential to reach that point as well?
wodenokoto
I am not sure I think they are that comparable. AschiiDoc is a proper mark-up language, something markdown explicitly sets out not to be. Markdown is easy to remember, easy to consume in its clear-text form and renderable. I fail to see that AsciiDoc or HTML having "unrendered consumption" as a goal at all.
There is so much you can't put in Markdown because it doesn't work without rendering.
dqv
Any Markdown implementation which allows for custom directives and is CommonMark-compliant is good enough for me.
MyST, for example, lets you do
:::{makeup-highlight}
:lang: elixir
defmodule A do
def b, do: :ok
end
:::
:::{pygments-highlight}
:lang: python
class B:
pass
:::
Symbiote
AsciiDoctor also has an AST intermediary which can be used by plugins/extensions.
mahkoh
The problem with asciidoc is that it doesn't support nesting. Markdown allows you to nest constructs as much as you want using syntax that are easy to use for both humans and documentation-generating applications.
The asciidoc developers don't seem to consider this an important issue: https://github.com/asciidoctor/asciidoctor/issues/1121
While asciidoc has some nice constructs, this made it a no go the last time I was looking for a documentation language.
FloatArtifact
It seems the maintainer is willing to implement it but lacks the time. Perhaps a PR would be in order.
kimi
My company uses Asciidoc for documentation - for almost 20 years now - and it's really good. Now with Antora you can make searchable docs, and with Asciidoctor you can create most diagrams right within the text. We target HTML/PDF/Epub and it works really well.
So you get a result that is Word-quality, but separates presentation and content, and is easy to keep under version control.
replete
Do you also use it for company docs, policies etc, or only for software documentation? Would love to see the back of Word.
kimi
Basically for anything/everything but README.md because we use Gogs and that's just MD. OK, I admit we sometimes use Word to craft a specific page, or a print-once sign.
jmull
To me, asciidoc is effectively another markdown variant, but one that is less readable and considerably less interoperable than other flavors.
I'd rather pair markdown with an independent template language, if I need programmability. (Or script tags, though that's only useful in contexts where you'll view it rendered and script tags aren't blocked.)
sausagefeet
I've been using AsciiDoc since Oxide did a podcast on their RFDs and I love it. I find it so much saner than Markdown, and it covers more usecases. I wish there were more implementations but asciidoctor works great. Hugo also supports AsciiDoc.
bcantrill
That's awesome to hear! For other folks, our discussion is at [0] -- in which I learn that AsciiDoc is nowhere near as ubiquitous as I thought it to be. (But optimistic that that's starting to change, especially given the article!)
[0] https://oxide-and-friends.transistor.fm/episodes/rfds-the-ba...
tcfhgj
Once I felt that Markdown wasn't enough for documentation and Asciidoc seemed to be a good alternative.
I tried to rewrite it to AsciiDoc, but there was some unexpected ugly ess. Iirc e.g. lists. It bothered me so much, I switched back to markdown.
Today I reach for Typst when I need more than Markdown. Biggest caviar there is that html export is still wip.
sReinwald
> Biggest caviar there is that html export is still wip.
Pandoc seems to support converting from and to Typst. That might be an option for you.
red_admiral
> If you’ve been relying on Markdown and occasionally fighting its quirks, AsciiDoc might be the structured, fully-featured alternative you didn’t know you needed.
No, I'm afraid it's the format I know I don't need. At least not for the kind of things I usually use markdown for.
Readme files, technical documentation, moderately complex websites with templating and rendering engines - markdown works just fine. Sometimes with a custom `|||warning\n...\n|||\n` thrown in to render something in a box with a red border.
I get that there's a market in the space occupied by TeX, Typst (underrated IMHO), and possibly MS Word or Quark Express (for non-techies). Libreoffice is great in theory but, again IMHO, "eh" in practice. That market is generating book-length documents with all the cross-references and other features that needs.
That said, Robert Nystrom of "Crafting Interpreters" managed this just fine with markdown and a few custom scripts: https://journal.stuffwithstuff.com/2020/04/05/crafting-craft... , https://github.com/munificent/craftinginterpreters/tree/mast... . This is how those famous 10x writers/programmers work, I guess.
Asciidoc is Markdown's big brother? I'll carry on playing with the little brother, thank you very much.
Also the whole page is an ad for their own editor tool. $9.99 per month so you don't need to use your own editor and unintuitive tools like (gasp!) the terminal.
drdec
I have used asciidoc when I needed to generate PDFs for documentation.
You don't need any paid tools if you don't want them, I used a text editor and the terminal and source control.
I don't understand the hostility toward someone offering a product. It's fine that you don't need it, that doesn't mean someone else won't.
red_admiral
My worldview is there's a big market for WYSIWYG editors, and a big "market" for FOSS editors and tools, but not too much in between for simple text editing.
I can't think of many scenarios where someone does care about the backing format or explicitly wants to write raw asciidoc, but doesn't want to just use asciidoctor or other free CLI tools.
aitchnyu
We could be using html based DSLs and powerful importable components instead of special characters. Monaco (VSCode editor framework) allows frontend devs to make special DSL editors with autocomplete for both desktop and web. Between Spectacle and Typst approaches, I would choose Spectacle.
I read the 2003 book The art of Unix programming where the author praises plain text config and says hand editing xml is a human rights violation, since Notepad was the most powerful ubiquitous editor then. Markdown was best then.
https://commerce.nearform.com/open-source/spectacle/docs/api...
ognyankulev
I was hoping Eclipse AsciiDoc would already deliver stable spec, TCK and (new) reference implementation: https://asciidoc-wg.eclipse.org/projects/
mdaniel
I was expecting it to be Yet Another Eclipse Abandonware but https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-la... has commits from 5 hours ago, and https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-tc... was 10 months ago, which isn't nothing. But yikes they are not doing themselves any discoverability favors by having almost every meaningful looking link on https://projects.eclipse.org/projects/asciidoc.asciidoc-lang point to itself
As much as people don't really like it, reStructuredText with Sphinx is still my favorite one of these. Once you get into wanting to do fancy things, the sheer power and extensibility of it with custom directives and community plugins is hard to beat. The glossary, index, and project cross-referencing features (intersphinx) are amazing. You can easily integrate with Bibtex reference libraries (maybe managed in Zotero). You can do full-on traceable QA in it, not just for software, but for hardware projects as well using e.g. sphinx-needs [1]. I think for some sophisticated applications, reST + sphinx is best.
And of course you can write some pages in this ecosystem in Markdown if you want using MyST [2]
[1] https://sphinx-needs.readthedocs.io/en/latest/
[2] https://myst-parser.readthedocs.io/en/latest/intro.html