Asciidoctor 0.1.4 released!

Asciidoctor 0.1.4 introduces an inline macro for inserting an icon at an arbitrary place in paragraph content.

Here’s an example that inserts a tags icon in front of a list of tag names:

Here’s how this example renders:

ruby, asciidoctor

You can even give the icon color by assigning it a role:

which appears as:

ruby, asciidoctor

The icon macro recognizes a few attributes that can be used to modify the size, orientation and function of the icon. Here’s a large, blue Twitter logo that’s had too much to drink, but still manages to link to the Twitter homepage:

created from:

At the moment, the name of the icon is resolved from the Font Awesome icon set. You can see the possible icon name options on the icons page. Support for other icon sets is being discussed in issue #539.

If you aren’t using the font-based icons, Asciidoctor looks for the images on disk in the iconsdir directory.

Resolves issue #529.

In AsciiDoc, the xref inline macro is used to create a cross-reference (i.e., link) from one section to another. Asciidoctor 0.1.4 extends this functionality by allowing a link to be made to a section in another AsciiDoc document. This eliminates the need to use direct links between documents (e.g., HTML links) that couple the document to a single backend. The cross-reference also captures the intent to establish a reference between related documents.

Here’s how an xref is normally defined in AsciiDoc:

This xref creates a link to a section with the id section-b.

Let’s assume the xref is defined in the document document-a.adoc. If the target section is in a separate document, document-b.adoc, the author may be tempted to write:

However, this link is coupled to HTML output. What’s worse, if document-b.adoc is included in the same master as document-a.adoc, then the link will refer to a document that doesn’t even exist!

These problems can be alleviated by using an inter-document xref:

The id of the target is now placed behind a hash symbol (#). Preceding the hash is the name of the reference document (the file extension is optional). We also assigned a label to the reference since Asciidoctor cannot (yet) resolve the section title in a separate document.

When Asciidoctor generates the link for this xref, it first checks to see if document-b.adoc is included in the same master as document-a.doc. If not, it will generate a link to document-b.html, intelligently substituting the original file extension with the file extension of the output file.

If document-b.adoc is included in the same master as document-a.doc, then the document will be dropped in the link target and look like the output of a normal xref:

Now you can create inter-document references without the headache.

Resolves issue #417.

By default, the original AsciiDoc processor drops the entire line if it contains a reference to a missing attribute (e.g., {bogus}). This "feature" was added to the Python implementation for use in creating custom backends, which are written using the AsciiDoc syntax.

This behavior is not needed in Asciidoctor since its templates are composed in a dedicated template language (e.g., ERB, Haml, Slim, etc). But the main issue with this behavior is that it’s frustrating to the author, editor or reader. To them, it’s not immediately apparent when a line goes missing. Discovering its absence often requires a full (and tedious) read-through of the document or section.

Asciidoctor 0.1.4 introduces two attributes to alleviate this inconvenience: attribute-missing and attribute-undefined.

The video::[] macro now supports videos from external video hosting services like YouTube and Vimeo. To use this feature, put the video ID in the macro target and the name of the hosting service in the first positional attribute. Asciidoctor will put the two together and generate the correct embed code to insert the video in the HTML output.

Here’s an example that embeds a YouTube video:

and one that embeds a Vimeo video:

You can control the video settings using additional attributes and options on the macro. For instance, you can offset the start time of playback using the start attribute and enable autoplay using the autoplay option.

Resolves issue #587.

In addition to DocBook 4.5, Asciidoctor 0.1.4 can produce DocBook 5.0 output, which is handled by the docbook5 backend.

The output from the docbook5 backend only differs marginally from the docbook45, just enough to make it compliant with the DocBook 5.0 specification. A summary of the differences are as follows:

Refer to What’s new in DocBook v5.0? for more details about how DocBook 5.0 differs from DocBook 4.5.

To use the DocBook 5.0 backend, set the backend to docbook5, as shown in this example:

Here’s a sample DocBook 5.0 document generated by this backend:

Resolves issue #411.

Joining the Fedora package, Asciidoctor is now packaged for Debian and Ubuntu thanks to Per Andersson! 'nuff said!

You can install Asciidoctor on Debian or Ubuntu using:

Resolves issue #216.

Previously, when a reader selected and copied source code containing callouts from an HTML page generated by Asciidoctor, the callout numbers would get caught up in the copy. Those extra characters can cause compile or runtime errors at the spot where the reader pastes the code. Readers shouldn’t be surprised in this way or have to understand why extra characters end up in the clipboard. Copy and paste should just work.

In this release, we used some CSS ninja moves to prevent the callouts from getting caught up in the copy. No matter how hard the reader tries, those callouts just won’t get selected. (The same is true for line numbers as well).

On the other side of the coin, you don’t want the callout annotations to mess up your code either. We can’t play fancy CSS games in raw source code, but we can leverage line comments! You can now tuck your callouts neatly behind line comments. Asciidoctor will recognize the line comment characters in front of a callout number—​optionally offset by a space—​and remove them when rendering the document.

Here are the line comments that are supported:

Here’s how the commented callouts look when rendered:

Notice the line comment characters are gone! Now select the lines. As you can see, the callouts are left behind.

We want callouts to be an aid, not a pain.

Resolves issue #478.

Speaking of pain, what about callouts in XML? Read on to find out.

XML doesn’t have line comments, so our “tuck the callout behind a line comment” trick doesn’t work here. We played around with the syntax and came up with something we think works and looks pretty clean. We just stretched out the angled brackets around the callout number and turned it into an XML comment:

<1> ⇒ <!--1-->

Here’s how the XML-friendly callout appears in a listing:

Here’s how the callout looks when rendered:

Again, notice the comment is gone and the callout number cannot be selected.

Resolves issue #582.

A macro definition for XML-friendly callouts is included in the AsciiDoc compatibility file so they can be recognized by the asciidoc command as well.

Thanks to these enhancements, both the reader and developer can copy and paste source code containing callouts without having to worry about error-causing hitchhikers. But, our tricks with callouts aren’t over quite yet.

We had reports that callouts weren’t getting replaced in some cases when using the CodeRay source highlighter (e.g., source-highlighter=coderay).

It turns out, the problem is that the very presence of callouts in the code, whether behind line comments or not, causes them to get caught in the highlighting and mangled. The trick here is to pull the callouts out of the source code before highlighting, then restore them afterward. That way, the source highlighter never sees them, and we can be sure that they end up where they’re supposed to be, unmangled.

There’s nothing you need to change to take advantage of this improvement. This feature works when using CodeRay or Pygments (i.e., the "server-side" source highlighters).

Resolves issue #534.

That’s right. Asciidoctor can use Pygments to highlight source code!

The most popular source code highlighter in the AsciiDoc world—​perhaps the whole world—​is Pygments. Until now, Asciidoctor only integrated with CodeRay for "server-side" source highlighting, mostly because it’s also written in Ruby.

Thanks to the awesome folks at GitHub, Pygments has a nice Ruby wrapper library named pygments.rb that makes integrating with it a cinch.

In order to use Pygments with Asciidoctor, you need to install Pygments (and Python, if you don’t have it yet). Run something like:

You then need to install the pygments.rb RubyGem.

To activate Pygments in Asciidoctor, assign the value pygments to the source-highlighter attribute in your document’s header.

Voila! Your code now has “pygments”.

Resolves issue #538.

Previously, the Asciidoctor stylesheet was configured to prevent line wrapping (e.g., white-space: pre-wrap; word-wrap: normal) in listing and literal blocks. This behavior isn’t always desirable because it causes the browser window to scroll if the content overflows the width of the page. For many, this horizontal scrolling is considered a greater readability problem than line wrapping.

Since there are two camps on how to handle overflow text, neither choice would please both audiences. For that reason, we’ve made this behavior configurable in Asciidoctor 0.1.4.

The default Asciidoctor stylesheet now wraps long lines in listing and literal blocks by applying the CSS white-space: pre-wrap and word-wrap: break-word. The lines are wrapped at word boundaries, similar to how most text editors wrap lines.

There are two ways to prevent lines from wrapping so that horizontal scrolling is used instead:

You can use the nowrap option on literal or listing blocks to prevent lines from being wrapped in the HTML:

When the nowrap option is used, the nowrap class is added to the <pre> element. This style class changes the CSS to white-space: pre and word-wrap: normal.

To apply the nowrap option globally, unset the prewrap attribute on the document.

When the prewrap attribute is unset, the nowrap class is added to any <pre> element, even when the nowrap option is absent on the block.

Now, you can use the line wrapping strategy that works best for you and your readers.

Resolves issue #303.

List items can now be marked as complete using checklists. If you use Asciidoctor to track the completion of tasks, get ready to start checking off those tasks!

Checklists (i.e., task lists) are unordered lists that have items marked as checked ([*] or [x]) or unchecked ([ ]). Here’s an example:

When checklists are rendered to HTML, the checkbox markup is transformed into an HTML checkbox with the appropriate checked state. For more details, check out the checklist section in the user manual.

If you enable font-based icons (i.e., -a icons=font), the checkbox markup is rendered using a font-based icon! Here’s how that looks:

Snazzy!

Resolves issue #200.

Asciidoctor 0.1.4 offers additional bullet and numbering styles for lists. The list marker (bullet or numeration style) is set using the list’s block style.

Asciidoctor now recognizes all the unordered list bullets available in HTML and DocBook.

The unordered list marker can be set using any of the following block styles:

When present, the style name is assigned to the unordered list element as follows:

Here’s how you create an unordered list marked with square bullets:

For ordered lists, Asciidoctor now supports the lowergreek and decimal-leading-zero numeration styles in addition to the existing options.

Here are a few examples showing various numeration styles as defined by the block style shown in the header row:

* Default numeration if block style is not specified

For more information about bullets and numerations, consult the user manual.

Resolves issues #364, #472 and #620.

After adding shorthand notation in Asciidoctor 0.1.3 for specifying the table format (e.g., ,===, ;===), it seemed tedious to still have to use a block attribute line to enable the header row (e.g, [options="header"]).

It’s now possible to enable the header row implicitly just by following a few conventions. Here are the conventions introduced in Asciidoctor 0.1.4 to determine if the first row should be a header row:

If all of these rules hold, the first row of the table is treated as a header row. Building on existing conventions, if the cols attribute has not been specified, the number of columns in the table is set to the number of columns in the first row (i.e., the header row).

Here’s an example of a table that has an implicit header row:

Here’s how it looks when rendered:

Resolves issue #387.

In traditional AsciiDoc syntax, block options are specified using the options attribute in the block’s attribute list. Asciidoctor 0.1.4 allows options to be specified using a block shorthand notation, in which the option name is prefixed with a percent sign (%).

Consider the following table block with three options:

Here’s how the options are written using the shorthand notation (%):

Let’s consider the options when combined with other shorthand notations.

Resolves issue #481.

The shorthand notation introduced on blocks in Asciidoctor 0.1.3 can now be used on inline formatted (i.e., quoted) text as well.

Here’s an example of an inline anchor and formatted text that has two roles:

In the HTML backend, this syntax becomes:

In the DocBook backend, it becomes:

Resolves issue #517.

To align with other formatted (i.e., quoted) text in AsciiDoc, roles can now be assigned to text enclosed in backticks.

Given:

the following HTML is produced:

Using the new shorthand notation in Asciidoctor 0.1.4, an id (i.e., anchor) can also be specified:

which produces:

Keep in mind that text enclosed in backticks is not subject to other inline substitutions, but rather passed through as is.

Resolves issue #419.

The Asciidoctor CLI (i.e., the asciidoctor command) is no longer single-minded! You can pass multiple source files (or a file name pattern) to the Asciidoctor CLI and it will process all the files in turn.

Let’s assume there are two AsciiDoc files in your directory, a.adoc and b.adoc. When you enter the following command in your terminal:

Asciidoctor will process both files, transforming a.adoc to a.html and b.adoc to b.html.

To save you some typing, you can use the glob operator (*) to match both files using a single argument:

The shell will expand the previous command to the one you typed earlier:

You can also render all the AsciiDoc files in immediate subfolders using the double glob operator (**) in place of the directory name:

To match all files in the current directory and immediate subfolders, use both glob patterns:

If the file name argument is quoted, the shell will not expand it:

This time, the text *.adoc gets passed directly to Asciidoctor instead of being expanded to a.adoc and b.adoc. In this case, Asciidoctor handles the glob matching internally in the same way the shell does (when the file name is not in quotes)--with one exception. Asciidoctor can match files in the current directory and subfolders at any depth using a single glob pattern:

Now that’s saving you some typing!

Resolves issue #227.

Images are a great way to enhance the text, whether it’s to illustrate an idea, show rather than tell, or just help the reader connect with the text.

Out of the box, images and text behave like oil and water. Images don’t like to share space with text. They are kind of "pushy" about it. That’s why we tuned the controls in the image macros so you can get the images and the text to flow together.

There are two approaches you can take when positioning your images:

AsciiDoc couldn’t decide if it wanted to support remote images (i.e., images with a URL target) or not. While you’ve always been able to use a URL for block images, both AsciiDoc and Asciidoctor were ignoring inline images with a URL target.

Even the block images would fall apart in AsciiDoc if you defined the imagesdir attribute to set the location of your local images. AsciiDoc was mangling the image URL in this case by blindly prefixing the URL with this path. Doh!

Things were messy. They aren’t anymore. You can now reference images served from any URL (e.g., your blog, an image hosting service, your docs server, etc.) and never have to worry about downloading the images and putting them somewhere locally. Asciidoctor gets it right. We’ve also updated the AsciiDoc compatibility file so that AsciiDoc gets it right too.

Here are a few examples of images that have a URL target:

If you want to avoid typing the URL prefix for every image, and all the images are located on the same server, you can use the imagesdir attribute to set the base URL:

This time, the imagesdir is used since the image target is not a URL (the imagesdir just happens to be one).

Resolves issue #470.

The TOC in the html5 backend is now rendered as an unordered list instead of an ordered list. This change was made since the automatic numbering of an ordered list isn’t consistent with the numbering strategy in AsciiDoc and therefore is semantically incorrect. This also eliminates the "double numbering of sections" problem that was occurring when the default stylesheet was absent. Additionally, the type="none" list attribute work-around can be dropped.

Resolves issue #461.

Asciidoctor now correctly numbers sections in cases when numbering is disabled for a portion of the document. Previously, Asciidoctor would increment the section number counter in regions of the document where section numbering was disabled. This resulted in section numbers being skipped. Asciidoctor now freezes the counter where numbering is suppressed to prevent gaps in the numbering.

Asciidoctor was also preventing section numbering from being turned off if the document started with section numbering on. Now, if the -a numbered option is passed to Asciidoctor, it will still honor :numbered!: directives in the flow of the document.

In short, section numbering now works the way it should.

Resolves issue #341.

Asciidoctor continues to expand support for (reasonable) Markdown syntax by recognizing Markdown horizontal rules. The motivation here is to ease migration (both of the content and the mind).

To avoid conflicts with the syntax of AsciiDoc block delimiters, only 3 repeating characters (- or *) are recognized. As with Markdown, whitespace between the characters is optional.

A macro definition for the Markdown horizontal rules is included in the AsciiDoc compatibility file so they can be recognized by the asciidoc command as well.

Resolves issue #455.

The include directive can now include content directly from a URI.

Here’s an example that demonstrates how to include AsciiDoc content:

Here’s another example showing how to include specific lines of a source file:

Since this is a potentially dangerous feature, it’s disabled if the safe mode is SECURE or greater. Assuming the safe mode is less than SECURE, you must also set the allow-uri-read attribute to permit Asciidoctor to read content from a URI.

Reading content from a URI is obviously much slower than reading it from a local file. Asciidoctor provides a way for the content read from a URI to be cached, which is highly recommended.

To enable the built-in cache, you must:

When these two conditions are satisfied, Asciidoctor will cache content read from a URI according the to HTTP caching recommendations.

Resolves issue #445.

AsciiDoc allows you to include custom content in the header of the output document (HTML or DocBook) by supplying docinfo files. In Asciidoctor 0.1.4, docinfo files can be used to add custom content to the footer as well.

Footer docinfo files are differentiated from header docinfo files by adding -footer to the file name. In the HTML output, the footer content is inserted inside the footer div (i.e., <div id="footer">). In the DocBook output, the footer content is inserted immediately before the ending </article> or </book> element.

If you want to add content to the footer of a specific document, put the content in the file <docname>-footer.html (for HTML output) or <docname>-footer.xml (for DocBook output), where <docname> is the name of the document without the AsciiDoc extension. Then, set the attribute docinfo in the AsciiDoc source document to enable the feature.

If you want to add content to the footer of all documents in the same directory, put the content in the file docinfo-footer.html (for HTML output) or docinfo-footer.xml (for DocBook output). Then, set the attribute docinfo1 in the AsciiDoc source document to enable the feature.

If you want the document to look for either docinfo file, set the attribute docinfo2 in the AsciiDoc source document.

Resolves issue #486.

Many static site generators (i.e., Jekyll, Middleman, Awestruct) rely on "front matter" added to the top of the document to determine how to render the content. Front matter typically starts on the first line of a file and is bounded by block delimiters (e.g., ---).

Here’s an example of a document that contains front matter:

The static site generator removes these lines before passing the document to the Asciidoctor processor to be rendered. Outside of the generator, however, these extra lines confuse the AsciiDoc processor.

If the skip-front-matter attribute is set, Asciidoctor 0.1.4 will recognize the front matter and consume it before parsing the document. Asciidoctor stores the content it removes in the front-matter attribute to make it available for integrations. Asciidoctor also removes front matter when reading include files.

Resolves issue #502.

In earlier versions of Asciidoctor, we linked to the stylesheet in the HTML output by default rather than embedding it—​the reverse of how AsciiDoc works. The reason we did it this way was to keep the HTML output document lightweight. What we found is that new users often don’t discover the default stylesheet and get confused when certain features, which rely on CSS, don’t work.

We’d rather have Asciidoctor “just work” out of the box. It’s a better experience for new users and we get to spend less time repeatedly answering the same forum post.

That’s why in Asciidoctor 0.1.4 (and going forward), stylesheets are embedded in the HTML output by default (i.e., linkcss is not set). If no stylesheet is specified, then it’s the default stylesheet that gets embedded. New users no longer have to fiddle with the linkcss or copycss attributes.

As it turns out, there’s another benefit to switching this default. We no longer have to rely on the copycss attribute at all. Now, if the linkcss attribute is set, stylesheets are copied to the stylesdir (inside the output directory) so the HTML document can find them. If you’re using the default stylesheet, you’ll see asciidoctor.css appear in this directory. To disable this behavior, just unset the copycss attribute (i.e., copycss!).

Resolves issue #428.

Custom templates can now be stored in multiple directories. That means you can build on an existing backend by copying just the templates you want to modify. Then, simply pass both the directory holding the original templates and the directory containing your customized templates when you invoke Asciidoctor.

In the CLI, multiple template directories are specified by using the -T option multiple times.

In the API, multiple template directories are specified by passing an array to the template_dirs option:

Hack away!

Resolves issue #437.

One of the most interesting uses of AsciiDoc is for creating man pages (short for manual pages) for Unix and Unix-like operating systems. A man page conforms to a special document structure. That structure is recognized by AsciiDoc, and now Asciidoctor, when the doctype attribute is set to manpage.

When reading an AsciiDoc document using the manpage doctype, Asciidoctor parses the following man page metadata:

The mantitle and manvolum are captured from the document title. The manname and manpurpose are taken from the first section of the document, which must be a level 1 section and have content in the format <manname> - <manpurpose>.

Here’s an example of a man page written in AsciiDoc:

From this document, Asciidoctor extracts the following man page-related attributes:

Refer to the AsciiDoc source of the Asciidoctor man page to see a complete example. The man pages for git are also produced from AsciiDoc documents, so you can use those as another example to follow.

Resolves issue #488.

The reason I’ve been looking forward to bringing extensions to Asciidoctor is because they’ve already proven to be central to the success of AsciiDoc and the Python implementation. Despite the success they’ve enjoyed, there’s still plenty of room for improvement.

Extensions in AsciiDoc (technically called filters) have a number of problems:

The goal for Asciidoctor has always been to allow extensions to be written using the full power of a programming language (whether it be Ruby, Java, Groovy or JavaScript), similar to what we’ve done with the backend (rendering) mechanism. That way, you don’t have to shave yaks to get the functionality you want, and you can distribute the extension using defacto-standard packaging mechanisms (like RubyGems or JARs).

Here are the extension points that are available in Asciidoctor 0.1.4.

These extensions are registered per document using a callback that feels sort of like a DSL:

You can register more than one processor of each type, though you can only have one processor per custom block or macro. Each registered class is instantiated when the Asciidoctor::Document is created.

For now, you need to use the Asciidoctor API (not the CLI) in order to register the extensions and invoke Asciidoctor. Eventually, we’ll be able to load extensions packaged in a RubyGem (Ruby) or JAR (Java) by scanning the LOAD_PATH (Ruby) or classpath (Java), respectively. We may also ship some built-in extensions that can be enabled using an attribute named extensions, similar to how Markdown processors work.

Resolves issues #97 and #100.

I’d like to recognize the authors of the libraries I used as inspiration for Asciidoctor’s extension API, most notably Middleman, Python Markdown and Kramdown.

Below are several examples of extensions and how they are registered.