Asciidoc: Markdown on steroids.

Asciidoc Logo

I used to write my stuff in Word.

Then I started writing my stuff in Scrivener.

Then I split my writing between Scrivener (novels) and Ulysses (everything else).

But I’ve always had a slight problem with both of them: it was the markup.

Ulysses uses Markdown – or rather its own subset of Markdown. It can handle basics like bold and italics, and at punch, it does a fairly good job with stuff like footnotes (pretty useful if you’re writing academic papers). Table support has been a weak spot as old as Ulysses itself: it just can’t do ‘em, even though every other Markdown editor supports them. Still, most novels don’t need tables, so it’s hardly a dealbreaker if you’re writing the next great American novel. What’s important is that it saves your work in the Markdown format: it’s purely text-based so is portable, a good fit for collaborative work, and is great for version control systems.

On the other lawn, we have Scrivener, which stores everything in RTF format.

Now, the problem I have with RTF is probably just my own ageism: RTF is old. It’s the format Microsoft used for word processing when the world was a twinkle in the eye of the cosmos. Things have moved on; Microsoft certainly has. So while there is nothing lacking with RTF, I don’t like keeping stuff in a dead format, especially one that’s kind of … opaque.

I still felt like Markdown was the right direction, but it needed more … and the ‘more’ came along with Asciidoc. Asciidoc is very similar to Markdown; it uses character-based markup to attach semantic meaning to your writing. So what does that mean? Well, instead of selecting text with your mouse and hitting Bold on your toolbar, you just surround the bits you want in bold in asterisks:

*I want this line in bold*

And you can do the same thing with italics; you just use the underscore characters.

_And I want this line in italics_

Okay, so far, that’s pretty much the same as doing stuff in Markdown, but the difference comes when you look at their respective origins: Markdown was designed to make it easy to build web pages without having to deal with complicated HTML markup. Asciidoc was designed to build complicated technical documentation without having to deal with complicated XML. Asciidoc had the harder job to begin with, which is probably why it is has a much richer feature set: we have complex table layouts, table of contents, admonitions, footnotes, parameterised file inclusion, conditional text …

Yeah, that reads like a load programmer speak, which it probably is. If you’re interested though, you can find out a lot more if you follow the jump –> https://asciidoctor.org/docs/asciidoc-writers-guide/

Join in…