Tools for Working with AsciiDoc Files

AsciiDoc vs Asciidoctor

The Solr Ref Guide is written in AsciiDoc format. This format is generally considered an extension of Markdown, because it has support for tables of contents, better table support, and other features that make it more appropriate for writing technical documentation.

We are using a version of the AsciiDoc syntax along with tools from an open source project called Asciidoctor. This provides full support for the AsciiDoc syntax, but replaces the original Python processor with one written in Ruby. There is a Java implementation, known as AsciidoctorJ. Further extensions from the original AsciiDoc project include support for font-based icons and UI elements.

Helpful Tools

You can write AsciiDoc without any special tools. It’s simply text, with familiar syntax for bold (*) and italics (_).

Having some tools in your editor is helpful, though.

Doc Preview

This allows you to see your document in something close to what it might appear like when output to HTML.

The following information is from http://asciidoctor.org/docs/editing-asciidoc-with-live-preview.

  • Atom has AsciiDoc Preview, which gives you a panel that updates as you type. There are also a couple of other plugins to support AsciiDoc format and auto-complete.

  • There is a Live Preview browser plugin for Chrome, Firefox and Opera which allow you to open your AsciiDoc page in the browser. It will also update as you type.

  • There is also an Intellij IDEA plugin to support AsciiDoc format.