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]
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.
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.
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.
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.
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.
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.
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.
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
:::
Since MyST has intermediaries that just give you an AST, you have a lot more extensibility using directives and roles to do special things (including includes). You can of course just use MyST proper, but getting to transform the AST myself how I see fit is a big win in my eyes. Pandoc does have AST and all that too, but MyST's implementation strikes the best balance for me.
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.
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.
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.
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.)
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.
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!)
> 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.
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.
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.
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.
Tooling for asciidoc (last time I used it) was super sparse and next to unusable. There was primarily one underlying engine everyone relied on to do cross-filetype generations, and the available editors was pretty bad as well. Of the few free ones, the recommended list was like:
- JetBrains Plugin
- VSCode Plugin
I wanted to like it, but doing anything was a bit of a pain. If I need that level of structure, I'd rather work with something like Typst. Otherwise Markdown works fine.
On a side note, it's still part of almost all character encodings, since it only occupies half of an octet. Obviously for many languages and special chars we need another "half".
Why does there need to be something else? That’s a powerful reason.
Markdown is subpar and has an awful steward—as evidenced by all the different “flavours” and degrees of support in existence—but we somehow made it work in a jumble of hacks and that’s what we have now. It’s crummy but gets the job done.
Even if AsciiDoc is technically superior, which it probably is, is it superior enough to justify the big players implementing and pushing for in more in places regular users have access too?
Opposing goals, the purpose of markdown is to have a nice looking plain text document that can be automatically typeset and asciidoc is to have a well structured plain text document that can be automaticly typeset.
Note that markdown's whole value proposition is that it is a nice looking plaintext format, it stinks at adding any sort of semantic value to a document. realistically if you care about your documentation you will use something better than markdown. The problem is adding better structure always makes the plain text ugly and hard to read, violating the whole point of markdown. that is to say, the many efforts to add better semantics to markdown don't appear to understand the point of markdown.
ASCII, by way of that character encoding standard, implies that dark age before writing and transmitting 'café' or 'Warschauer Straße' or '€10' or '¡olé!' just worked. Not a great marketing point.
So the first thing you are wondering when you read 'AsciiDoc' is, “Wait, does this mean it doesn't support anything but ASCII characters?”, regardless of whether or not that is true.
I think preventing. I don't think Ruby is a bad language, but I've never worked anywhere it was a first or even second class language. I like AsciiDoc, but it's a hard sell to convince people to manage an entire other language toolchain used for nothing but AsciiDoc. I don't think the distro packaged it, or maybe not a recent enough version, but I could be wrong.
It's already hard enough to get people to switch documentation formats, needing to manage another language for it is just a bridge too far everywhere I've worked. It would be an easier sell if it were statically compiled, or at least in an interpreted language we already used (Python or JS most places).
Sorry, I know this sounds like a stupid question… But I search the linked quick guide as well as the features page, but does this only support ASCII and not UTF characters?
I use both and I use them for different purposes. I use org-mode to stay organized, track todo's, keep notes, etc. I use AsciiDoc to express myself to others, write documentation, and write blog posts. Certainly there is some degree of overlap between the two, but I, personally, don't find org-mode great for writing content to show to others, where-as AsciiDoc is designed for that. Also, there is an AsciiDoc exporter so you can turn org-mode content into AssciiDoc.
What I find baffling is that we're in 2025 and people still can't make a decent, simple, interoperable WYSIWYG text editor without that markdown cancer. This crap has to be shoved at everybody's face in almost every good app because some nerds want to read code no matter what. I really despise that crap.
Are you kidding? There are lots of WYSIWYGs of various kinds out there and some of them are decent. You can get them for Markdown, HTML, RTF, and many other formats. But the real common denominator between most apps is text. You could try HTML, but that is much more code-like than Markdown. It would be wildly unreasonable to make text into a binary-only thing that you can only paste into apps that support the particular encoding that you're using.
Some nerds read and write code for a living, and they invented Markdown too, so what are you proposing? This nerd wants to read and write equations too.
As is org-mode. I think Markdown is one of those VHS vs Betamax kind of situations where it was just lucky to get the traction that its competitors didn't.
That is a bad analogy, as VHS won through pure technological superiority (it was able to record a standard length TV program without you having to sit in front of the device to switch the cassette in the middle).
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
reply