AsciiDoc Writer’s Guide

Since adjacent lines of text are combined into a single paragraph when Asciidoctor renders a document, that means you can wrap paragraph text or put each sentence or phrase on a separate line. The line breaks won’t appear in the output.

However, if you want the line breaks in a paragraph to be preserved, you can either use a plus sign (+) or the hardbreaks attribute. This results in a visible line break (e.g., <br>) following each line.

Alternatively, you can preserve line breaks throughout your whole document by adding the hardbreaks attribute to the document’s header.

You can also preserve line breaks using literal blocks, listing blocks, and verses.

For instance, in an e-mail, you might “speak” a word louder by enclosing it in asterisks.

As you would expect, the asterisks make the text won bold. You can almost sense the emotion. This is one example of quoted (i.e., formatted) text.

Here are the forms of quoted text that AsciiDoc recognizes:

When you want to quote text (e.g., place emphasis) somewhere other than at the boundaries of a word, you need to double up the punctuation.

Any quoted text can be prefixed with an attribute list. The first positional attribute is treated as a role. The role can be used to apply custom styling to the text. For instance:

When rendering to HTML, the word “asciidoc” is wrapped in <span> tags and the role is used as the element’s CSS class:

You can apply styles to the text using CSS.

You may not always want these substitutions to take place. In those cases, you’ll need to use markup to escape the text.

If you are getting quoted text behavior where you don’t want it, you can use a backslash or a passthrough macro to prevent it.

To prevent punctuation from being interpreted as formatting markup, precede it with a backslash (\). If the formatting punctuation begins with two characters (e.g., __), you need to precede it with two backslashes (\\). This is also how you can prevent character and attribute references from substitution. When your document is processed, the backslash is removed so it doesn’t display in your output.

Asciidoctor provides several ways to write a passthrough macro.

The pass macro can be applied to inline or block content. You can include a comma-separated list of substitutions prior to the passthrough content.

To exclude a phrase from substitutions and disable escaping of special characters, enclose it in the inline pass macro:

If you want to enable ad-hoc quotes substitution, then assign the macros value to subs and use the inline pass macro.

The inline pass macro does introduce additional markup into the Java source code that makes it invalid in raw form, but the output it produces will be valid when viewed in a viewer (HTML, PDF, etc.).

The inline pass macro also accepts shorthand values for specifying substitutions.

For example, the quotes text substitution value is assigned in the inline passthrough macro below:

The triple-plus passthrough works the same way as the pass macro. To exclude content from substitutions, enclose it in triple pluses (+++).

The triple-plus macro is often used to output custom HTML or XML.

To exclude a phrase from substitutions, enclose it in plus signs (+).

AsciiDoc also recognizes textual representations of symbols, arrows and dashes.

This mild punctuation does not take away from the readability of the text. In fact, you could argue that it makes the text easier to read. What’s important is that these are conventions with which you are likely already familiar.

Punctuation is used in AsciiDoc to create another very common type of element in documents, lists!

If you were to create a list in an e-mail, how would you do it? Chances are, you’d mark list items using the same characters that Asciidoctor uses to find list items.

In the example below, each list item is marked using an asterisk (*), the AsciiDoc syntax specifying an unordered list item.

A list item’s first line of text must be offset from the marker (*) by at least one space. If you prefer, you can indent list items. Blank lines are required before and after a list. Additionally, blank lines are permitted, but not required, between list items.

You can add a title to a list by prefixing the title with a period (.).

Was your instinct to use a hyphen (-) instead of an asterisk to mark list items? Guess what? That works too!

You should reserve the hyphen for lists that only have a single level because the hyphen marker (-) doesn’t work for nested lists. Now that we’ve mentioned nested lists, let’s go to the next section and learn how to create lists with multiple levels.

To nest an item, just add another asterisk (*) in front of it.

You can have up to five levels of nesting.

While it would seem as though the number of asterisks represents the nesting level, that’s not how depth is determined. A new level is created for each unique marker encountered. However, it’s much more intuitive to follow the convention that the number of asterisks equals the level of nesting. After all, we are shooting for plain text markup that is readable as is.

Sometimes, we need to number the items in a list. Instinct might tell you to prefix each item with a number, like in this next list:

The above works, but since the numbering is obvious, the AsciiDoc processor will insert the numbers for you if you omit them:

If you decide to use number for your ordered list, you have to keep them sequential. This differs from other lightweight markup languages. It’s one way to adjust the numbering offset of a list. For instance, you can type:

However, in general the best practice is to use the start attribute to configure this sort of thing:

To present the items in reverse order, add the reversed option:

You can give a list a title by prefixing the line with a dot immediately followed by the text (without leaving any space after the dot).

Here’s an example of a list with a title:

You create a nested item by using one or more dots in front of each the item.

AsciiDoc selects a different number scheme for each level of nesting. Here’s how the previous list renders:

The following table shows the numbering scheme used by default for each nesting level.

You can override the number scheme for any level by setting its style (the first positional entry in a block attribute list). You can also set the starting number using the start attribute:

Labeled lists are useful when you need to include a description or supporting text for each item in a list. Each item in a labeled list consists of a term or phrase followed by:

Here’s an example of a labeled list that identifies parts of a computer:

By default, the content of each item is displayed below the label when rendered. Here’s a preview of how this list is rendered:

If you want the label and content to appear on the same line, add the horizontal style to the list.

The content of a labeled list can be any AsciiDoc element. For instance, we could rewrite the grocery list from above so that each aisle is a label rather than a parent outline list item.

Labeled lists are quite lenient about whitespace, so you can spread the items out and even indent the content if that makes it more readable for you:

Finally, you can mix and match the three list types within a single hybrid list. Asciidoctor works hard to infer the relationships between the items that are most intuitive to us humans.

Here’s a list that mixes labeled, ordered, and unordered list items:

Here’s how the list is rendered:

You can include more complex content in a list item as well.

Aside from nested lists, all of the list items you’ve seen only have one line of text. A list item can hold any type of AsciiDoc content, including paragraphs, listing blocks and even tables. You just need to attach them to the list item.

Like with regular paragraph text, the text in a list item can wrap across any number of lines, as long as all the lines are adjacent. The wrapped lines can be indented and they will still be treated as normal paragraph text. For example:

If you want to attach additional paragraphs to a list item, you “add” them together using a list continuation. A list continuation is a + symbol on a line by itself, immediately adjacent to the two blocks it’s connecting. Here’s an example:

Using the list continuation, you can attach any type of block element and you can use the list continuation any number of times in a single list item.

Here’s an example that attaches both a listing block and an admonition paragraph to the first item:

Here’s how the source is rendered:

If the principle text of a list item is blank, the node for the principle text is dropped. This is how you can get the first block (such as a listing block) to line up with the list marker. You can make the principle text blank by using the {blank} attribute reference.

Here’s an example of a list that has items with only complex content.

Here’s how the source is rendered:

There’s nothing you have to do to make a link to a URL. Just include the URL in the document and AsciiDoc will turn it into a link.

Asciidoctor recognizes the following common schemes without the help of any markup.

Since the URL in the example below begins with http, Asciidoctor will automatically turn it into a hyperlink when it is processed.

To prevent automatic linking of an URL, prepend it with a backslash (\).

If you prefer URLs to be rendered without a visible scheme, set the hide-uri-scheme attribute in the document’s header.

When the hide-uri-scheme attribute is set, the above URL will render as follows:

Note the absence of http inside the <a> element.

To attach a URL to text, enclose the text in square brackets at the end of the URL.

When a URL does not start with one of the common schemes, you must use the link macro. The URL is preceded by link: and followed by square brackets. The square brackets can include optional link text, target preference, and roles.

First, let’s look at an example of a link macro that contains link text.

When you set attributes in the link macro, you must also set the linkattrs attribute in the document’s header because Asciidoctor does not parse attributes in the link macro by default. Once you’ve set linkattrs in the header, you can then specify the name of the target window using the window attribute.

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

When linkattrs is set, you can add a role (i.e., CSS class) to the link.

If you want to link to an external file relative to the current document, use the link macro in front of the file name.

If your file is an HTML file, you can link directly to a section in the document, append a hash (#) followed by the section’s ID to the end of the file name.

For links to relative AsciiDoc documents cross references should be used.

A link to another location within an AsciiDoc document or between AsciiDoc documents is called a cross reference (also referred to as an xref).

In Asciidoctor, the xref inline macro is used to create cross references (i.e. links) to sections, blocks or phrases that have an ID (explicit or auto-generated).

An implicit cross reference is created by enclosing the ID of the target block or section (or the path of another document with an optional anchor) in double angled brackets.

You can also link to a block or section using the title by referencing its title. However, the title must begin with an uppercase letter (in basic Latin) without any leading formatting marks.

Some converters, such as the HTML converter, will use the xreflabel as the default text of the link. However, you can also customize this text. After the ID, add a comma and then enter the custom text you want the cross reference to display.

You can also use the inline xref macro as an alternative to the double angled bracket form.

Cross references can also be used to create a link to a file relative to the current document. For links to another AsciiDoc document, this is the preferred way.

The trailing hash (#) means that you refer to the top of the document.

To link directly to a section in the document, append the section’s ID after the hash (#)

In both cases, this syntax will also work if you are inside the document you are referring to. This is useful if you are sharing the same link across multiple documents.

Image references are similar to links since they are also references to URLs or files. The difference, of course, is that they display the image in the document.

To include an image on its own line (i.e., a block image), use the image:: prefix in front of the file name and square brackets after it:

If you want to specify alt text, include it inside the square brackets:

You can also give the image an id, a title (i.e., caption), set its dimensions (i.e., width and height) and make it a link:

The title of a block image is displayed underneath the image when rendered. Here’s a preview:

If you want to include an image inline, use the image: prefix instead (notice there is only one colon):

For inline images, the optional title is displayed as a tooltip.

You can also include other types of media, such as audio and video. Consult the Audio and video block macros section of the AsciiDoc User Guide for details.

If paragraphs and lists are the meat of the document, then titles and sections are its bones. Let’s explore how to give structure to our document.

Just as every e-mail has a subject, every document (typically) has a title. The title goes at the top of an AsciiDoc document.

To create a document title, begin the first line of the document with one equal sign followed by at least one space (= ), then the text of the title. This syntax is the simplest (and thus recommended) way to declare a document title.

Here’s an example of a document title followed by an abbreviated paragraph:

The document title is part of the document header. So what else can go in the header? Good question.

Attributes are one of the features that sets AsciiDoc apart from other lightweight markup languages. You can use attributes to toggle features or to store reusable or replacement content.

Most often, attributes are defined in the document header. There are scenarios where they can be defined inline, but we’ll focus on the more common usage.

An attribute entry consists of a name surrounded by colons at the beginning of the line followed by at least one space, then the content. The content is optional.

Here’s an example of an attribute that holds the version of an application:

Now you can refer to this attribute anywhere in the document (where attribute substitution is performed) by surrounding the name in curly braces:

Attributes are also commonly used to store URLs, which can get quite lengthy. Here’s an example:

Here’s the attribute in use:

Document attributes can also be used to toggle settings or set configuration variables that control the output generated by the AsciiDoc processor.

For example, to include a table of contents in your document, you can define the toc attribute:

To undefine an attribute, place a ! at the end of the name:

You can also set the base path to images (default: empty), icons (default: ./images/icons), stylesheets (default: ./stylesheets) and JavaScript files (default: ./javascripts):

When you find yourself typing the same text repeatedly, or text that often needs to be updated, consider assigning it to a document attribute and use that instead.

As your document grows, you’ll want to break the content into sections, like in this guide. That’s accomplished using section titles.

Sections partition the document into a content hierarchy. In AsciiDoc, sections are defined using section titles.

A section title uses the same syntax as a document title, except the line may begin with two to six equal signs instead of just a single equal sign. The number of equal signs represents the nesting level (using a 0-based index).

Here are all the section levels permitted in an AsciiDoc document (for an article doctype, the default), shown below the document title:

Section levels cannot be chosen arbitrarily. There are two rules you must follow:

For example, the following syntax is illegal:

Content above the first section (after the document title) is part of the preamble. Once the first section is reached, content is associated with the section that precedes it:

To have the processor auto-number the sections, define the numbered attribute in the document header:

You can also use this attribute entry above any section title in the document to toggle the auto-numbering setting. When you want to turn off the numbering, add an exclamation point to the end of the attribute name:

You can assign a title to any paragraph, list or delimited block element. The title is used as the element’s caption. In most cases, the title is displayed immediately above the content. If the content is a figure or image, the title is displayed below the content.

A block title is defined on a line above the element. The line must begin with a dot (.) and be followed immediately by the title text with no spaces in between.

Here’s an example of a list with a title:

Speaking of block titles, let’s dig into blocks and discover which types of blocks AsciiDoc supports.

For instance, an example block can act as an admonition block:

At the start of this tutorial, remember how painful we said it is to insert source code into a document using a traditional word processor. They just aren’t designed for that use case. AsciiDoc is!

In fact, inserting source code in an AsciiDoc is incredibly easy. Just shove the raw code into a listing block.

To enable syntax highlighting in the output, set the style on the block to source and specify the source language in the second attribute position.

You can even use source code that’s in a separate file. Just use the AsciiDoc include directive:

To really show how well-suited AsciiDoc is for technical documentation, it also supports callouts in source code. Code callouts are used to explain lines of source code. The explanations are specified below the listing and keyed by number. Here’s an example:

Here’s how the callouts appear when rendered:

The most versatile block of all is the open block. An open block can act as any other block, with the exception of pass and table. Here’s an example of an open block acting as a sidebar: