Features

Asciidoctor is written in Ruby, which means it must be run on a Ruby language runtime (including JRuby). But that’s its only requirement. Asciidoctor is packaged and distributed as a gem named asciidoctor to the package repository at RubyGems.org. The gem can be installed on any operating system that Ruby supports using Ruby’s package management tools (gem or bundle). Asciidoctor itself has no dependencies.

But what if you aren’t familiar with Ruby or, for whatever reason, prefer not to install it? No problem! Thanks to AsciidoctorJ and Asciidoctor.js, you can run the same exact version of Asciidoctor on a Java Virtual Machine (JVM) or JavaScript runtime, respectively. That means you don’t need a Ruby runtime installed on your machine after all. AsciidoctorJ uses JRuby internally, whereas Asciidoctor.js relies on a Ruby-like runtime written in JavaScript.

Whether you’re working in Ruby, Java, or JavaScript, Asciidoctor is readily available for you to start using. Only when you get into add-on converters and extensions do you need to install dependencies.

Asciidoctor provides a nice out-of-the-box HTML experience, complete with a default stylesheet and built-in integrations like Font Awesome (for icons), Highlight.js (for source highlighting), and MathJax (for STEM processing). When you’re just getting into using AsciiDoc for writing, Asciidoctor’s HTML output should be sufficient for all of your publishing needs.

The following before and after picture gives you an idea of what to expect:

If you’re looking for more advanced output, or you have an existing DocBook toolchain in place, you can instead convert to DocBook and feed the result into that pipeline. Once you get more familiar with AsciiDoc and Asciidoctor, you can explore customizing the built-in converter using templates or using add-on converters to produce other output formats such as PDF and EPUB 3. So there is plenty of room to grow.

Asciidoctor provides converters for three output formats by default: HTML 5, DocBook 5, and man page (short for manual page). These converters are designed to cover a majority of users’ needs for basic preview and publishing.

The HTML converter provides a result you can publish the web straight away without any tweaking. The DocBook converter allows you to leverage an existing publishing toolchain or migrate the content to a different authoring format (without the tool needing to know how to parse AsciiDoc). The man page converter drastically lowers the barrier to making system help files.

But it doesn’t end there. The converter interface in Asciidoctor is an extension point. That means it can be used to create converters for any output format imaginable. And there’s an ecosystem of additional converters already available in the Asciidoctor project. You can find converters for creating PDF, EPUB 3, Reveal.js slides, and more from AsciiDoc. Asciidoctor also provides advanced docinfo support for injecting colophon (such as content scripts) into the header and footer of the output file.

A single input format, AsciiDoc, gains you a plethora of output formats.

While Asciidoctor provides a built-in converter for producing publish-ready HTML, all the HTML that Asciidoctor generates can be changed. There are two ways to modify the HTML that Asciidoctor produces: a custom converter or converter templates.

If you’re an experienced programmer, you may lean towards the custom converter. You can extend the built-in HTML converter and override the methods that handle the conversion for any node in the document tree.

If your expertise is more on the technical writing side, you may find the converter templates to be more approachable. The templates can be written in any template language supported by the Tilt template abstraction library, such as ERB, Haml, or Slim. These templates augment the built-in converter by replacing the processing for a node in the document. You introduce one template for each type of node for which you want to control conversion. Templates allow you to apply logic around chunks of HTML (or HTML-like) markup.

Just know that if the HTML that Asciidoctor produces isn’t working for you, you can change it.

If you’re writing technical documentation that presents snippets of source code or configuration, you can enhance the display of those source blocks using syntax highlighting (aka source highlighting). Syntax highlighting is the practice of colorizing (or otherwise emphasizing) keywords and syntax elements in a structured programming or configuration language. Here’s an example to give you an idea:

Asciidoctor provides adapters for several popular syntax highlighters, including Rouge and Highlight.js. Aside from installing the library (if necessary), all you need to do is set a document attribute on your document and Asciidoctor will handle the rest. From there, you can configure the behavior of the syntax highlighter, such as changing the style/theme, enabling line numbers, and block highlighting select lines.

Asciidoctor offers two interfaces for processing AsciiDoc content: a commandline interface (CLI) and an application programming interface (API).

The CLI is designed as a simple tool for non-programmers who want to convert AsciiDoc without having to write a program or for converting content in an automated environment such as CI. Many of the processing options are accessible from the CLI using option flags. When you’re first starting out with Asciidoctor, you’ll mostly likely interact with it via the CLI. Although the CLI itself does not require any programming, it can still load extension code that augments processing.

The API is designed for programmers who want to take their AsciiDoc processing further. Like with the CLI, you can use the API to convert documents. But it’s not all about conversion to an output format. Asciidoctor parses and converts the source document in discrete steps. This makes conversion optional and gives programs the opportunity to extract, add, or replace content in the document by interacting with the document object model. Or you may want to leverage the ability to convert to an embedded document for integrating with other applications, such as a static site generator. The API also provides an extension SPI that you can use to augment the processor, such as to introduce new syntax, mutate the parsed document before conversion, or tweak the output after conversion.

Both the CLI and API have the ability to process both AsciiDoc files and AsciiDoc source passed in as a string.

No coverage of Asciidoctor would be complete without mention of its speed. Asciidoctor is about as fast as any program that runs in Ruby can be. It can load, parse, and convert a 100K AsciiDoc document in about a tenth of a second (~ 1MB/s). That’s more than 100x as fast as AsciiDoc.py, the original AsciiDoc implementation.

Asciidoctor’s speed is good news for developer productivity and good news for server-side applications that need to convert AsciiDoc markup. It also means that preview tools like the browser extension can present a preview of the AsciiDoc content in HTML in near real time.

Asciidoctor also has the ability to run securely by offering several security (aka safe) modes. By using one of these safe modes, you don’t have to worry about the processor accessing sensitive files or even the file system in highly secure environments. In addition to its performance, these security levels make Asciidoctor well-suited for server-side deployments.

Installing Asciidoctor is just the beginning of your publishing experience. Asciidoctor gives you access to a healthy ecosystem of extensions and tools, ranging from add-on converters, to extended syntax, to build plugins, to integrated writing and preview environments.

One popular extension is Asciidoctor Diagram. When loaded, Asciidoctor Diagram allows you to make diagrams from plain text (much like AsciiDoc does for writing). Asciidoctor Diagram does this by extending the syntax of AsciiDoc to recognize specially marked literal blocks. It takes the text inside those blocks, passes it through one of the diagramming tools it integrates with, and reinserts the image back into the document as it is being processed. The result is that the diagram source in the AsciiDoc document becomes an image in the generated output.

Another popular tool is the browser extension. When this extension is installed, you can browse to an AsciiDoc file on your local storage or on the web and the browser will show you the converted HTML instead of the AsciiDoc source. That means you can get the out-of-the-box HTML experience that Asciidoctor provides without even having to run a command or script. The extension running in the browser does everything for you.

These are just two examples. There are plenty more possibilities to explore in the ever-growing Asciidoctor ecosystem. All the components of this ecosystem work together to achieve one goal, to make writing in AsciiDoc a rewarding and productive experience.