AsciiDoc Writer’s Guide

Since adjacent lines of text are combined into a single paragraph when Asciidoctor converts 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 space followed by a plus sign (+) or set the hardbreaks option on the paragraph. This results in a visible line break (e.g., <br>) following each line.

To preserve line breaks throughout your whole document, add the hardbreaks attribute to the document’s header.

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

Asciidoctor provides several approaches for preventing substitutions.

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 supports several forms of the passthrough macro.

To exclude a phrase from substitutions and disable escaping of special characters, enclose it in the inline pass macro. For example, here’s one way to format text as underline when generating HTML from AsciiDoc:

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 source code that could make it invalid in raw form. However, 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 much 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 (*) to the marker, and another for each subsequent level.

In Asciidoctor 1.5.7 and earlier you could only have up to six (6) levels of nesting (assuming one level uses the hyphen marker).

Since Asciidoctor 1.5.8, you can nest unordered lists to any depth. Keep in mind, however, that some interfaces will begin flattening lists after a certain depth. GitHub starts flattening list after 10 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’re 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:

Asciidoctor works hard to infer the relationships between the items that are most intuitive to us humans. Here’s an example of nesting an unordered list inside of an ordered list:

You can spread the items out and indent the nested lists if that makes it more readable for you:

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:

A description list (often abbreviate as dlist) is useful when you need to include a description or supporting text for one or more terms. Each item in a description list consists of:

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

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

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

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

Description 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 description, ordered, and unordered list items:

Here’s how the list is rendered:

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

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.

You can think of these like implicit macro names (the bare email address being a special case). Since the URL in the example below begins with a protocol (in this case https followed by a colon), 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 shown with the scheme hidden, 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 https inside the <a> element.

To attach a URL to text, enclose the text in square brackets at the end of the URL, thus making it an URL macro:

When a URL does not start with one of the common schemes, or the URL is not surrounded by word boundaries, you must use the link macro. The link macro is a stronger version of a URI macro, which you can think of like an unconstrained macro. The URL is preceded by link: and followed by square brackets. The square brackets may include optional link text. The URL is used for the text of the link if link text is not specified. Prior to 1.5.7, if the linkattrs document attribute is set, the text in square brackets is parsed as attributes, which allows a window name or role to be specified. Since 1.5.7, attributes are parsed automatically if an equal sign is found after a comma (e.g., [link text,window=_blank]).

Let’s consider a case where we need to use the link macro (instead of just a URI macro) to expand a link when it’s not adjacent to a word boundary (i.e., unconstrained).

If we didn’t use the link: prefix in this case, the URL macro would not be detected by the parser.

Prior to 1.5.7, Asciidoctor does not parse attributes in the link macro by default. If you want attributes in the link macro to be parsed, you must set the linkattrs document attribute in the header. Since 1.5.7, this parsing is automatic (and the attribute is not required) if an equal sign is found after a comma. When attribute parsing is enabled, 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 attribute parsing is enabled, 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 inline xref macro is used to create cross references (also called in-text or page citations) to content elements (sections, blocks, or phrases) that have an ID (regardless of whether that ID is explicit or auto-generated).

You create a cross reference 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, referred to as a natural cross reference. The title must contain at least one space character or contain at least one uppercase letter. (If you are using Ruby < 2.4, that uppercase letter is restricted to the basic Latin charset).

Converters usually use the reftext of the target as the default text of the link. When the document is parsed, attribute references in the reftext are substituted immediately. When the reftext is displayed, additional reftext substitutions are applied to the text (specialchars, quotes, and replacements).

You can override the reftext of the target by specifying alternative text at the location of the cross reference. 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.

In the link that is created from the inter-document cross reference, the source file extension is replaced with the value of the outfilesuffix attribute. To customize the file extension used in the target of the link, simply change the value of this attribute.

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.

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 sectnums 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:

The “anything goes” mechanism in AsciiDoc is the passthrough block. As the name implies, this block passes the content of the block directly through to the output document. When you’ve encountered a complex requirement that you cannot meet using the AsciiDoc syntax, a passthrough block can come in very handy.

For example, let’s say you want to embed a GitHub gist into your document. You can define the following passthrough block: