TechCast #83 – Andres Almiray on AsciiDoc and Markdown

Tags: , , , , , , , ,

My guest is Andres Almiray, who has been on our podcast way back in episode 41 discussing Groovy Griffon.  I’ve invited him back again, discussing text-based documentation markup formats with me.  I’ve been a user of Markdown in various incarnations for a while now, but when I saw him tweet about his interest in AsciiDoctor, a ruby-based tool to convert the newer asciidoc format to various output formats, I was interested.


Formats Discussed



Major features of AsciiDoc

  • TOC automatically defined – include sections in order = right TOC
  • Inclusion of documents
  • Can embed production code into your documentation (he’s using it in the Griffon Guide) – this can be in the test sources for example… They build docs when test cases are green…
  • Can re-arrange indentation
  • Can include lines n:m
  • Code comments – specify tags – they get included as annotations – include this tag – that portion of tagged code can be included only

AsciiDoctor – custom extensions

  • One specifically targeting Java – know you are including a Java class file – or method name – extension parses code, builds AST, then includes the code even if the method moves around
  • Caliphs and callouts – nice highlights inside snippets – reference into captions.
  • AsciiDoc Can write document as it were a book – target a book layout – sections and parts, etc… Not built in to the Markdown format – must use a tool like Pandoc for this.
  • Javadoc support – from AsciiDoctor – a JavaDoc doclet to convert JavaDocs to printable documentation

Text Transformation Tools

  • Markdown via Pandoc to PDF, Word, Docbook for manuals (supports printable slide counts, etc).
  • Markdown support in Reveal.JS for slide content.
  • AsciiDoctor support to convert to DocBook format for publisher output
  • Gaiden – a markdown static website content tool
  • Grain – supports Markdown and Asciidoc and converts to static content
  • jBake (asciidoc) – compares to jeckyll for markdown (ruby)  – a multi-format (Markdown, AsciiDoc and HTML) content site generator



  • The old classic vim is all you need
  • Mou – mac side-by-side preview/content pane editor
  • Markdown Pro – an alternative Markdown editor
  • OxygenXML – if you’re in Docbook-land, it’s a WSYWIG editor for Docbook. HIGHLY recommended but costs $$$$.
  • XmlMind – alternative, free tool for editing DocBook