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 :toc: :numbered: == Hello, world! === Python [source,python] print "Hello World" === Ruby [source,ruby] puts "Hello, World!"
into this (CSS has been removed and a light grey background applied; by default, output is much prettier):
Table of Contents
print "Hello World"
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).
"Use 'asciidoc' for document markup. Really. It’s actually readable by humans, and easier to parse and way more flexible than XML." -- Linus Torvalds in a reply to his Google+ post
"If Markdown is a 1st-grader, then AsciiDoc is [a] PhD student." -- Dan Allen in a Google+ post
Living the Future of Technical Writing "The issue with Markdown was that it was too simple. It didn’t specify things like table formatting, cross references, indexing, callouts, source code examples, etc. All of which Asciidoc does in a format that is just as easy to write."
And for everything else, there's AsciiDoc.0 "For an extra five minutes learning you get a boatload (think container ship) more features1 - it compiles to DocBook: a mature, actually standardised, highly structured format, and from that you get HTML, EPUB, PDF, slideshows, and man pages for free.0 For math you get MathML, ASCIIMath, and LaTeX (along with a number of ways to render them.) It has a super nice syntax, is equally good at little docs and huge books, and you could theoretically write a proper academic paper in it with the LaTeX backend. And you always know what's going to happen when you try to mix bold and italic... Also endorsed by Linus.2
AsciidocFX - Asciidoc text editor with live preview and syntax highlighting for Windows, OS X, Linux (Java-based)
Asciidoctor Stylesheet Factory - Themes for Asciidoctor output
On PDF output: "If you want to publish HTML, it’s great. For PDF the current way to go it is to compile to DocBook and from DocBook to PDF."
According to the documentation, "Asciidoctor still supports the attribute name 'numbered' to number sections for backward compatibility with AsciiDoc Python, but the name 'sectnums' is preferred." However, I could only get section numbers to appear by using :numbered:, not :sectnums:.
/misc | Sep 26, 2015
Subscribe or visit the archives.