Asciidoctor 0.1.4 released!

by Dan Allen and Sarah White -

We’re thrilled (and a bit relieved) to announce the release of Asciidoctor 0.1.4!

What is Asciidoctor?

Asciidoctor is a fast, open source text processor and publishing toolchain for transforming AsciiDoc markup into HTML 5, DocBook 5.0, DocBook 4.5 and custom output formats. Asciidoctor is written in Ruby, packaged as a RubyGem and published to RubyGems.org. The Asciidoctor processor is also accessible to any JVM language or build system via the Java integration library.

Follow the instructions on the Installing or Updating Asciidoctor page to get started.

A release marked by milestones

Asciidoctor 0.1.4 was originally planned to be a small release. Instead, it turned out to be a summer-long project, spanning from Memorial Day to Labor Day, which concluded in the biggest release to date. Ninety issues — that’s right, 90 — were closed along the way, resulting in 325 commits.

The extended development cycle was due in part to a major pickup in the amount of feedback from users. We also didn’t want to let another release slip by without including an extension mechanism, which we’re happy to say is available in this release as a technology preview.

This also turned out to be a development cycle full of milestones. At the time of the last release, we announced that Asciidoctor had reached 20,000 downloads in total. Asciidoctor 0.1.3 alone topped that number at 27,000 and the number of downloads in total broke the 50,000 mark! But that’s just the start.

Here are some of the additional milestones we surpassed:

  • > 1,000 commits (1,158 in total)

  • > 1,000 tests (1245 in total)

  • > 500 closed issues (523 in total)

  • > 100 mailing list topics (117 in total)

  • > 1 year of development (initial commit Jun 1, 2012)

Once again, the valuable feedback we’ve received from Asciidoctor’s awesome community has helped push Asciidoctor’s compliance with the AsciiDoc syntax beyond the Python implementation. Asciidoctor has also achieved another 15% increase in speed over the previous release. Just to give you an idea of how fast the processor is, the 16,000-line Enterprise Web Development: From Desktop to Mobile book, published by O’Reilly, renders to HTML in 0.85 seconds on an Ultrabook.

Asciidoctor is now in use by major open source projects, most notably Groovy, Spring XD, Spring Security, OpenShift Origin, Neo4j, CRaSH, RichFaces and Granite DS, among others. We’ve also kicked off our own documentation effort in Asciidoctor, admist all the development. Sarah started a documentation strategy (i.e., information architecture) for the project and composed an initial draft of the Asciidoctor user manual. For the first time, we also have a proper Changelog associated with each tag on GitHub and aggregated in the CHANGELOG.adoc file at the repository root.

As you can see, things are really on around here.

On that note, let’s get to what’s in this new release! (Jump to TL;DR to get the abbreviated version.)

Headliners

Awesome icons everywhere!

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:

icon:tags[] ruby, asciidoctor

Here’s how this example renders:

ruby, asciidoctor

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

icon:tags[role=blue] ruby, asciidoctor

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:

icon:twitter[4x, flip=vertical, link=http://twitter.com]

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.

Additional improvements
  • Asciidoctor now uses Font Awesome 3.2.1 (loaded from cdnjs.com) (#451)

Inter-document references

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:

Refer to <<section-b>> for more information.

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:

Refer to link:document-b.html#section-b[Section B] for more information.

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:

Refer to <<document-b.adoc#section-b,Section B>> for more information.

See you when you get back from <<document-b#section-b,Section B>>!

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.

<a href="document-b.html#section-b">Section B</a>

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:

<a href="#section-b">Section B</a>

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

Resolves issue #417.

No more dropped lines!

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.

attribute-missing

The attribute attribute-missing controls how missing references are handled. By default, missing references are left intact so it’s clear to the author when one hasn’t been satisfied since, likely, the intent is for it to be replaced.

This attribute has three possible values:

skip

leave the reference in place (default setting)

drop

drop the reference, but not the line

drop-line

drop the line on which the reference occurs (compliant behavior)

Consider the following line of AsciiDoc:

Hello, {name}!

Here’s how the line is handled in each case, assuming the name attribute is not defined:

skip

Hello, {name}!

drop

Hello, !

drop-line

attribute-undefined

The attribute attribute-undefined controls how expressions that undefine an attribute are handled (e.g., {set:name!}). By default, the line is dropped since the expression is a statement, not content. It’s reasonable to stick with the compliant behavior in this case since such an expression is not intended to produce content.

We recommend putting any statement that undefines an attribute on a line by itself.

Resolves issue #523.

YouTube and Vimeo videos

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:

video::rPQoq7ThGAU[youtube, 640, 360]

and one that embeds a Vimeo video:

video::67480300[vimeo, 400, 300]

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.

video::rPQoq7ThGAU[youtube, 640, 360, start=60, options=autoplay]

Resolves issue #587.

DocBook 5.0 backend

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:

  • XSD declarations are used on the document root instead of a DTD

  • <info> elements for document info instead of <articleinfo> and <bookinfo>

  • elements that hold the author’s name are wrapped in a <personname> element

  • the id for an element is defined using an xml:id attribute

  • <link> is used for links instead of <ulink>

  • the URL for a link is defined using the xlink:href attribute

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:

$ asciidoctor -b docbook5 sample.adoc

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

<?xml version="1.0" encoding="UTF-8"?>
<article xmlns="http://docbook.org/ns/docbook"
    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
  <info>
    <title>Hello, AsciiDoc!</title>
    <date>2013-09-03</date>
    <author>
      <personname>
        <firstname>Doc</firstname>
        <surname>Writer</surname>
      </personname>
      <email>doc@example.com</email>
    </author>
    <authorinitials>DW</authorinitials>
  </info>
  <simpara>
    An introduction to <link xlink:href="http://asciidoc.org">AsciiDoc</link>.
  </simpara>
  <section xml:id="_first_section">
    <title>First Section</title>
    <itemizedlist>
      <listitem>
        <simpara>item 1</simpara>
      </listitem>
      <listitem>
        <simpara>item 2</simpara>
      </listitem>
    </itemizedlist>
  </section>
</article>

Resolves issue #411.

Additional improvements
  • The xmlns attribute is now added to the root DocBook element by default. Set the attribute noxmlns to disable this feature.

Debian and Ubuntu package

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:

$ sudo apt-get install asciidoctor
Currently, packages are only available for Asciidoctor 0.1.3. Updated packages for Asciidoctor 0.1.4 should become available within a few weeks following this release.

Resolves issue #216.

Classy code listings

We know code is important to you. It’s important to us too. That’s why we made some sweet refinements to code listings in this release.

Callouts don’t get caught in copy

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:

----
line of code  // <1>
line of code   # <2>
line of code  ;; <3>
----
<1> A callout behind a line comment for JavaScript, Java, and C-style languages.
<2> A callout behind a line comment for Ruby, Python, Perl, etc.
<3> A callout behind a line comment for Clojure and Lisp-style languages.

Here’s how the commented callouts look when rendered:

line of code  (1)
line of code  (2)
line of code  (3)
1 A callout behind a line comment for JavaScript, Java, and C-style languages.
2 A callout behind a line comment for Ruby, Python, Perl, etc.
3 A callout behind a line comment for Clojure and Lisp-style languages.

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.

Asciidoctor requires that callouts be placed at the end of the line.

Resolves issue #478.

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

XML-friendly callouts

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:

[source,xml]
----
<section>
  <title>Section Title</title>  <!--1-->
</section>
----
<1> The section title is required.

Here’s how the callout looks when rendered:

<section>
  <title>Section Title</title>  (1)
</section>
1 The section title is required.

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

This syntax also works for callouts in HTML listings.

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.

Highlight-free callouts

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.

Wait, did you say Pygments?

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

Syntax highlighting with Pygments

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:

$ "`\which apt-get || \which yum || \which brew`" install python-pygments

You then need to install the pygments.rb RubyGem.

$ gem install pygments.rb

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

:source-highlighter: pygments

Voila! Your code now has “pygments”.

Resolves issue #538.

Additional improvements
  • The default CodeRay theme has been updated so it matches better with the default Asciidoctor styles.

  • Syntax highlighting is no longer disabled if the subs attribute is used on a source listing (as long as specialcharacters is in the subs list).

To wrap or to scroll, that is the question

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:

  • set the nowrap option on the block

  • unset the prewrap document attribute

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

public class ApplicationConfigurationProvider extends HttpConfigurationProvider
{
   @Override
   public Configuration getConfiguration(ServletContext context)
   {
      return ConfigurationBuilder.begin()
               .addRule()
               .when(Direction.isInbound().and(Path.matches("/{path}")))
               .perform(Log.message(Level.INFO, "Client requested path: {path}"))
               .where("path").matches(".*");
   }
}

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.

:prewrap!:

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.

Mark your lists

Lists are everywhere. Let’s put them to work.

Getting Things Done using checklists

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:

Checklist
- [*] checked
- [x] also checked
- [ ] not checked
-     normal list item

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:

  • checked

  • also checked

  • not checked

  • normal list item

Snazzy!

Resolves issue #200.

More bullets and numerations styles for lists

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:

  • square

  • circle

  • disc

  • none or no-bullet (indented, but no bullets)

  • unstyled (no indentation or bullets) (HTML only)

  • inline (as paragraph, no bullets) (HTML only)

These styles are supported by the default Asciidoctor stylesheet.

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

For HTML

the style name is assigned to the class attribute on the <ul> element.

For DocBook

the style name is assigned to the mark attribute on the <itemizedlist> element.

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

[square]
* one
* two
* three

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

These two new styles are only supported in the HTML backend (DocBook doesn’t recognize these options).

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

[arabic]* [decimal] [loweralpha] [lowergreek]
  1. one

  2. two

  3. three

  1. one

  2. two

  3. three

  1. one

  2. two

  3. three

  1. one

  2. two

  3. three

* Default numeration if block style is not specified

Custom numeration styles can be implemented using a custom role. Define a new class selector (e.g., .custom) in your stylesheet that sets the list-style-type property to the value of your choice. Then, assign the name of that class as a role (e.g., [.custom]) on any list to which you want that numeration applied.

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

Resolves issues #364, #472 and #620.

Additional improvements
  • When the role shorthand (e.g., [.custom]) is used on an ordered list, the default numeration style is no longer dropped.

More time savers

Implicit header row for tables

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:

  1. The first line of content inside the table block delimiters is not empty.

  2. The second line of content inside the table block delimiters is empty.

  3. The options attribute has not been specified in the block attributes.

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:

|===
|A |B |C (1)

|A-1
|B-2
|C-3

|A-2| B-2| C-2

|A-3
|B-3
|C-3
|===
1 Satisfies the convention for a header row.

Here’s how it looks when rendered:

A B C

A-1

B-1

C-1

A-2

B-2

C-2

A-3

B-3

C-3

You can arrange the cells in the remaining rows however you want. Note, however, that we’re considering using a similar convention for enabling the footer in the future. Thus, if you rely on this convention to enable the header row, it’s advised that you not put all the cells in the last row on the same line unless you intend on making it the footer row.

Resolves issue #387.

Shorthand notation for block options

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:

Block options using traditional AsciiDoc syntax
[options="header,footer,autowidth"]
|===
|Cell A |Cell B
|===

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

Block options using Asciidoctor shorthand notation
[%header%footer%autowidth]
|===
|Cell A |Cell B
|===

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

Traditional AsciiDoc syntax
[horizontal, role="properties", options="step"]
property 1:: does stuff
property 2:: does different stuff
Asciidoctor shorthand notation
[horizontal.properties%step]
property 1:: does stuff
property 2:: does different stuff

Resolves issue #481.

Shorthand notation on formatted (i.e., quoted) text

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:

Traditional AsciiDoc syntax
[[free_the_world]][big goal]_free the world_
Asciidoctor shorthand notation
[#free_the_world.big.goal]_free the world_
Since quoted text doesn’t have an id, the id attribute is converted to an anchor that precedes the text.

In the HTML backend, this syntax becomes:

<a id="free_the_world"><em class="big goal">free the world</em>

In the DocBook backend, it becomes:

<anchor id="free_the_world" xreflabel="free the world"/><emphasis><phrase
role="big goal">free the world</phrase></emphasis>

Resolves issue #517.

Additional improvements
  • The attribute list preceding formatted text can be escaped using a backslash (e.g., \[role]*bold*). In this case, the text will still be formatted, but the attribute list will be unescaped and output verbatim. (#421)

Role-playing for text enclosed in backticks

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

Given:

[rolename]`escaped monospace text`

the following HTML is produced:

<code class="rolename">escaped monospace text</code>

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

[#idname.rolename]`escaped monospace text`

which produces:

<a id="idname"></a><code class="rolename">escaped monospace text</code>

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

Resolves issue #419.

Process multiple source files from the CLI

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 a.adoc b.adoc

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:

$ asciidoctor *.adoc

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

$ asciidoctor a.adoc b.adoc

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

$ asciidoctor **/*.adoc

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

$ asciidoctor *.adoc **/*.adoc

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

$ asciidoctor '*.adoc'

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:

$ asciidoctor '**/*.adoc'

Now that’s saving you some typing!

Resolves issue #227.

Additional improvements
  • The asciidoctor command writes to the specified output file if the input is stdin. (#500)

For example, the following command writes to output.html instead of to the console:

$ echo "content" | asciidoctor -o output.html -

Formatting galore

Put images in their place

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:

  1. Named attributes

  2. Roles

Positioning attributes

Asciidoctor already supports the align attribute on block images to align the image within the block (e.g., left, right or center). In this release, we added the float named attribute to both the block and inline image macros. This attribute pulls the image to one side of the page or the other and wraps block or inline content around it, respectively.

Here’s an example of a floating block image. The paragraphs or other blocks that follow the image will float up into the available space next to the image. The image will also be positioned horizontally in the center of the image block.

A block image pulled to the right and centered within the block
image::tiger.png[Tiger,200,200,float="right",align="center"]

Here’s an example of a floating inline image. The image will float into the upper-right corner of the paragraph text.

An inline image pulled to the right of the paragraph text
image:linux.png[Linux,150,150,float="right"]
You can find Linux everywhere these days!

When you use the named attributes, CSS gets added inline (e.g., style="float: left"). That’s bad practice because it can make the page harder to style when you want to customize the theme. It’s far better to use CSS classes for these sorts of things, which map to roles in AsciiDoc terminology.

Positioning roles

Here are the examples from above, now configured to use roles that map to CSS classes in the default Asciidoctor stylesheet:

Image macros using positioning roles
[.right.text-center]
image::tiger.png[Tiger,200,200]

image:linux.png[Linux,150,150,role="right"]
You can find Linux everywhere these days!

The following table lists all the roles available out of the box for positioning images.

Roles for positioning images
Float Align

Role

left

right

text-left

text-right

text-center

Block Image

Inline Image

Merely setting the float direction on an image is not sufficient for proper positioning. That’s because, by default, no space is left between the image and the text. To alleviate this problem, we’ve added sensible margins to images that use either the positioning named attributes or roles.

If you want to customize the image styles, perhaps to customize the margins, you can provide your own additions to the stylesheet (either by using your own stylesheet that builds on the default stylesheet or by adding the styles to a docinfo file).

Framing images

It’s common to frame the image in a border to further offset it from the text. You can style any block or inline image to appear as a thumbnail using the thumb role (or th for short), also in the default stylesheet.

The thumb role doesn’t alter the dimensions of the image. For that, you need to assign the image a height and width.

Here’s a very common example for adding an image to a blog post. The image floats to the right and is framed to make it stand out more from the text.

image:logo.png[role="related thumb right"] Here's text that will wrap around the image to the left.

Notice we added the related role to the image. This role isn’t technically required, but it gives the image semantic meaning.

Controlling the float

When you start floating images, you may discover that too much content is floating around the image. What you need is a way to clear the float. That is provided using another role, float-group.

Let’s assume that we’ve floated two images so that they are positioned next to each other and we want the next paragraph to appear below them.

[.left]
.Image A
image::a.png[A,240,180]

[.left]
.Image B
image::b.png[B,240,180,title="Image B"]

Text below images.

When this example is rendered and viewed a browser, the paragraph text appears to the right of the images. To fix this behavior, you just need to "group" the images together in a block with self-contained floats. Here’s how it’s done:

[.float-group]
--
[.left]
.Image A
image::a.png[A,240,180]

[.left]
.Image B
image::b.png[B,240,180]
--

Text below images.

This time, the text will appear below the images where we want it.

Resolves issue #460.

Image URLs are rendered, not mangled

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:

Block image with a URL target
imagesdir: ./images

image::https://upload.wikimedia.org/wikipedia/commons/3/35/Tux.svg[Tux,250,350]
Inline image with a URL target
imagesdir: ./images

You can find image:https://upload.wikimedia.org/wikipedia/commons/3/35/Tux.svg[Linux,25,35] everywhere these days.
The value of imagesdir is ignored when the image target is a URI.

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:

Using a URL as the base URL for images
:imagesdir: https://upload.wikimedia.org/wikipedia/commons

image::3/35/Tux.svg[Tux,250,350]

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

Resolves issue #470.

Additional improvements
  • Footnotes containing URLs are now parsed correctly and formatted properly when output to HTML. (#506)

A well-behaved table of contents (TOC)

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.

Additional improvements
  • toc and numbered attributes are enabled by default in the DocBook backend. (#540)

  • The TOC can be positioned to the right by assigning the value right to the toc-position, toc or toc2 attribute. (#467, #618)

  • The preamble toc has been updated with a panel-like styling in the default Asciidoctor stylesheet (as seen on asciidoctor.org). (#507)

Markdown-style horizontal rules

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.

Recognized Markdown horizontal rule syntax
---

- - -

***

* * *

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.

Content, more or less

Include content from a URI

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

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

:asciidoctor-source: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master

include::{asciidoctor-source}/README.adoc[]

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

:asciidoctor-source: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master

[source,ruby]
----
include::{asciidoctor-source}/lib/asciidoctor/helpers.rb[lines=10..30]
----

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:

  • install the open-uri-cached gem

  • set the cache-uri attribute

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

Resolves issue #445.

Additional improvements
  • The include directive now resolves files relative to the current document instead of the root document. This applies to include directives used inside a file which itself has been included. (#572)

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.

docinfo

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.

docinfo1

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.

docinfo2

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

Resolves issue #486.

Additional enhancements
  • Attributes are substituted in the content of docinfo files (both header and footer). (#403)

  • The "Last updated" line in the footer can be disabled by unassigning the attribute last-update-label (#407)

Ignore front matter added for static-site generators

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:

-(1)
layout: default (2)
-(1)
= Document Title

content
1 Front matter delimiters
2 Front matter data

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.

Awestruct can get the information it needs directly from AsciiDoc attributes defined in the document header, eliminating the need to worry about front matter at all.

Resolves issue #502.

Backend boost

Stylesheets are embedded by default

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

Asciidoctor does not yet copy a user-specified stylesheet when the linkcss stylesheet is set.

Resolves issue #428.

Auxiliary stylesheets

Asciidoctor will also embed the stylesheet that provides the theme for either the CodeRay or Pygments syntax highlighter by default.

For CodeRay

If the source-highlighter attribute is coderay and the coderay-css attribute is class, the CodeRay stylesheet is:

  • embedded if linkcss is not set (default behavior)

  • copied to the file asciidoctor-coderay.css inside the stylesdir folder within the output directory if linkcss is set

For Pygments

If the source-highlighter attribute is pygments and the pygments-css attribute is class, the Pygments stylesheet is:

  • embedded if linkcss is not set (default behavior)

  • copied to the file asciidoctor-pygments.css inside the stylesdir folder within the output directory if linkcss is set

Resolves issue #381.

Multiple custom template directories

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.

$ asciidoctor -T /path/to/original/templates -T /path/to/modified/templates sample.adoc

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

Asciidoctor.render_file 'sample.adoc', :safe => :safe, :in_place => true,
    :template_dirs => ['/path/to/original/templates', '/path/to/modified/templates']

Hack away!

Resolves issue #437.

Additional improvements
  • The template engine option in the API (i.e., :template_engine) is now mapped as the --template-engine (long) or -E (short) option in the CLI. This option is used for resolving the location of backend templates relative to path specified using the --template-dir (long) or -T (short) option. (#406)

  • Backend templates are now cached so that they are not reloaded each time Asciidoctor is invoked in the same Ruby process. By default, Asciidoctor uses an internal cache, though a custom cache can be passed to the API using the option :template_cache. (#438)

Man pages in AsciiDoc

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:

  • mantitle

  • manvolnum

  • manname

  • manpurpose

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:

= asciidoctor(1)
:doctype: manpage

== NAME
asciidoctor - converts AsciiDoc source files...

== SYNOPSIS
*asciidoctor* ['OPTION']... 'FILE'...

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

mantitle

asciidoctor

manvolnum

1

manname

asciidoctor

manpurpose

converts AsciiDoc source files…​

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.

Additional improvements
  • Asciidoctor produces the same output as AsciiDoc when rendering a man page to HTML using the html5 backend. (#489)

  • The Asciidoctor Backends repository hosts an early draft of a manpage backend, which is now used to generate the man page for Asciidoctor.

Extensions!

Ever since I started working on Asciidoctor, I’ve been eagerly awaiting the chance to work on the extensions API. That time has come. I’m excited to say that extensions are available as a technology preview in Asciidoctor 0.1.4.

Technology Preview

The extension API should be considered experimental and subject to change. This technology preview is intended for developers interested in playing around with it and helping to mature the design.

If you need the capabilities that extensions provide now, don’t be afraid to jump on board. Just keep in mind that you may need to rework parts of your extensions when you upgrade Asciidoctor.

Introduction

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:

  • they are challenging to write because they work at such a low-level (read as: nasty regular expressions)

  • they are fragile since they rely on system commands to do anything significant

  • they are hard to distribute due to the lack of integration with a formal distribution system

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

Extension points

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

Preprocessor

Processes the raw source lines before they are passed to the parser.

Treeprocessor

Processes the Asciidoctor::Document (AST) once parsing is complete.

Postprocessor

Processes the output after the document has been rendered, but before it’s written to disk.

Block processor

Processes a block of content marked with a custom block style (i.e., [custom]). (similar to an AsciiDoc filter)

Block macro processor

Registers a custom block macro and processes it (e.g., gist::12345[]).

Inline macro processor

Registers a custom inline macro and processes it (e.g., btn:[Save]).

Include processor

Processes the include::<filename>[] directive.

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

Asciidoctor::Extensions.register do |document|
  preprocessor FrontMatterPreprocessor
  treeprocessor TerminalCommandTreeprocessor
  postprocessor CustomFooterPostprocessor
  block :yell, YellBlock
  block_macro :gist, GistMacro if document.basebackend? 'html'
  inline_macro :man, ManpageMacro
end

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.

There is currently no extension point for processing a built-in block, such as a normal paragraph. Look for that feature in a future Asciidoctor release.

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.

For those of you on the JVM, yes, you can write extensions in Java. We’ve prototyped it and it works. We’re still sorting out a few technical challenges and documentation to make it completely smooth, but we’ll get there. For details, follow the discussion in issue #97.

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.

Example extensions

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

Preprocessor example

Purpose

Skim off front matter from the top of the document that gets used by site generators like Jekyll and Awestruct.

sample-with-front-matter.ad
---
tags: [announcement, website]
---
= Document Title

content

[subs="attributes,specialcharacters"]
.Captured front matter
....
---
{front-matter}
---
....
FrontMatterPreprocessor
require 'asciidoctor'
require 'asciidoctor/extensions'

class FrontMatterPreprocessor < Asciidoctor::Extensions::Preprocessor
  def process reader, lines
    return reader if lines.empty?
    front_matter = []
    if lines.first.chomp == '---'
      original_lines = lines.dup
      lines.shift
      while !lines.empty? && lines.first.chomp != '---'
        front_matter << lines.shift
      end

      if (first = lines.first).nil? || first.chomp != '---'
        lines = original_lines
      else
        lines.shift
        @document.attributes['front-matter'] = front_matter.join.chomp
        # advance the reader by the number of lines taken
        (front_matter.length + 2).times { reader.advance }
      end
    end
    reader
  end
end
Usage
Asciidoctor::Extensions.register do |document|
  preprocessor FrontMatterPreprocessor
end

Asciidoctor.render_file 'sample-with-front-matter.ad', :safe => :safe, :in_place => true

Treeprocessor example

Purpose

Detect literal blocks that contain terminal commands, strip the prompt character and style the command using CSS in such a way that the prompt character cannot be selected (as seen on help.github.com).

sample-with-terminal-command.ad
 $ echo "Hello, World!"

 $ gem install asciidoctor
TerminalCommandTreeprocessor
class TerminalCommandTreeprocessor < Asciidoctor::Extensions::Treeprocessor
  def process
    process_blocks @document if @document.blocks?
  end

  def process_blocks node
    node.blocks.each_with_index do |block, i|
      if block.context == :literal && block.lines.first.start_with?('$ ')
        node.blocks[i] = convert_to_terminal_listing block
      else
        process_blocks block if block.blocks?
      end
    end
  end

  def convert_to_terminal_listing block
    attributes = block.attributes
    attributes['role'] = 'terminal'
    lines = block.lines.map do |line|
      line = block.sub_specialcharacters line.chomp
      if line.start_with? '$ '
        %(<span class="command">#{line[2..-1]}</span>)
      else
        line
      end
    end
    Asciidoctor::Block.new @document, :listing, :content_model => :verbatim, :subs => [],
        :source => lines * "\n", :attributes => attributes
  end
end
Usage
Asciidoctor::Extensions.register do |document|
  treeprocessor TerminalCommandTreeprocessor
end

Asciidoctor.render_file 'sample-with-terminal-command.ad', :safe => :safe, :in_place => true

Postprocessor example

Purpose

Insert custom footer text.

CustomFooterPostprocessor
class CustomFooterPostprocessor < Asciidoctor::Extensions::Postprocessor
  def process output
    content = 'Copyright Acme, Inc.'
    if @document.basebackend? 'html'
      replacement = %(<div id="footer-text">\\1<br>\n#{content}\n</div>)
      output = output.sub(/<div id="footer-text">(.*?)<\/div>/m, replacement)
    elsif @document.basebackend? 'docbook'
      replacement = %(<simpara>#{content}</simpara>\n\\1)
      output = output.sub(/(<\/(?:article|book)>)/, replacement)
    end
    output
  end
end
Usage
Asciidoctor::Extensions.register do |document|
  postprocessor CustomFooterPostprocessor
end

Asciidoctor.render_file 'sample.ad', :safe => :safe, :in_place => true

Block processor example

Purpose

Register a custom block style named yell that uppercases all the words and converts periods to exclamation points.

sample-with-yell-block.ad
[yell]
The time is now. Get a move on.
YellBlock
require 'asciidoctor'
require 'asciidoctor/extensions'

class YellBlock < Asciidoctor::Extensions::BlockProcessor
  option :contexts, [:paragraph]
  option :content_model, :simple

  def process parent, reader, attributes
    lines = reader.lines.map {|line| line.upcase.gsub(/\.( |$)/, '!\\1') }
    Asciidoctor::Block.new parent, :paragraph, :source => lines, :attributes => attributes
  end
end
Usage
Asciidoctor::Extensions.register do |document|
  block :yell, YellBlock
end

Asciidoctor.render_file 'sample-with-yell-block.ad', :safe => :safe, :in_place => true

Block macro processor example

Purpose

Create a block macro named gist for embedding a gist.

sample-with-gist-macro.ad
.My Gist
gist::123456[]
GistMacro
require 'asciidoctor'
require 'asciidoctor/extensions'

class GistMacro < Asciidoctor::Extensions::BlockMacroProcessor
  def process parent, target, attributes
    title = (attributes.has_key? 'title') ?
        %(\n<div class="title">#{attributes['title']}</div>) : nil
    source = %(<div class="gistblock">#{title}
<div class="content">
<script src="https://gist.github.com/#{target}.js"></script>
</div>
</div>)
    Asciidoctor::Block.new parent, :pass, :content_model => :raw, :source => source
  end
end
Usage
Asciidoctor::Extensions.register do |document|
  if document.basebackend? 'html'
    block_macro :gist, GistMacro
  end
end

Asciidoctor.render_file('sample-with-gist.ad', :safe => :safe, :in_place => true)

Inline macro processor example

Purpose

Create an inline macro named man that links to a manpage.

sample-with-man-link.ad
See man:gittutorial[7] to get started.
ManpageMacro
require 'asciidoctor'
require 'asciidoctor/extensions'

class ManpageMacro < Asciidoctor::Extensions::InlineMacroProcessor
  option :pos_attrs, ['volnum']

  def process parent, target, attributes
    text = manname = target
    suffix = ''
    target = "#{manname}.html"
    if (volnum = attributes.fetch('volnum', nil))
      suffix = "(#{volnum})"
    end
    @document.register(:links, target)
    %(#{Asciidoctor::Inline.new(parent, :anchor, text, :type => :link, :target => target).render}#{suffix})
  end
end
Usage
Asciidoctor::Extensions.register do |document|
  inline_macro :man, ManpageMacro
end

Asciidoctor.render_file('sample-with-man-link.ad', :safe => :safe, :in_place => true)

Include processor example

Purpose

Include a file from a URI.

sample-with-uri-include.ad
:source-highlighter: coderay

.Gemfile
[source,ruby]
----
include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/Gemfile[]
----
UriIncludeProcessor
require 'asciidoctor'
require 'asciidoctor/extensions'
require 'uri-open'

class UriIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
  def handles? target
    target.start_with?('http://') or target.start_with?('https://')
  end

  def process reader, target, attributes
    content = open(target).readlines
    reader.push_include content, target, target, 1, attributes
  end
end
Usage
Asciidoctor::Extensions.register do |document|
  include_processor UriIncludeProcessor
end

Asciidoctor.render_file('sample-with-uri-include.ad', :safe => :safe, :in_place => true)

AsciiDoc compatibility file updates

The following improvements have been made to the AsciiDoc compatibility file, compat/asciidoc.conf:

  • Added level 5 (<h6>) section titles

  • Recognize attributes in link macro when linkattrs is set

  • Removed linkcss attribute

  • Fixed detection of fenced code blocks

  • Recognize XML-style callouts

  • Don’t prepend imagesdir to image target if it is a URI or absolute path

  • Add float attribute to image inline macro

  • Calculate alt text from image filename in a manner consistent with Asciidoctor

  • Recognize markdown-style horizontal rules

Resolves issue #441 and other related issues.

Acknowledgments

The best part of Asciidoctor is its community. We’d like to thank the following people for contributing to and participating in this release:

We’d like to give a special shout out to Alex Soto and Xavier Coulon for making their first code contributions to the main Asciidoctor repository and to Per Anderssen for getting Asciidoctor into Debian and Ubuntu!

I (Dan) would also like to thank Sarah White for her monstrous effort to pull together the documentation and prepare a documentation workflow for the project.

Additional thanks to everyone who is using the project and those who have participated in the growing ecosystem of sub-projects. The mission of Asciidoctor is to help you write, publish and communicate your content successfully, and enjoy doing it! With your feedback and participation, we can achieve that goal together! We encourage you to ask questions and discuss any aspects of the project on the mailing list or IRC.

If you discover errors or omissions in the source code, documentation, or website content, please don’t hesitate to submit an issue or open a pull request with a fix. We’re always eager to learn about your experiences and how we can help improve them. Together, we’re going to make 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.

The next release of Asciidoctor will be 1.5.0. The focus of release will be on improvements to the extension API, additional syntax conveniences and enhancements to the toolchain.

We’re making a shift in the version number scheme in the next release to make room for point releases and to get out from underneath 1.0.0.

We hope to keep the Asciidoctor 1.5.0 release a bit more manageable and turn around a release in ~2 months. With your participation and feedback, we can make it happen!

Appendix A: TL;DR

  • Stylesheets are embedded by default

  • Inter-document cross references (e.g., <<doc-b#section-a,Section A in Document B>>)

  • Implicit header row on tables

  • DocBook 5.0 backend (i.e., docbook5)

  • Icon inline macro (e.g, icon:heart[2x]), designed primarily for using font-based icons

  • Checklists

  • Developer and user-friendly callouts in code listings

  • Pygments syntax highlighter (e.g., source-highlighter=pygments)

  • Shorthand notation for block options (e.g., [%header%footer])

  • Shorthand notation for id and role on formatted text (e.g., [#id.role]_text_)

  • Roles for text enclosed in backticks (e.g., [role]`text`)

  • Docinfo files for the document footer (e.g., docinfo-footer.(html|xml))

  • Include file from URL using include::[] directive

  • Include file is resolved relative to current include file

  • Support for YouTube and Vimeo IDs in video macro (e.g., video::12345[youtube,480,360])

  • Missing attribute references (e.g., {bogus}) do not cause line to be dropped (by default)

  • Parse manpage metadata

  • TOC positioning (e.g., toc-position=right, toc=right or toc2=right)

  • Improved section numbering in document and in TOC

  • First draft of the Asciidoctor User Manual

  • Debian and Ubuntu packages (joining the Fedora package)

See the 0.1.4 Changelog for a complete list of changes.


Easier Documentation, Simpler Websites And Faster Collaboration @ OSCON 2013

by Dan Allen -

Do you find producing and collaborating on documentation or web content difficult? At OSCON 2013, we’ll work with you to reduce the friction of creating content by simplifying your content workflow, teaching you how to collaborate more efficiently and helping to make writing and publishing enjoyable!

OSCON banner

Join us on Tuesday, July 23 at our workshop titled Easier Documentation, Simpler Websites And Faster Collaboration to learn about tools and techniques that lighten your documentation workload and jumpstart your content strategy. To attend, register for OSCON 2013, then sign up for the workshop!

TIP: Use code ARQIKE for a 20% discount off registration!

How?

It begins with writing content…​

…​in the same format you use to write e-mail.

Plain text *embellished* with _subtle_ markup.

Indeed, that’s the focus of the lightweight markup language AsciiDoc. The AsciiDoc syntax feels natural and that keeps you focused on the content. Content written in AsciiDoc is easy to read and edit in raw form, which facilitates collaboration. It can also be translated into HTML for presentation, hello web publishing!

Zurb Foundation Yeti

Next, we do some baking.

After composing some documentation in AsciiDoc, we’ll pull together our content into a cohesive website using the static site generators Awestruct and Jekyll. Then we’ll leverage CSS frameworks like Bootstrap and Zurb Foundation to dress up the content with an elegant look and feel.

It’s push to publish!

We’ll then publish our website to GitHub Pages using a single command, git push.

That’s when the real fun starts. From GitHub, we can collaborate on the content using git and the web-based collaboration tools in the GitHub interface.

Revision history in GitHub
The revision history is safely tucked away in the git repository.

Don’t forget to chunk!

There are billions of devices connected to the web. And more are coming. Regardless of how the device market changes over time, the challenge for us remains the same. We need to get our content on all of them.

AsciiDoc is more than just a lightweight markup language. It enables and encourages us to write reusable, structured content.

Chunking Reusable content can be mixed and matched with other content to create a composition that suits a device, context or situation. It’s also a way to keep our content DRY (Don’t Repeat Yourself) so we don’t have to update the same content in a dozen places, or even two.

Structured content is meaningful, semantic content that is flagged using metadata. We can do lots of things with a document if we know what’s in it. We can pull out a lead or excerpt. We can hide content when it isn’t needed. We can present a structure and allow the user to drill into what they want to see.

Content no longer lives on a “page”. The future unit of publishing is the “chunk”. These smaller, discrete sources can be tuned to specific platforms or aggregated using automation.

The web is changing. It’s left the desktop. It’s now a road warrior. The way we think about content publishing must adapt. More than ever before, we must separate content from presentation.

Recap

Writing documentation is hard. So we don’t do it often enough. And yet, we’re skipping out on the best opportunity to reach and influence our target audience. Let’s do something about it.

  • lightweight markup makes writing documentation easier

  • static site generators and CSS frameworks make websites simpler

  • git and GitHub make collaborating on content and publishing it online faster

…​all powered by open source software:

Ruby

Git

AsciiDoc / Asciidoctor

Awestruct

Jekyll

Haml / Slim

SASS / Compass

Zurb Foundation

Travis CI

Let’s bake better documentation, together. Documentation that’s reusable and structured.

What, Where and When?

Title:

Easier Documentation, Simpler Websites And Faster Collaboration

Date:

Tuesday, July 23, 2013

Time:

1:30 - 5:00 PM (3h 30m)

Room:

D139/140, Oregon Convention Center

Type:

Workshop

Category:

Tools & Techniques

You can find all the details about the workshop, including the session abstract, on the official session page.

Who?

Attendees

Open source community members like you who are passionate about documentation and web publishing.

Not sure if that’s you? Do you contribute to, maintain or organize any of the following?

  • manuals, user guides, tutorials or READMEs

  • news, press releases or announcements

  • articles or books

  • brochures or press kits

  • conference or event information

  • request for proposals (RFPs)

  • resume or personal site

If you nodded, then you’re one of us :)

Trainers

Dan Allen Dan Allen

Dan is an open source advocate, community catalyst, author and speaker. He proudly pursues these passions as a Red Hat employee and community member.

In his role as Principal Software Engineer at Red Hat, he leads the Asciidoctor project and serves as the community manager for Arquillian. He draws on these experiences to help make a variety of open source projects wildly successful. Besides drinking a Trappist beer or indulging in Belgian chocolate, there’s nothing he’d rather do.

Sarah White Sarah White

Sarah is the content strategist for both the Arquillian and Asciidoctor projects—​an ideal position for someone passionate about open source, alien invasions and writing.

If there’s room for improvement, Sarah will find it. Lots of it.

Long ago, in a not-too-distant galaxy, she assessed hazardous waste sites and tracked pesticide routes through watersheds. So she knows a thing or two about identifying and eradicating stuff that kills, including software bugs and poor documentation.

Prerequisites

Knowledge of HTML and being comfortable using the commandline are both essential. Some knowledge of git and Ruby is useful, though a novice should be able to pick up the necessary training “on the job”.

Reading list

We’ve prepared some reading material that will give you a better idea of what the session is about and what you’ll be learning. These resources should also help you continue to learn about the subject after the workshop is over.

A full list of resources is available on the Reference Resources page on the workshop’s wiki.

We look forward to seeing you at OSCON!


Asciidoctor Maven plugin 0.1.3.1 released!

by Jason Porter -

I’m proud to announce the Asciidoctor Maven plugin 0.1.3.1 release! This is simply a bug fix release to correct some of the things I messed up with 0.1.3 (sorry about that). Like version 0.1.3 before it, it’s based on the same version of the Asciidoctor Java integration project and the Asciidoctor projects — 0.1.3.

Thank you to all the contributors for helping out.

Go forth and make great documentation once again!

Plugin artifact information
Group ID Artifact ID Latest versions Download

org.asciidoctor

asciidoctor-maven-plugin

0.1.3.1

pom jar

Upgrading to 0.1.3.1 (recommended) is simple. Just update the version in your Maven POM. All necessary dependencies should be pulled in via Maven.

For more information about issues fixed in this release, please see the 0.1.3.1 milestone in the issue tracker!


Asciidoctor Maven plugin 0.1.3 released!

by Jason Porter -

It has taken me a little while longer to get this release out the door than I would have hoped, but it’s here at last! I’m proud to release Asciidoctor Maven plugin version 0.1.3! Like the other versions before it, it is based on the same version of the Asciidoctor Java integration project and the Asciidoctor projects — 0.1.3.

There’s very little new things for the end user in this release as the changes were mostly to use some of the new ease of use things from the Java Integration project.

I would like to call out the help of Brian Leathem in this release in helping me go through a few things and pushing me to release it. Also, thank you to all the contributors for helping out.

Go forth and make great documentation once again!

Plugin artifact information
Group ID Artifact ID Latest versions Download

org.asciidoctor

asciidoctor-maven-plugin

0.1.3

pom jar

Upgrading to 0.1.3 (recommended) is simple. Just update the version in your Maven POM. All necessary dependencies should be pulled in via Maven.

For more information about issues fixed in this release, please see the 0.1.3 milestone in the issue tracker!


Write Javadocs in AsciiDoc with Asciidoclet

by John Ericksen -

We’re excited to announce the newest member of the Asciidoctor family, Asciidoclet. Asciidoclet is a Javadoc Doclet based on Asciidoctor that enables developers to write Javadoc comments using the AsciiDoc syntax.

Motivation

From the very beginning, a concept the designers of Java got right was to include documentation with source code. This allowed documentation to stay closer in sync with ever-changing source and allowed multiple viewing platforms, most notably the HTML generation and IDE integration.

The main drawback of Javadoc has been the requirement to use embedded HTML fragments to achieve advanced (or even modest) formatting. This is where the AsciiDoc integration shines. Being a lightweight markup language, AsciiDoc gives developers access to advanced formatting without having to fiddle with low-level HTML markup. In other words, developers can focus on the content rather than the markup and still achieve a beautiful end result.

Pairing AsciiDoc with Javadocs means readable source and beautifully rendered Javadocs, the best of both worlds!

Usage

Once Asciidoclet is plugged into Javadoc, it’s just a matter of using AsciiDoc mark up in Javadocs. The following example demonstrates a number of features of Asciidoclet:

/**
 * = Asciidoclet (1)
 *
 * Sample comments that include +source code+. (2)
 *
 * [source,java] (3)
 * --
 * public class Asciidoclet extends Doclet {
 *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
 *
 *     @SuppressWarnings("UnusedDeclaration") (4)
 *     public static boolean start(RootDoc rootDoc) {
 *         new Asciidoclet().render(rootDoc);
 *         return Standard.start(rootDoc);
 *     }
 * }
 * --
 *
 * @author https://github.com/johncarl81[John Ericksen] (5)
 */
public class Asciidoclet extends Doclet {
}
1 Titles are easy to create using the = markup.
2 Paragraphs are the default and do not require the <p> html tag. Inline source may be marked up by surrounding the text in + symbols.
3 Source is easily marked up using the [source,language] tag and block delimiters, --, also called "fences"
4 The notorious @ symbol is automatically handled by Asciidoclet, avoiding the standard {@literal @} boilerplate.
5 Inline AsciiDoc markup is available within Javadoc tags. This example highlights link rendering.

Distribution

Asciidoclet is published to Maven Central. The artifact information is summarized in the table below.

Artifact information for Asciidoclet
Group Id Artifact Id Version Download

org.asciidoctor

asciidoclet

0.1.3*

pom jar javadoc (jar) source (jar)

* This release is based on the Asciidoctor 0.1.3 release.

Installation

Asciidoclet is a standard Javadoc Doclet and may be used as such. One of the easiest ways to install Asciidoclet is by adding it as a Doclet to the maven-javadoc-plugin:

Maven Doclet declaration
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <doclet>org.asciidoctor.Asciidoclet</doclet>
        <docletArtifact>
           <groupId>org.asciidoctor</groupId>
           <artifactId>asciidoclet</artifactId>
           <version>${asciidoclet.version}</version>
        </docletArtifact>
    </configuration>
</plugin>

We hope that this extension helps you push your Javadocs to new heights. As always, collaboration is welcome and you may find (and fork) the source on GitHub.

A big thanks to Alex Soto of the Asciidoctor Java integration project, Jason Porter and Dan Allen for their feedback and support and everyone else who contributes to the Asciidoctor project. Writing this extension could not have been easier because of the great work and collaboration of the Asciidoctor community.


  • 4 of 7