Markdown's Big Brother: Say Hello to AsciiDoc | Hacker News Reader

Markdown's Big Brother: Say Hello to AsciiDoc

git-tower.com

101 pointspointnova63 comments

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

It's a bit more effort but it just can't be beat for documentation.

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.

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

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.

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

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.

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.

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

Does anyone know a JS renderer that supports custom directives?

markdown-it?

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.

It seems the maintainer is willing to implement it but lacks the time. Perhaps a PR would be in order.

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.

Do you also use it for company docs, policies etc, or only for software documentation? Would love to see the back of Word.

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!)

[0] https://oxide-and-friends.transistor.fm/episodes/rfds-the-ba...

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.

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

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

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.

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.

https://commerce.nearform.com/open-source/spectacle/docs/api...

https://typst.app/

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

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

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.

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

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

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

ASCII makes up 90% of all digital text; UTF-8 makes up the other 90%.

The fraction of people who have heard of ASCII is steadily shrinking so you need not worry!

Markdoc (https://markdoc.dev/) really had me excited, but I'm not sure it aspires to be all that I hoped it would.

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.

Ruby.

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

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

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

The name doesn't help.

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.

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.

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?

It supports all Unicode.

That would be obvious, except for the name.

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

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.

Bold, italic and monospace feel like WhatsApp formatting

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.

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.

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.

Congratulations, you've reinvented HTML 1.0! With if/else you're almost at DHTML.

What exactly is your comment about? Have you heard about asciidoc before?

AsciiDoc is even older than Markdown.

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.

Org-mode failed with hyperlinks and images:

    [[https://123.com][Description]]

is way more cumbersome than Markdown's:

    [Description](https://123.com)

I find the use of a single type of bracket to be less cumbersome than Markdown's variant. The two extra characters don't bother me.

I think my main hangup is that the thing I wish to markup is preceded by the link, instead of succeeded by it

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

Only technically.

By that name, yes, but much of Markdown was "discovered" rather than invented, having been used in email/newsgroups/... for a long time.

Those parts apply equally to both languages.

Reply on news.ycombinator.com