Asciidoctor 0.1.3 released!

by Sarah White and Dan Allen -

We’re thrilled to announce the release of Asciidoctor 0.1.3.
Read Installing or Updating Asciidoctor to learn how to get it setup.

Asciidoctor is an open source text processor and publishing toolchain written in Ruby for converting AsciiDoc markup into HTML 5, DocBook 4.5 and custom formats. Asciidoctor is written in Ruby, but available to any JVM language using the Java integration library.

This release marks an important milestone. It’s been exactly 6 months since Dan picked up Asciidoctor and started driving it forward. The project sure has come a long way since then. With this release, we’ve moved past just implementing AsciiDoc to advancing it, as this post highlights.


The focus of this release cycle was on:

  • AsciiDoc compliance (yes, still)

  • New shorthand syntax and macros

  • Improved styles

  • Markdown compatibility

  • Bug fixes

The valuable feedback we’ve received has helped bring Asciidoctor to 99.5% compliance with the AsciiDoc syntax and key parts of the Markdown syntax. The improvements have given Asciidoctor a 10% boost in speed over the previous release, nearly 40x as fast as the native AsciiDoc processor.

This document covers most of the new and noteworthy fixes and enhancements. Here’s the TL;DR version if you’re in a hurry.

  • File encoding and Windows path bugs fixed!

  • Haml/Slim/Jade-inspired syntax for defining the id and role for block content

  • Shorthand syntax to set the table format using the first position of the block delimiter

  • Alternate "air quotes" delimiters for defining block quotations

  • Support for Markdown blockquotes and headings (to join fenced code blocks)

  • Font-based admonition icons powered by Font Awesome and CSS-based callout icons

  • Linked section titles as floating anchors or linked title text

  • Target window and role (i.e., CSS class) attributes for links

  • Option to use google-code-prettify to highlight source code blocks

  • Attributes resolved in target of include macro

  • Control over block indentation of included content

  • Sidebar placement for table of contents (toc2)

  • Macros for keyboard shortcuts, menu selections and UI buttons (experimental)

  • Table of contents honors numbered setting for section titles

  • Inline doctype for rendering simple, unstructured content

  • Shorthand syntax for passing attributes to the Asciidoctor API

  • General style improvements in default stylesheet

  • Updated asciidoc.conf compatibility configuration

  • 1,000+ tests in the test suite

  • Over 40 issues resolved

Read on to learn about these great improvements!

Write faster with new shorthand syntax!

Shorthand notation for setting id and role block attributes

In the spirit of Haml, Jade, and Slim, Asciidoctor allows you to assign the id and role attributes on a block using attribute shortcuts. This shorthand syntax is useful for creating presentations with AsciiDoc, where lots of style classes in the markup are needed.

Consider the following AsciiDoc markup:

* Goal 1
* Goal 2

In Asciidoctor, this can now be written as:

* Goal 1
* Goal 2

The # prefix is recognized as shorthand for id=, and the . prefix is recognized as shorthand for role=.

Both source snippets produce the following HTML:

<div id="goals" class="ulist incremental">
<li><p>Goal 1</p></li>
<li><p>Goal 2</p></li>

This shorthand notation is part of a block’s style. Thus, it leverages the first attribute position to its fullest extent.

Let’s say you want to create a blockquote from an open block and assign it an id and role. You prepend the style quote to the # (id) and . (role) in the first attribute position, as this example shows:

[quote#roads.dramatic, Dr. Emmett Brown]
Roads? Where we're going, we don't need roads.

That produces the following HTML:

<div id="roads" class="quoteblock dramatic">
<div class="paragraph">
<p>Roads? Where we're going, we don't need roads.</p>
<div class="attribution">
&#8212; Dr. Emmett Brown

Here are some other things to know about this notation:

  • To specifiy multiple roles using the shorthand syntax, separate them by dots

    For example, [.summary.incremental] emits the HTML attribute class="summary incremental".

  • The order of id and role values in the shorthand syntax does not matter

    For example, [#goals.incremental] and [.incremental#goals] produce the same output.

Learn more in the Asciidoctor Docs: block attributes

Shorthand notation for setting csv and dsv table formats

The first position of the table block delimiter (i.e., |===) can be replaced by the data delimiter to set the table format.

Instead of specifying the csv format using a block attribute, as shown here:


you can simply replace the leading pipe (|) with a comma (,):


In the same way, the dsv format can be specified by replacing the leading pipe (|) with a colon (:).


Now, you only need the block attribute list for setting any additional options.

Learn more in the Asciidoctor Docs: tables

Alternate blockquote syntax

Asciidoctor 0.1.3 brings three new syntax variations for marking up blockquotes:

  1. Quoted paragraph

  2. Air quotes

  3. Markdown-style

Here’s an example of a traditional AsciiDoc quote block with three parts (quoted text, attribution and source):

[quote, Thomas Jefferson, Papers of Thomas Jefferson: Volume 11]
I hold it that a little rebellion now and then is a good thing,
and as necessary in the political world as storms in the physical.

Here are the three new alternatives.

Quoted paragraph blockquote

You can turn a single paragraph into a blockquote by:

  1. surrounding it with double quotes

  2. adding an optional attribution (prefixed with two dashes) below the quoted text.

"I hold it that a little rebellion now and then is a good thing,
and as necessary in the political world as storms in the physical."
-- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11

Here’s the result of the abbreviated blockquote syntax:

I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.
— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11

Air quotes

Asciidoctor recognizes text between "air quotes" as a quote block. Air quotes are the best thing since fenced code blocks.

[,Lewis Carroll]
If you don't know where you are going, any road will get you there.

This syntax is inspired by the gesture people make with their fingers when quoting someone, such as famously used by Dr. Evil.

Markdown-style blockquotes

Asciidoctor even supports Markdown-style blockquotes:

> I hold it that a little rebellion now and then is a good thing,
> and as necessary in the political world as storms in the physical.
> -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11

This markup renders the same as the example above.

Like Markdown, Asciidoctor supports block content inside the blockquote, including nested blockquotes:

Markdown-style blockquote containing block content
> > What's new?
> I've got Markdown in my AsciiDoc!
> > Like what?
> * Blockquotes
> * Headings
> * Fenced code blocks
> > Is there more?
> Yep. AsciiDoc and Markdown share a lot of common syntax already.

Here’s how this conversation renders:

What’s new?

I’ve got Markdown in my AsciiDoc!

Like what?

  • Blockquotes

  • Headings

  • Fenced code blocks

Is there more?

Yep. AsciiDoc and Markdown share a lot of common syntax already. Just try it.

Learn more in the Asciidoctor Docs: blocks

You often need to set the target attribute on a link element (<a>) so the link opens in a new window (e.g., <a href="…​" target="_blank">).

This type of configuration is normally specified using attributes. However, AsciiDoc does not parse attributes in the link macro by default. In Asciidoctor, you can now enable parsing of link macro attributes by setting the linkattrs document attribute in the header.


You can then specify the name of the target window using the window attribute:[Google, window="_blank"]

Since _blank is the most common window name, we’ve introduced shorthand for it. Just end the link text with a caret (^):[Google^]
If you use the caret syntax more than once in a single paragraph, you may need to escape the first occurrence with a backslash. If the link text contains a comma, then you need to surround the link text in double quotes.

Since Asciidoctor is parsing the attributes, that opens the door for adding a role (i.e., CSS class) to the link:[Google^, role="external"]

Have fun styling your links!

Font awesome icons, fancy section anchors and other style options

You no longer have to carry icons around with you where ever you go! Asciidoctor 0.1.3 introduces Font-based admonition and CSS-based callout icons.

Admonition icons powered by Font Awesome

Icons can make your document look sharp, but they are a pain to manage. That is, until now! Asciidoctor can "draw" icons using Font Awesome and CSS.

To use this feature, just set the value of the icons document attribute to font. Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block.

Here’s an example, starting with the AsciiDoc source:

:icons: font

NOTE: Asciidoctor now supports font-based admonition icons, powered by Font Awesome!

Here’s the HTML it produces:

<div class="admonitionblock note">
<td class="icon">
<i class="icon-note" title="Note"></i>
<td class="content">
Asciidoctor now supports font-based admonition icons, powered by Font Awesome!

And here’s a preview of how it renders:

Asciidoctor now supports font-based admonition icons, powered by Font Awesome!

Asciidoctor adds a reference to the Font Awesome stylesheet, served from a CDN, to the document header. The stylesheet then imports the font from the same server.

<link rel="stylesheet"
The default stylesheet (or any stylesheet produced by the Asciidoctor stylesheet factory) is required for this feature to work.

Learn more in the Asciidoctor Docs: admonition blocks | Asciidoctor stylesheets

CSS-based callout icons

The font icons setting also enables callout icons drawn using CSS.

:icons: font (1)

NOTE: Asciidoctor now supports font-based admonition icons, powered by Font Awesome! (2)
1 Activates font-based icons in the HTML5 backend
2 Admonition block that uses a font-based icon

Kick that icon directory to the curb. You’re untethered!

Two document attributes are available to control section linking:


When this attribute is enabled on a document, an anchor (empty link) is added before the section title. The default Asciidoctor stylesheet renders the anchor as a section entity (§) that floats to the left of the section title.


When this attribute is enabled on a document, the section titles are turned into links. The default Asciidoctor stylesheet displays linked section titles in the same color as normal section titles.

Section title anchors depend on the default Asciidoctor stylesheet to render properly.

Learn more in the Asciidoctor Docs: section titles

Lead paragraph style

Simply apply role="lead" (or .lead) above any paragraph, and it will appear in the style of a lead paragraph (i.e., larger font).

Cleaner quote blocks and verses

If a quote or verse block does not have an attribution, the empty attribution div is no longer displayed in the HTML5 output. This corrects any output styling inconsistencies caused by the empty div.

AsciiDoc quote block syntax without attribution
Words of wisdom.
HTML output using Asciidoctor 0.1.2 and older versions
<div class="quoteblock">
<div class="paragraph">
<p>Words of wisdom.</p>

<div class="attribution">

HTML output using Asciidoctor 0.1.3
<div class="quoteblock">
<div class="paragraph">
<p>Words of wisdom.</p>

The default stylesheet has been updated to follow suit. Additionally, verse blocks have been given a style makeover, so they should appear consistent with the default look and feel.

The stylesheet has also been updated with some new styles for the experimental user input macros.

Return of the Mac(ros): Making it clear what readers are supposed to press

You must set the experimental attribute to enable these macros.

Keyboard shortcuts

Asciidoctor now recognizes a macro for creating keyboard shortcuts following the syntax kbd:[key(+key)*].

For example:

[options="header", caption=""]
.Common browser keyboard shortcuts
|Shortcut |Purpose

|Toggle fullscreen

|Open a new tab

|New incognito window

|kbd:[Ctrl + +]
|Increase zoom

renders as:

Common browser keyboard shortcuts
Shortcut Purpose


Toggle fullscreen


Open a new tab


New incognito window


Increase zoom

You no longer have to struggle to explain to users what combination of keys they are supposed to press.

Trying to explain to someone how to select a menu item can be a pain. With the new menu macro, the symbols do the work.

For example:

To save the file, select menu:File[Save].

Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

The instructions in the example appove appear as:

To save the file, select File  Save.

Select View  Zoom  Reset to reset the zoom level to the default setting.

UI buttons

It can be equally difficult to communicate to the reader that they need to press a button. They can’t tell if you are saying “OK” or they are supposed to look for a button labeled "OK". It’s all about getting the semantics right. The new btn macro to the rescue!

For example:

Press the btn:[OK] button when you are finished.

Select a file in the file navigator and click btn:[Open].

Here’s the result:

Press the OK button when you are finished.

Select a file in the file navigator and click Open.

We are looking for feedback on these macros before setting them in stone. If you have suggestions, we want to hear from you!

A better programmer’s best friend

AsciiDoc is a programmer’s best friend because it keeps your source code close to the documentation and makes inserting source code easy. Now there are even more options for pulling source code snippets into your document and highlighting them.

Normalizing the block indentation of included source code

Source code snippets from external files are often padded with leading block indent. This leading block indent is relevant in its original context. However, once inside the documentation, this leading block indent is no longer needed.

The attribute indent allows the leading block indent to be stripped and, optionally, a new block indent to be inserted for blocks with verbatim content (listing, literal, source, verse, etc.).

  • When indent is 0, the leading block indent is stripped (tabs are replaced with 4 spaces).

  • When indent is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value.

For example, this AsciiDoc source:

    def names
      @name.split ' '


def names
  @name.split ' '

You’ll need this feature when including content:


This AsciiDoc source:

    def names
      @name.split ' '


  def names
    @name.split ' '
The relative indentation between the lines of source code is not affected.

Including files relative to a common source directory

Asciidoctor now expands attributes in the target of the include macro. That means you only have to type the unique part of the path when linking to a source file.


:sourcedir: src/main/java


The target of the include macro resolves to:


Learn more in the Asciidoctor Docs: include macro and blocks

New source highlighter: google-code-prettify

Source code snippets can now be highlighted with the google-code-prettify library.

To use prettify, enable it by setting the source-highlighter attribute in the document header (or pass it as an argument):

:source-highlighter: prettify

Asciidoctor will link to the prettify JavaScript library and stylesheet and emit the HTML prettify requires to highlight the source code.

Consider this source code block:

public class Person {
  private String name;

  public String getName() {
    return name;

Asciidoctor produces the following HTML:

<div class="listingblock">
<div class="content monospaced">
<pre class="prettyprint java language-java"><code>public class Person {
  private String name;

  public String getName() {
    return name;

The key addition is the prettyprint class on the <pre> tag.

Learn more in the Asciidoctor Docs: enabling source code highlighters

Documents with more depth, a bigger picture and mini content

Level 5 section title added

Asciidoctor 0.1.3 includes syntax for the level 5 section title.

===== Level 5 Section Title

The level 5 title maps to the <h6> tag in the html5 backend.

Part headings in HTML backend

Previously, part headings (level 0 sections in a book doctype document) weren’t distinguishable from other <h1> tags. In 0.1.3, these <h1> tags get the sect0 class name to be consistent with the class names assigned to the other section levels. This addition simplifies the effort of adding custom styles to the part headings.

Table of contents layout and style options

Asciidoctor 0.1.3 includes numerous table of contents (TOC) style changes and options.

More table of contents position options

The AsciiDoc toc2 layout is now included in the Asciidoctor default stylesheet as the toc2 class. To use the alternate TOC, specify the document attribute toc2 in the header.

The table of contents can also be inserted directly beneath a document’s preamble. To place the TOC under the preamble, assign the new value, preamble to the toc-placement attribute.

The TOC macro requires the toc attribute to be set. To disable the built-in TOC, unassign the toc-placement attribute (toc-placement!)

Updated level 0 section title styles

Level 0 section titles (only applicable to book doctype) are now organized in their own level within the table of contents (in the HTML backend). A CSS class has been added to each outline level (i.e., <ol> element) that cooresponds to the level of the sections it contains (e.g., sect1level) The addition of these CSS classes make it easier to style the TOC.

In the default stylesheet, the following style changes have been made to the TOC:

  • Level 0 and level 1 section titles are aligned vertically

  • Extra spacing has been added between level 0 and level 1 section titles to make level 0 section titles stand out

  • Level 0 section titles (i.e., parts) appear in italic text

Also, the type="none" attribute has been added to the <ol> elements to provide a hint to the browser not to add a number in front of each item. This change satisfies the requirement that the TOC should "just work" without a stylesheet.

Introducing the inline doctype for inline formatting on input text

There may be cases when you only want to apply inline AsciiDoc formatting to input text without wrapping it in a block element. For example, in the Asciidoclet project (AsciiDoc in Javadoc), only the inline formatting is needed for the text in Javadoc tags.

The rules for the inline doctype are as follows:

  • Only a single paragraph is read from the AsciiDoc source

  • Inline formatting is applied

  • The output is not wrapped in the normal paragraph tags

Given the following input:[AsciiDoc] is a _lightweight_ markup language...

Processing it with the options doctype=inline and backend=html5 produces:

<a href="">AsciiDoc</a> is a <em>lightweight</em> markup language&#8230;

The Asciidoctor processor is now able to cover the full range of output, from unstructured (inline) text to a full, standalone document!

Markdown in your AsciiDoc?

That’s right! Asciidoctor supports three key elements from the Markdown syntax (where AsciiDoc and Markdown don’t already overlap).

  • Headings

  • Blockquotes

  • Fenced code blocks

In addition to the equal marker (=) used for defining single-line section titles, Asciidoctor recognizes the hash symbol (#) from Markdown. That means the outline of a Markdown document will render just fine as an AsciiDoc document.

# Document Title

## Section One


The Markdown-style blockquotes where previously described in Alternate blockquote syntax.

Markdown-style headings and blockquotes join support for fenced code blocks (from GitHub-flavored Markdown), which was added in a previous release.

require 'asciidoctor'

puts Asciidoctor.render("[AsciiDoc] is a _lightweight_ markup language...")

We hope these additions help to ease and encourage migration from Markdown to AsciiDoc. To alleviate concerns about fragmentation from AsciiDoc, we maintain an AsciiDoc configuration file in the project that brings these same enhancements to AsciiDoc when used.

Important bug fixes

The Windows path bug is fixed

Asciidoctor 0.1.3 properly detects the Windows environment and converts all backslashes to forward slashes. This eliminates file path resolution errors in Windows. Resolves issue 330.

File encoding errors when using Ruby 1.9 and above is fixed

Asciidoctor was not properly setting the encoding on data read from files when the default system encoding was not UTF-8. To correct this issue, any data that comes into Asciidoctor 0.1.3 is force encoded to UTF-8 on Ruby 1.9 and above. Resolves issue 308.

Additional bug fixes

  • The Asciidoctor CLI no longer splits attribute key/value pairs on the first equal sign. Resolves issue 291.

  • Asciidoctor no longer crashes if to_file and base_dir are both set. Resolves issue 335.

  • DocBook renderer works if the author is defined using document attributes. Resolves issue 301.

Compliance fixes

doctitle attribute

The doctitle attribute can be used anywhere in a document. It’s value is identical to the value returned by Document#doctitle.

AsciiDoc doctitle syntax
= Document Title

The document title is {doctitle}.
doctitle output result
The document title is Document Title.

Horizontal layout for labeled lists added to DocBook 4.5 backend


first term:: definition
more detail

second term:: definition


<informaltable tabstyle="horizontal" frame="none" colsep="0" rowsep="0">
<tgroup cols="2">
<colspec colwidth="15*"/>
<colspec colwidth="85*"/>
<tbody valign="top">
<simpara>first term</simpara>
<simpara>more detail</simpara>
<simpara>second term</simpara>

Consecutive terms in labeled list share same varlistentry

Consecutive terms in a labeled list share the same varlistentry in the docbook backend.


alt term::


alt term

Special sections and styles

The partintro and abstract styles can be used on open blocks and are handled correctly by the renderer.

Sections assigned the glossary and appendix styles are now handled correctly in Asciidoctor.

Assign document variables inline

Document variables can be assigned using the following syntax:


For example:


It’s effectively the same as:

:sourcedir: src/main/java

This is important for being able to assign document attributes in places where attribute entry lines are not normally processed, such as in a table cell.

An example of where this might be used is documented in the how to set the background color of a table cell tip.

Block title not allowed above document title

Previously, a block title line above a level 0 heading was being processed and passed on to the first content block. AsciiDoc sees the block title as the first line of content and does not create a header as a result. Asciidoctor’s behavior is now consistent with AsciiDoc.


.Misplaced block title
= Document Title
Author Name

The following input is now rendered as a link.


CLI and API updates

Specify any backend with the Asciidoctor CLI

Previously, the Asciidoctor CLI restricted the user from specifying a backend other than html5 or docbook45. Now, any non-empty value can be specified as the backend. This is critical when you want to use a custom backend, such as deck.js or dzslides.

Set safe mode with a string, symbol or integer in the Asciidoctor API

The safe level option now accepts a symbol, string or integer value to lookup the safe level.

result = Asciidoctor.render_file('', :safe => 'server')

can now be written as:

result = Asciidoctor.render_file('', :safe => :server)

Use a string or symbol to set the backend in the Asciidoctor API

The backend option now accepts a symbol or string value.

result = Asciidoctor.render_file('', :backend => 'docbook')

can now be written as:

result = Asciidoctor.render_file('', :backend => :docbook)

Pass attributes as a string or array to the Asciidoctor API

Previously, attributes were passed as a Hash to the Asciidoctor API methods. At times, this made the argument list feel heavy. These methods now accept the attributes as a string or array.

For instance, consider a user wants to pass the attribute that enables the table of contents (toc) and auto-numbering (numbered). Previously, that required:

result = Asciidoctor.render_file('',
    :attributes => {'toc' => '', 'numbered' => ''})

Since both attributes are simple flags, the invocation can be simplified as:

result = Asciidoctor.render_file('',
    :attributes => ['toc', 'numbered'])

It can be further simplified using the array-from-string shorthand in Ruby:

result = Asciidoctor.render_file('',
    :attributes => %w(toc numbered))

That leads us into attributes specified as a string:

result = Asciidoctor.render_file('',
    :attributes => 'toc numbered')

That’s quite an improvement over the original call.

If the attribute requires a value, such as source-highlighter, you just use the key=value form:

result = Asciidoctor.render_file('',
    :attributes => 'toc numbered source-highlighter=coderay')

This API call parallels this commandline invocation:

$ asciidoctor -a toc -a numbered -a source-highlighter=coderay master.adoc

This enhancement is particularly useful in the integrations, such as the Gradle plugin.

Learn more in the Asciidoctor Docs: Asciidoctor Ruby API | Asciidoctor Java API

And that’s a wrap!


As we hoped, Asciidoctor 0.1.2 downloads broke into the next increment of 10,000. was reporting over 20,000 downloads of the Asciidoctor gem prior to this release and Maven Central over 100 downloads of the Java integration. We look forward reaching new landmarks with 0.1.3.

The level of participation in the Asciidoctor project continues to grow at an impressive rate. We welcomed several new projects in this development iteration, including Asciidoclet, a Javadoclet for writing Javadoc in AsciiDoc by John Ericksen, as well as several AsciiDoc editor initiatives. We’re very grateful to everyone who participates, especially those who contribute and spread the word :)

We’d especially like to thank the following people for their contributions and feedback on this release:

A special shout out to Brian Leathem for finding a critical regression the night before the release.

Additional thanks goes to everyone who is using the project and has contributed to it. Together, we’re making documentation fun, easy, and rewarding!

What’s next?

This release is just the beginning of the release train. Look for releases of the Java integration, Maven plugin, Gradle plugin and more recent additions such as the editors.