asciidoc: an awesome markdown alternative - ivo's awfully random tech blog

Yesterday while reading through the twitters, I came upon a reference to a markup format called AsciiDoc which I had never heard about before.

Oh wow. Just read up on asciidoc and asciidoctor and woooow. This just made my life. Mind. Blown.
— Ivo Anjo (@KnuX) October 21, 2017

I started reading about both AsciiDoc and the AsciiDoctor tool and they completely blew my mind, so I immediately decided that I had to write a blog post about it --- Using AsciiDoc, of course!

Awesome AsciiDoc+AsciiDoctor features

So if you already are comfortable with Markdown, why should you care?

Here are some of the features that really impressed me:

Generating a table of contents: A table of contents can be automatically generated based on your document structure. You can control where a ToC is placed, how many subsection levels to include, and even its title.

Including files in a document. You can use this to:

Split up your document into multiple files and then include them all to create a single final output
Include data from an external csv and render it as a table

Including verbatim source code from source files. You can even slice the file by tags or by lines.

For instance, here’s the source code for this itemized list thus far, directly embedded from the post source file (not copy-pasted!):

* http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[Including files in a document]. You can use this to:

** http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[Split up your document into multiple files and then include them all to create a single final output]

** http://www.methods.co.nz/asciidoc/newtables.html[Include data from an external csv and render it as a table]

** Including verbatim source code from source files. https://mrhaki.blogspot.co.uk/2014/04/awesome-asciidoc-include-partial-parts.html[You can even slice the file by tags] or https://mrhaki.blogspot.co.uk/2014/08/awesome-asciidoc-include-only-certain.html[by lines].

Callouts in source code:

def foo
  begin
    raise 'Hello, world' # (1)
  rescue => e
    puts 'Rescued!' # (2)
  end
end

This will raise a StandardError
This will stop the exception from propagating

Note/tip/warning/etc blocks
Counters: Each (1) time (2) you (3) include (4) {counter:some_name} a number gets printed and incremented.
Footnotes ^[1]
^Super and _subscript text
Custom substitutions! You can define a substitution :version: 1.0.0 and then use it in links https://rubygems.org/gems/warm-blanket/versions/{version} and in the text “Latest stable version is {version}” and then they’ll get automatically replaced:
- Latest version is 1.0.0, link https://rubygems.org/gems/warm-blanket/versions/1.0.0
You can add comments without needing to cheat by using html ;)

Using AsciiDoc

AsciiDoc documents use the file extension .adoc. Most text editors already ship with or have third-party plugins to perform syntax highlighting.

But yeah, so there’s lots of fancy features, but Markdown is already everywhere… isn’t it?

The best news is that AsciiDoc is the most widely-supported format you’ve never heard about:

You can use it on GitHub and on GitLab. Yes, really: https://github.com/Talkdesk/warm-blanket/blob/master/README.adoc
You can use it with the jekyll website generator (and many others). In fact, you’re looking at jekyll-asciidoc's output right now!
You can use it together with gitbook to write awesome documentation
You can convert it to html, docbook, and many other formats
You can use asciidoctor’s markdown compatibility to ease your transition
You can convert your existing Markdown content to AsciiDoc automatically
You can edit it with live preview online. And it even supports collaborative editing, woohoo!

Go forth and explore!

I hope I was able to share some of my enthusiasm about AsciiDoc with you!

If you want to learn more, I suggest starting with:

1. This is an example footnote!