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:

In Asciidoctor, this can now be written as:

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

Both source snippets produce the following HTML:

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:

That produces the following HTML:

Here are some other things to know about this notation:

Learn more in the Asciidoctor Docs: block attributes

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

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

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

Here are the three new alternatives.

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:

Since _blank is the most common window name, we’ve introduced shorthand for it. Just end the link text with a caret (^):

Since Asciidoctor is parsing the attributes, that opens the door for adding a role (i.e., CSS class) to the link:

Have fun styling your links!

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:

Here’s the HTML it produces:

And here’s a preview of how it renders:

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.

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

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

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

Two document attributes are available to control section linking:

Learn more in the Asciidoctor Docs: section titles

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

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.

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.

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

For example:

renders as:

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:

The instructions in the example appove appear as:

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:

Here’s the result:

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

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.).

For example, this AsciiDoc source:

Produces:

You’ll need this feature when including content:

This AsciiDoc source:

Produces:

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.

Example:

The target of the include macro resolves to:

Learn more in the Asciidoctor Docs: include macro and blocks

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):

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:

Asciidoctor produces the following HTML:

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

Learn more in the Asciidoctor Docs: enabling source code highlighters

Asciidoctor 0.1.3 includes syntax for the level 5 section title.

The level 5 title maps to the <h6> tag in the html5 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.

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

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:

Given the following input:

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

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

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.

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.

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

Example:

Renders:

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

Example:

Produces:

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.

Document variables can be assigned using the following syntax:

For example:

It’s effectively the same as:

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.

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.

Example:

The following input is now rendered as a link.

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.

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

can now be written as:

The backend option now accepts a symbol or string value.

can now be written as:

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:

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

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

That leads us into attributes specified as a string:

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:

This API call parallels this commandline invocation:

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!