Asciidoctor 0.1.2 released!

by Dan Allen -

We’re proud to announce the release of Asciidoctor 0.1.2!

Asciidoctor is an open source text processor and publishing toolchain for converting AsciiDoc markup into HTML 5, DocBook 4.5 and other formats.

The focus of this release cycle was on:

The valuable feedback we’ve received has helped bring Asciidoctor to 99% compliance with the AsciiDoc syntax. The improvements have also given Asciidoctor a 28% boost in speed, now more than 30x as fast as AsciiDoc.

Key improvements

default stylesheet

Asciidoctor now ships a default stylesheet! This stylesheet gives documents a unique, modern and elegant look and feel out of the box. To learn how to use it, read the stylesheet section of How do I render a document?. Visit http://themes.asciidoctor.org to a preview the default stylesheet and other themes created using the Asciidoctor stylesheet factory. Resolves issues #76 and #165.

docinfo files

Supplemental document header files (i.e., docinfo files) are now included in the rendered output when enabled. These files are used to include custom content into the header of the HTML or DocBook output. Resolves issues #116 and #193.

leveloffset

The leveloffset attribute is now supported. This attribute allows several standalone documents to be combined as a master document. Resolves issue #212.

partial includes

The include macro can now be used to include select regions of a file by line numbers, line ranges or tagged regions. This enhancement to the include macro is unique to Asciidoctor. Resolves issue #226.

footnotes in embedded mode

Footnotes are now rendered at the bottom of the output in embedded mode (when the header and footer are disabled), such as on GitHub or in a page generated by Awestruct. Resolves issue #206.

table of contents macro

Support has been added for the toc macro, which allows you to place the toc anywhere in the document. This feature makes it possible to include a toc in the document when in embedded mode, such as on GitHub or in a page generated by Awestruct. Resolves issues #269 and #221.

audio and video macros

Macros have been added to output HTML 5 audio and video tags. These macros parallel the block image macro. Resolves issue #155.

safe mode and embedded attributes

The attributes safe-mode-level, safe-mode-name and safe-mode-%name% are now assigned to match the active safe mode. The attribute embedded is assigned to indicate the document is rendered using the embedded document template. Resolves issue #244.

multiple authors

You can now specify multiple authors in the header of the document, separated by semi-colons. In the DocBook backend, the authors are listed in an authorgroup element in the document info section. This feature is unique to Asciidoctor. Resolves issue #223.

email macro

The inline email address and the inline mailto macro are now recognized. Resolves issue #213.

secure paths

The path resolution logic was simply too fragile as a result of relying on Ruby core libraries. The code has been completely rewritten so that paths are properly normalized and secured, with loads of tests to back it up.

custom block substitutions

Substitution groups applied to block content can now be customized using the subs block attribute. Resolves issue #220.

masquerading blocks and paragraphs

The open block and paragraphs can now masquerade as any style of block. Masquerading is also available for other blocks, where applicable. This was one of the weakest areas of Asciidoctor, now fully compliant (and even a little extra). Resolves issue #187.

In order to implement full support for masquerading blocks, paragraphs and custom block substitutions, the main block parsing code had to be reworked. The refactoring not only cleaned up the code, but laid the foundation necessary to implement block filters and other extensions.

Some of the improvements to Asciidoctor have resolved issues inherent in AsciiDoc. Fortunately, AsciiDoc is configurable enough that these issues can be "ported" to AsciiDoc without changing the core. We now maintain and ship an AsciiDoc configuration file, asciidoc.conf, that makes AsciiDoc conform to Asciidoctor’s behavior and enhancements. Resolves issue #257.

The full list of new features, enhancements and patches implemented in this release can be viewed by filtering on the 0.1.2 milestone in the issue tracker.

New website and documentation

You’re looking at it!

During the 0.1.2 release cycle, we created a proper website for Asciidoctor and focused on getting the user documentation started. Both the website and documentation are, of course, written in AsciiDoc.

Sarah White has taken on the initiative of untangling information in the AsciiDoc user guide and man pages and converting it to something consumable so users can get started quickly with the AsciiDoc and Asciidoctor toolchains.

I wrote up an introduction to AsciiDoc, an AsciiDoc writer’s guide and an AsciiDoc syntax quick reference to reveal the elegance of the AsciiDoc syntax and get writers the information they need to be productive and proficient with AsciiDoc. I summarized this information in an article titled The Zen of Writing (Ascii)Docs, published in the April issue of NFJS, The Magazine (also produced from articles written in AsciiDoc).

Look for more details about the website and documentation in a future news post.

Thanks!

The amount of participation in the Asciidoctor project, particularly around the integrations, has increased tremendously since the last release. Asciidoctor 0.1.1 crossed the 10,000 downloads mark prior to this release. We look forward to 0.1.2 breaking the next 10,000.

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:

Together, we’re making documentation easy, fun and rewarding!