Skip to content(if available)orjump to list(if available)

Markdown's Big Brother: Say Hello to AsciiDoc

Markdown's Big Brother: Say Hello to AsciiDoc

27 comments

·February 6, 2025
Visit

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.

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.

pindab0ter

Markdown being so ubiquitous is what makes it valuable, IMO. Do you think AsciiDoc has the potential to reach that point as well?

ffaser5gxlsll

[dead]

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.

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

Symbiote

AsciiDoctor also has an AST intermediary which can be used by plugins/extensions.

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.

poisonborz

Unfortunate naming. When most devs think of "ascii" they think "oh that character encoding you shouldn't use anymore"

santiagobasulto

I agree. The first time I heard the name I had the same impression.

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.

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.

DimuP

Bold, italic and monospace feel like WhatsApp formatting

pindab0ter

Other than inertia, what is keeping AsciiDoc from overtaking Markdown?

Personally I like the ubiquity and simplicity of Markdown, but I can also see the benefits of the features AsciiDoc has to offer.

latexr

> Other than inertia

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?

xeonmc

Ruby.

pindab0ter

What do you mean? Is Ruby helping or preventing AsciiDoc from becoming more widespread?

Y-bar

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?

Symbiote

It supports all Unicode.

That would be obvious, except for the name.

ognyankulev

I was hoping Eclipse AsciiDoc would already deliver stable spec, TCK and (new) reference implementation: https://asciidoc-wg.eclipse.org/projects/

stragies

Is there anybody here, who migrated to AsciiDoc from ORG-Mode, and could detail the reasons?

sausagefeet

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.