Asciidoctor 1.5.0: Release Notes

If you need to get technical in your writing, Asciidoctor integrates with MathJax to allow you to write TeX / LaTeX or AsciiMath expressions directly in your document.

With a simple declaration of the stem attribute, you can now write inline and block formulas in plain text too!

You can add even more visual elements to your document with diagrams conjured from plain text. Asciidoctor Diagram emerged from a request to port the PlantUML extension for AsciiDoc Python to Asciidoctor. Pepijn Van Eeckhoudt (@pepijnve) took the reins and created a comprehensive diagram extension that not only adds integration with PlantUML, but three additional diagramming tools, as well as a framework for adding more in the future.

Asciidoctor Diagram 1.5.0 now supports the following diagramming tools:

See the Asciidoctor Diagram guide to learn how to create diagrams from ASCII art in your AsciiDoc documents.

Curious how to load extensions like Asciidoctor Diagram from the commandline interface? Read on.

Asciidoctor introduced an extensions API in 0.1.4 that enables you to extend the AsciiDoc syntax and tap into the lifecycle of the processor. However, it was only possible to load these extensions when invoking Asciidoctor via the API or by creating a custom launch script.

The asciidoctor command now supports the -r and -I flags (ported from the ruby command) to require additional paths or modify the load path, respectively.

Here’s an example of how to use the -r flag to enable the Asciidoctor Diagram extension:

The -r flag also accepts absolute or relative paths and can be used multiple times.

The scripts referenced by the -r flag are loaded in the order they are listed before any other processing occurs.

Now you get the full power of the asciidoctor command plus extensions!

The DocBook 5 specification was finalized in 2008. It’s time we embrace it.

DocBook 5 is now the default output when you use the docbook backend. If you still need to produce DocBook 4.5, use the docbook45 backend.

HTML5 reintroduced flexible HTML syntax that’s only loosely based on SGML…​and most certainly not XML. This decision makes HTML5 more approachable. However, it makes XML parsers .

To accommodate tools that use XML parsers to read the generated HTML, Asciidoctor can now output the XHTML variant of HTML5, known as XHTML5.

To output XHTML5 instead of HTML5, set the backend to xhtml or, to be more explicit, xhtml5. The “x” at the beginning of the name cleverly tells Asciidoctor to close short tags, assign values to boolean attributes and add the xmlns attribute to the root element.

Trust us, your XML parser will thank you.

Asciidoctor can now convert directly from AsciiDoc to PDF and EPUB3, using Asciidoctor PDF and Asciidoctor EPUB3, respectively. These converters are hosted in their own repositories and are distributed as separate gems.

The converters are currently alpha, but still very functional.

Guillaume Grossetie (@mogztter) led the effort during the 1.5.0 development cycle to align the Asciidoctor.js code base with Asciidoctor core. After a lot of fiddling and Opal patches, Asciidoctor.js now builds directly against master and the Asciidoctor 1.5.0 release. That means that for the first time, Asciidoctor.js is Asciidoctor.

Anthonny Quérouil (@anthonny) followed up by developing a Grunt build script to bundle Asciidoctor.js and publish it to npm (the Node.js package manager) and Bower (the web package manager).

Guillaume is the creator of the AsciiDoc preview for Chrome and Anthonny the creator of the AsciiDoc preview for Atom. The AsciiDoc preview for Atom complements the AsciiDoc language definition kicked off by Anton Moiseev (@antonmoiseev). Thomas Kern (@nerk) was quick to follow up with an AsciiDoc plugin for Brackets based on the aforementioned work. We also invited the veteran project of Asciidoctor.js, DocGist, into the Asciidoctor organization. DocGist was created by Anders Nawroth (@nawroth). Guillaume, Anthonny, Anders, Thomas, Anton and others have been collaborating on tooling based on Asciidoctor.js. They’re helping Asciidoctor boldly go where no AsciiDoc implementation has gone before.

The alignment of Asciidoctor.js with Asciidoctor core was a major effort. I want to sincerely thank Guillaume, Anthonny and the Opal team (Adam Beynon, meh and Elia Schito) for making this happen.

The single quote (') and the backtick (`) are two markup characters in the AsciiDoc syntax that often give people trouble. They like to get in each other’s way. We decided to shuffle some of the AsciiDoc syntax to address this problem and, in general, make it more consistent and easy to learn. Not only do these changes reduce slip ups by the parser, they also strengthen the meaning of the plus character and bring more alignment with Markdown by making the backtick the primary character for monospace formatting.

The leveloffset attribute is used to shift the level of sections when combining documents. It works great for a single include level, but as Groovy developers Cédric and Guillaume discovered, it quickly breaks down when you get into multiple levels of nesting.

The problem is that the level offset value is assumed to be absolute. Asciidoctor now supports relative level offset values using a leading + or - operator.

Alternatively, you can specify the leveloffset attribute directly on the include directive so you don’t have to worry about restoring the old value.

The Groovy developers use the include and tag directives a lot. They discovered that tag directives within a broader tagged range get carried over into the document. Asciidoctor now drops these lines so you can nest fine-grained ranges within broader ranges.

The tag directives are also searched using a more strict match to avoid false matches.

When you needed to customize the substitutions on a block, you used to have to list out all the substitutions you wanted to enable. It’s now possible to add or remove substitutions to the default substitution set using the + and - modifiers (e.g., [subs=+quotes]). That should save a lot of unnecessary typing!

Serving assets over SSL is a best practice to avoid man-in-the-middle attacks and preying eyes in general.

All remote assets referenced out of the box in Asciidoctor, such as Font Awesome, are now served over SSL from https://cdnjs.cloudflare.com and https://fonts.googleapis.com.

Asciidoctor auto-detects and auto-links URLs. Writers often don’t take advantage of this feature because the link shows the URI scheme prefix (e.g., http://). So, they end up long-handing it for the sole purpose of hiding the prefix.

Now, Asciidoctor can produce the exact same result if you set the hide-uri-scheme attribute on the document.

If you’re linking to an anchor point somewhere else in your document, you can refer to it by title instead of by ID.

You’ll likely want to switch to using IDs as the document matures, but this should certainly help with flow in early drafts!

Leif Gruenwoldt (@leif81) pointed out that the print styles were too aggressive, causing the printed document to lose its integrity. We worked together to tweak the stylesheet until the output looked nearly as good as the PDF generated by the DocBook toolchain. The styles even separate chapters into different pages when using the book doctype. In addition to these styles, we also added the missing table border styles for all the grid and frame permutations on both web and print.

Who needs DocBook when you’ve got HTML5 and CSS3?

The culture of Asciidoctor is deeply rooted in Open Source, so we want to be Open Source all the way down.

In the past, the default stylesheet relied on Microsoft Core Fonts (Arial and Georgia) installed on the user’s system. We’ve replaced these proprietary fonts with Open Source fonts, which we load from Google Fonts.

Here are the fonts we’ve selected:

We particularly like Noto Serif because it’s an extremely readable font and it supports all the world’s languages.

We made additional refinements to the default stylesheet that give it a professional, modern appearance. Here’s a preview of the new default theme:

Speaking of fonts, Asciidoctor integrates with Font Awesome 4.1, thanks to the work done by Guillaume Grossetie (@mogztter)! You now have over 400 icons available to accessorize your document!