tinyapps.org / blog

Asciidoc(tor)! Where have you been all my life?! #

I love documenting, but loathe the tedious process of trying to manually markup the logical structure in HTML, as evidenced by these inconsistent pages:

I began a futile search for a Markdown editor that could automatically generate section numbers and a table of contents. Next I tried "software for technical writing" which turned up some promising tools. But it wasn’t until I tried searching for

    text editor "table of contents" "section numbering"

that I finally hit the jackpot on page 2 of the search results:

Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook 5 (or 4.5) and other formats.

It turns this:

= Learn 2 Languages in 2 Seconds

== Hello, world!

=== Python

print "Hello World"

=== Ruby

puts "Hello, World!"

into this (CSS has been removed and a light grey background applied; by default, output is much prettier):

Learn 2 Languages in 2 Seconds

Table of Contents

1. Hello, world!

1.1. Python

print "Hello World"

1.2. Ruby

puts "Hello, World!"

Last updated 2015-09-25 20:50:26 HST

Where has this been all my life?!

Exactly what I was after - crazy-simple syntax with automatic section numbering and TOC generation (bonus: it also inserts "Last updated date time" at the bottom).

Quotes & Articles

Editing & Preview

Manuals & Reference

Notes & More

/misc | Sep 26, 2015

Subscribe or visit the archives