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
The Toolchain for My iOS Book - AsciiDoc and the Joy of Text
AsciidocFX - Asciidoc text editor with live preview and syntax highlighting for Windows, OS X, Linux (Java-based)
GitHub's Atom text editor has asciidoc-preview for HTML preview and language-asciidoc for syntax highlighting
Adobe's Brackets text editor has Live Preview of AsciiDoc for Adobe Brackets (after installing, press the new "AD" icon at top right to activate live preview window)
[Mac] Asciidocを書くエディタとプレビューの設定 - Steps for getting syntax highlighting and live preview with Sublime Text, Marked, and Asciidoctor
AsciiDoc
Asciidoctor
Asciidoctor Stylesheet Factory - Themes for Asciidoctor output
Site Made With Asciidoctor - "This site was made only using Asciidoctor and with one command."
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