July 2, 2015 — asciidoc markdown

'(From Markdown to Asciidoc)

UPDATE 2017: I’m going to move everything to org-mode or Markdown since I’m no longer finding the case for adoc compelling enough.

Markdown has become the de facto standard for plain text syntax. It’s supported in the webform editors of Stack Overflow, Github, and many blogs, wikis, and forums. It’s built into most static site generators. You can even use it to write a book. It’s fantastic that it has raised awareness of text-based markup, but it’s not enough.

Asciidoc fills in many of the shortcomings of Markdown. Here’s a cheat-sheet to give you a feel for its syntax. It’s almost as simple as Markdown, and thus quick to learn.

Markdown Shortcomings

You’re probably aware of most of these, but maybe don’t notice the pain as much as you should.

Comments are clumsy. And multi-line becomes a mess.

Vim ends up loading its HTML syntax which clutters functionality and causes confusion.

No good way to add extra markup without dropping into HTML.

No tables, citations, footnotes, or sub-/super-scripting.

Inferior to Asciidoc’s Docbook toolchain.

Asciidoc Extras and General Niceties

Consistency of section delimiters. All are four characters and delineate blocks: line-wise pairs of quadruples - (code), _ (quote), / (comment), = (caption), + (pass-through HTML).

Titles can be added to most sections.

Auto-up-converting of some punctuation, like the pedant’s apostrophes — and yes, even dashes.

You can add anchors.

Auto-generated Table Of Contents.

Markdown-to-Asciidoc Conversion Guide

Headings

Markdown:

## Foo

Asciidoc:

== Foo

Links

Markdown:

[This is Google](http://google.com)

Asciidoc:

http://google.com[This is Google]
link:/relative-page[some relative page]

The Asciidoc feels more natural to me. My first instinct when inserting a link is to insert the link itself. It’s also nice to avoid the parens. Also, I often will type a paragraph that has a few things that need to be linked after the fact. It’s really easy to paste the link just before the text in Asciidoc.

Images

Markdown:

![Mittens is my fave](/img/kitty1.jpg "My Cat")

Asciidoc:

image:/img/kitty1.jpg[My Cat]  Mittens is my fave] "My Cat")

Comments

Markdown:

<!-- just a comment -->

Asciidoc:

// just a comment

or multi-line (yay!):

////
a bunch
of comment
lines
////

Code Fragments

Markdown:

    This is indented, yet subtle and easily mishandled when mixing with lists.

Asciidoc (weird but easy enough):

  ----
  This is left-aligned, or wherever you want. It is explicit.
  ----

Asciidoc also supports Markdown-style indents, but I’m finding that being explicit is less susceptible to ambiguous translating.

HRs

Markdown:

  ----

Asciidoc (weird but easy enough):

  ''''

Definition lists

Asciidoc is much richer, and not significantly harder to learn.