Asciidoctor reads content written in plain text, as shown in the panel on the left in the image below, and converts it to HTML5, as shown rendered in the right panel. Asciidoctor adds a default stylesheet to the HTML5 document, as shown, to provide a pleasant out-of-the-box experience.

You can run Asciidoctor on the JVM using JRuby. You can also use AsciidoctorJ to invoke Asciidoctor’s APIs from Java and other JVM languages.

Asciidoctor can be used in JavaScript. Opal is used to transcompile the code from Ruby to JavaScript to make Asciidoctor.js, which can be used wherever JavaScript runs, such as in a web browser or on Node.js.

While Asciidoctor aims to offer full compliance with the AsciiDoc syntax, it’s more than just a clone.

Asciidoctor uses a set of built-in ERB templates to generate HTML 5 and DocBook output that is structurally equivalent to what AsciiDoc produces. Any of these templates can be replaced by a custom template written in any template language available in the Ruby ecosystem. Custom template rendering is handled by the Tilt template abstraction library. Tilt is one of the most popular gems in the Ruby ecosystem.

Leveraging the Ruby stack isn’t the only benefit of Asciidoctor. Unlike the AsciiDoc Python implementation, Asciidoctor parses and renders the source document in discrete steps. This makes rendering the document optional and gives Ruby programs the opportunity to extract, add or replace information in the document by interacting with the document object model Asciidoctor assembles. Developers can use the full power of the Ruby programming language to play with the content in the document.

No coverage of Asciidoctor would be complete without mention of its speed. Despite not being an original goal of the project, Asciidoctor has proven startlingly fast. It loads, parses and renders documents 25 times as fast as the Python implementation. That’s good news for developer productivity and good news for GitHub or any server-side application that needs to render AsciiDoc markup. Asciidoctor also offers several levels of security, further justifying its suitability for server-side deployments.

Asciidoctor’s usage is not limited to the Ruby community. Thanks to JRuby, a port of Ruby to the JVM, Asciidoctor can be used inside Java applications as well. Plugins are available for Apache Maven, Gradle, and Rewrite. These plugins are based on the AsciidoctorJ for Asciidoctor.

Asciidoctor also ships with a command line interface (CLI). The Asciidoctor CLI, asciidoctor, is a drop-in replacement for the asciidoc.py script from the AsciiDoc Python distribution.

The most compelling reason to choose a lightweight markup language for writing is to minimize the amount of technical concepts that an author must grasp in order to be immediately productive. In other words, the goal is to write without friction.

A popular choice is Markdown. (At least, that’s what you call it in the beginning). The main advantage of Markdown lies in its primitive syntax: its manual and cheatsheet are one and the same. But this advantage is also its greatest shortcoming.

As soon as authors need something slightly more complex (tables, cross references, footnotes, embedded YouTube videos, etc.), they find themselves diving directly into HTML or seeking out alternate implementations. Markdown has become a maze of different implementations, termed “flavors”, which make a universal definition evasive.

Here’s how the story inevitably goes. You start out with Markdown. Then it’s Markdown + X. Then Markdown + X + Y. And down the rabbit hole you go. What’s worse, X and Y often take the form of HTML, unnecessarily coupling content with presentation and wrecking portability. Your instinct to choose Markdown is good. There are just better options.

AsciiDoc presents a more sound alternative. The AsciiDoc syntax is more concise than (or at least as concise as) Markdown. At the same time, AsciiDoc offers power and flexibility without requiring the use of HTML or “flavors” for essential syntax such as tables, definition lists, admonitions (tips, notes, warnings, etc.) and table of contents.

It’s important to understand that AsciiDoc was initially designed as a plain-text alternative to the DocBook XML schema. AsciiDoc isn’t stuck in a game of whack-a-mole trying to satisfy publishing needs like Markdown. Rather, the AsciiDoc syntax was explicitly designed with the needs of publishing in mind, both print and web. If the need arises, you can make full use of the huge choice of tools available for a DocBook workflow using Asciidoctor’s DocBook converter. That’s why mapping to an enterprise documentation format like DocBook remains a key use case for AsciiDoc.

And yet, AsciiDoc is simple enough to stand in as a better flavor of Markdown. But what truly makes AsciiDoc the right investment is that its syntax was designed to be extended as a core feature. This extensibility not only means that AsciiDoc has a more to offer, with room to grow, it also fulfills the objective of ensuring your content is maximally reusable.

You can find more links to discussions about the differences between AsciiDoc and Markdown in the comments of issue #34

Asciidoctor’s command line interface (CLI) is a drop-in replacement for the asciidoc.py command from the Python implementation.

If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To confirm that Asciidoctor is available, execute:

The following information should be output in your terminal:

To invoke Asciidoctor from the CLI and render an .adoc file, execute:

This will use the built-in defaults for options and create a new file in the same directory as the input file, with the same base name, but with the .html extension.

There are many other options available, listed in CLI Options.

Full help is provided via:

or in the man page.

There is also an asciidoctor-safe command, which turns on safe mode by default, preventing access to files outside the parent directory of the source file. This mode is very similar to the safe mode of asciidoc.py.

In addition to the command line interface, Asciidoctor provides a Ruby API. The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub.

Asciidoctor also has a Java API that mirrors the Ruby API. The Java API calls through to the Ruby API using an embedded JRuby runtime. See the AsciidoctorJ project for more information.

To use Asciidoctor in your application, you first need to require the gem:

With that in place, you can start processing AsciiDoc documents. To parse a file into an Asciidoctor::Document object:

You can get information about the document:

More than likely, you will want to render the document. To render a file containing AsciiDoc markup to HTML 5, use:

The command will output to the file mysample.html in the same directory.

You can render the file to DocBook 5.0 by setting the :backend option to 'docbook':

The command will output to the file mysample.xml in the same directory. If you’re on Linux, you can view the file using Yelp.

You can also use the API to render strings and load custom templates.

To install Asciidoctor using the gem command:

If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To confirm that Asciidoctor is available, execute:

The following output should appear in your terminal:

To install Asciidoctor for a project using Bundler:

To install Asciidoctor on Fedora (or RHEL via EPEL) using the rubygem-asciidoctor package:

The benefit of installing the gem using this method is that the package manager will also install Ruby and RubyGems if not already on your machine.

To install Asciidoctor on Debian Sid or Ubuntu Saucy or greater:

The benefit of installing the gem via apt-get is that the package manager will also install Ruby and RubyGems if not already on your machine.

To install Asciidoctor on Alpine Linux using the asciidoctor package:

The benefit of installing the gem via apk is that the package manager will also install Ruby and RubyGems if not already on your machine.

In short, “constrained” means around a word or sequence of words.

Constrained quotes are single characters (often symbols) placed around a word. The “around” is defined by the fact that word characters do not appear immediately outside the enclosing marks.

You use this form to format a word that stands alone,

to format a sequence of words,

or to format a word adjacent to punctuation, like an exclamation mark.

In short, “unconstrained” means anywhere, including within a word.

Unconstrained quotes are repeated characters (often symbols) placed anywhere in the text, including within a word. The “within” is defined by the fact that a word character may appear directly outside one of the enclosing marks.

Consider the following questions:

If you answered “yes” to any of these questions, you need to switch to unconstrained (double formatting) quotes.

To help you determine whether a particular syntax pattern requires unconstrained quotes, consider the following syntactical situations.

There are cases when it might seem logical to use constrained quotes, however unconstrained quotes are required. This happens because of the way the Asciidoctor parser (and the AsciiDoc Python parser) currently handles substitutions.

Substitutions may be applied by the parser before getting to the formatting marks, in which case the characters adjacent to those marks may not be what you see in the original source.

One such example is enclosing monospaced text inside quotation marks, such as “endpoints”.

You might start with the following syntax:

That only gives you “endpoints”, since the backticks are contributing to the enclosing smart quotes.

Adding another backtick gets closer, but the parser still ignores the constrained formatting marks and interprets the backticks literally:

So you have to double up the marks to coerce it into formatting the text to monospace.

Unconstrained quotes are meant to match anywhere in the text, context free. However, that means you catch them formatting when you don’t intend them to. Admittedly, these symbols are a bit tricky to type literally when the content calls for it. But being able to do so is just a matter of knowing the tricks, which this section will cover.

Let’s assume you are typing the following two lines:

In the first sentence, you aren’t looking for any text formatting, but you’re certainly going to get it. Double underscore is an unconstrained formatting mark. In the second sentence, you might expect CB###2 and CB###3 to be formatted in monospace and highlighted. However, what you get is a scrambled mess. The mix of constrained and unconstrained formatting marks in the line is ambiguous.

There are two (reliable) solutions for escaping unconstrained formatting marks:

The attribute reference is preferred because it’s the easiest to read:

This works because attribute expansion is performed after text formatting (i.e., quotes substitution) under normal substitution order. (Recall that backticks around text format the text in monospace but permit the use of attribute references).

Here’s how you’d write these lines using the inline passthrough to escape the unconstrained formatting marks instead:

Notice the addition of the plus symbols. That’s the closest thing to a text formatting escape. Everything between the plus symbols is escaped from interpolation (attribute references, text formatting, etc). However, the text still receives proper output escaping for HTML (e.g., < becomes <).

The enclosure `+TEXT+` (text enclosed in pluses surrounded by backticks) is a special formatting combination in Asciidoctor. It means to format TEXT as monospace, but don’t interpolate formatting marks or attribute references in TEXT. It’s roughly equivalent to Markdown’s backticks. Since AsciiDoc offers more advanced formatting, the double enclosure is necessary.

The more brute-force solution to the inline passthrough approach is to use the pass:c[] macro, which is a more verbose (and flexible) version of the plus formatting marks.

As you can see, however, the macro is not quite as elegant or concise. In case you’re wondering, the c in the target slot of the pass:[] macro applies output escaping for HTML. Though not always required, it’s best to include this flag so you don’t forget to when it is needed.

Backslashes for escaping aren’t very reliable in AsciiDoc. While they can be used, they have to be placed so strategically that they are rather finicky.

All attributes have a name and a value.

The attribute name:

In other words, the name cannot contain dots or spaces.

Currently, case is ignored when resolving attributes, so URI, Uri and uRI are all the same as uri. (See issue #509 for a proposed change to this restriction). A best practice is to only use lower case for letters in the name and avoid starting the name with a number.

The attribute value:

Certain attributes have a restricted range of allowable values. See the entries in the Catalog of Document Attributes for details.

By default, the attribute assignment precedence, from highest to lowest, is as follows:

Let’s use the doctype attribute to show how precedence works.

The default value for the doctype attribute is article. Therefore, if doctype is not set and assigned a value in the document, API or CLI it will be assigned the article value (i.e. its default value). However, if doctype is set in the document and assigned a new value, such as book, the book value will override the default value. Finally, a value assigned to doctype via the API or CLI, will overrule the value in the document.

You can adjust the precedence of attribute values passed to the API or CLI. By adding an @ symbol to the end of an attribute value passed to the API or CLI, it makes that assignment have a lower precedence than an assignment in the document.

Let’s add that to the precedence list defined earlier.

Before you can use an attribute in your document, it must be set. (Sometimes referred to as “toggling on” the attribute).

Some attributes are automatically set when Asciidoctor processes a document. You can also set (or override) an attribute for a document by declaring an attribute entry. For example:

Many attributes can be assigned a value at the same time:

The value may be empty, a string (of characters) or a number. A string value may include references to other attributes.

Attributes can be unset using the bang symbol (!). The ! can be placed either before or after the attribute’s name.

For example, both:

and

mean unset the sectnums attribute. In this case, it tells Asciidoctor to not number the sections.

An attribute reference is an inline element composed of the name of the attribute enclosed in curly brackets. For example:

The attribute reference is replaced by the attribute’s value when Asciidoctor processes the document. Referencing an attribute that is not set is considered an error and is handled specially by the processor.

The following sections will show you how to use attributes on your whole document, individual blocks, and inline elements.

An attribute entry is the primary mechanism used to define an attribute in a document.

An attribute entry consists of the attribute’s name and its value. The attribute’s name comes first and must be surrounded by colons. The attribute’s value is offset from the name part by at least one space. The value is optional.

Once set, an attribute (and its value) are available for use throughout the remainder of the document. Attribute entries are used to toggle settings on and off or to set configuration variables that control the output generated by the AsciiDoc processor.

Attributes are typically defined in the document header, though they may also be defined in the body of the document. Many of the built-in attributes only take effect when defined in the document header.

For example, to enable the table of contents, you can define (i.e., set) the toc attribute using an attribute entry in the document header as follows:

When the value following an attribute is left empty, as it is in the example above, the default value will be assigned. The default value for toc is auto; therefore, the table of contents will be placed in the default location (below the document’s title) when the document is rendered. If you want the table of contents to be placed on the right side of the document, you must assign the attribute a new value.

The right value will override the default value. The value assigned to an attribute in the document header will replace the intrinsic value (assuming the attribute is not locked).

Attributes are also used to store URLs.

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

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.

Attribute entries have the following characteristics:

An attribute list can apply to blocks, inline quotes text, and macros. The attributes and their values contained in the list will take precedence over attribute entries.

Attribute lists:

Document attributes can be assigned using the following syntax:

For example:

is effectively the same as:

This is important for being able to assign document attributes in places where attribute entry lines are not normally processed, such as in a table cell.

The rules for the inline doctype are as follows:

Given the following input:

Processing it with the options doctype=inline and backend=html5 produces:

The inline doctype allows the Asciidoctor processor to cover the full range of applications, from unstructured (inline) text to full, standalone documents!

The document title resembles a level-0 section title, which is written using a single equal sign followed by at least one space (i.e., = ), then the text of the title. The document title must be the first level-0 section title in the document. The only content permitted above the document title are blank lines, comment lines and document-wide attribute entries.

Here’s an example of a document title followed by a short paragraph. Notice the blank line between the document title and the first line of prose. That blank line is what offsets the document header from the body.

When the doctype is article or manpage, the document can only have one level-0 section title. In contrast, the book document type permits multiple level-0 section titles. When the doctype is book, the first level-0 section title, located in the header, is the document’s title and subsequent level-0 section titles are the part titles.

The author of a document is listed on the line beneath the document’s title. An optional email address or URL can follow an author’s name inside angle brackets.

Let’s add an author with her email address to the document below.

As you can see in the example above, Asciidoctor uses the author’s name and email to assign values to a number of built-in attributes that can be used throughout the document’s body. These attributes include:

If one or more of the author’s names consists of more than one word, use an underscore (_) between the words you want to adjoin. For example, the author of the following document has a compound last name.

Alternatively, the author and email attributes can be set explicitly in the header.

The html5 and docbook converters can render documents with multiple authors. Multiple authors and their emails are separated by semicolons (;) when they’re listed on the same line.

A document’s revision information contains three optional attributes.

The revision information is listed on the third line of the header, beneath the author information line.

When rendered, the revnumber in the byline is preceded by the word Version; however, when referenced in the body of the document, only the numerical value is displayed. The version-label attribute controls the version number label in the byline. The revision information attributes can also be explicitly set in the header.

In the rendered document, notice that the V preceding the revnumber is capitalized in the byline but not when the attribute is referenced in the body of the document.

By default, the document title is separated into a main title and subtitle using the industry standard, a colon followed by a space.

The separator is searched from the end of the text. Therefore, only the last occurrence of the separator is used for partitioning the title.

You can modify the title separator by specifying the separator block attribute explicitly above the document title (since Asciidoctor 1.5.3). Note that a space will automatically be appended to the separator value.

You can also set the separator using a document attribute, either in the document:

or from the API or CLI (shown here):

You can partition the title from the API when calling the doctitle method on Document:

You can partition the title in an arbitrary way by passing the separator as a value to the partition option. In this case, the partition option both activates subtitle partitioning and passes in a custom separator.

Document metadata, such as a description of the document, keywords, and an alternate title, can be assigned to attributes in the header. When rendered to HTML, the values of these attributes will correspond to tags contained in the <head> section of an HTML document.

When the document is rendered as HTML 5 (using the built-in html5 backend), each section title becomes a heading element where the heading level matches the number of equal signs. For example, a level 1 section (==) maps to an <h2> element.

Section IDs are generated from the section title. By default, the ID is prefixed with an underscore (_) and each word in the title is separated by an underscore. You can change the prefix using the idprefix attribute.

If you want to remove the prefix, assign it to an empty value:

You can change the word separator by using the idseparator attribute.

To disable the auto-generation of section IDs, unset the sectids attribute:

You can also assign a custom ID and reference text label to a section (see Defining an Anchor). This can be useful when you define a cross reference pointing to the section.

To turn section titles into links, enable the sectlinks attribute. The default Asciidoctor stylesheet displays linked section titles with the same color and styles as unlinked section titles.

When the sectanchors attribute is enabled on a document, an anchor (empty link) is added before the section title. The default Asciidoctor stylesheet renders the anchor as a section entity (§) that floats to the left of the section title.

Asciidoctor allows section numbering to be toggled on and off throughout a document. You can enable section numbers using the sectnums attribute.

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:

For regions of the document where section numbering is turned off, the section numbering will not be incremented.

Given:

The sections will be numbered as follows:

Asciidoctor will always curtail incrementing the section number in regions of the document where section numbers are off.

If sectnums is set on the command line (or API), that overrides the value set in the document header, but it does not prevent the document from toggling the value for regions of the document.

If sectnums! is set on the command line (or API), then the numbers are disabled regardless of the setting within the document.

The discrete attribute can be applied to any section titles that start with two to six equal signs (==). A discrete title is styled like a section title but is not part of the content hierarchy (i.e., it ignores section nesting rules). Nor will it be included in the ToC.

Asciidoctor provides styles for the frontmatter and backmatter sections commonly found in journal articles, academic papers, and books. The styles are:

These styles are available to the article and book document types, with the exception of the part introduction style which is exclusive to books.

In general, the section style attribute is set above a level 1 section title or block of text. For instance, the example below shows how to label a section as an abstract.

The structure and usage rules for each section style is explained in Structuring, Navigating, and Referencing Your Content.

You can assign a title to any paragraph, list, delimited block, or block macro. 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.

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

In addition to a title, a block can be assigned additional metadata including:

Here’s an example of a quote block with metadata:

Some metadata is used as supplementary content, such as the title, whereas other metadata controls how the block is rendered, such as the block name.

The AsciiDoc syntax provides a set of components for including non-paragraph text, such as block quotes, source code listings, sidebars and tables, in your document. These components are referred to as delimited blocks because they are surrounded by delimiter lines (e.g., ****).

Here’s an example of a sidebar block:

Within the boundaries of a delimited block, you can enter any content or blank lines. The block doesn’t end until the ending delimiter is found. The delimiters around the block determine the type of block, how the content is processed and rendered and what elements are used to wrap the content in the output.

The following table identifies the built-in block names and delimited blocks syntax, their purposes, and the substitutions performed on their contents.

This table shows the substitutions performed by each substitution group referenced in the previous table.

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.

Apply the lead style to any paragraph, and it will render using a larger font size. The lead style is assigned to the role attribute. You can set role using the long- or shorthand method.

When you render a document using the default backend and stylesheet, the first paragraph of the preamble is automatically styled as a lead paragraph.

The two most common ways of emphasizing a word is to format it as bold or italic. To render a word or phrase with bold styling, place an asterisk (*) at the beginning and end of the text you wish to format. To bold a letter or letters in a string of text, place two asterisks (**) before and after the letter or letters.

Letters and words are italicized using one (_) or two (__) underscores. When you want to bold and italicize a letter or word, the bold markup must be the outermost markup.

Single and double quotation marks are not rendered as curved quotation marks (also known as smart, curly, typographic or book quotation marks). When entered using the ' and " key, Asciidoctor outputs straight (dumb, vertical, typewriter) quotation marks. However, by creating a set of backticks (`) contained within a set of single quotes (') or double quotes ("), you can tell Asciidoctor where to output curved quotation marks.

When entered with the ' key, Asciidoctor renders an apostrophe that is directly preceded and followed by a character, such as in contractions and possessive singular forms, as a curved apostrophe. This inconsistent handling of apostrophes and quotation marks is a hold over from the original AsciiDoc processor. An apostrophe directly bounded by two characters is processed during the replacements substitution phase, not the quotes phase. This is why an apostrophe directly followed by white space, such as the possessive plural form, is not curved by default.

To render an apostrophe as curved when it is not bound by two characters, mark it as you would a single curved quote.

In the rendered output, note that the plural possessive apostrophe, seen trailing werewolves, is curved, as is the omission apostrophe before 60s.

If you don’t want an apostrophe that is bound by two characters to be rendered as curved, escape it by preceding it with a backslash (\). The preventing substitutions and passthrough sections detail additional ways to prevent punctuation substitutions.

Subscript and superscript text is common in mathematical expressions and chemical formulas. When rendered, the size of subscripted and superscripted text is reduced. Subscripted text is placed at the baseline and superscripted text above the baseline. The size and precise placement of the text depends on the font and other stylesheet parameters applied to the rendered document.

Text is subscripted when you enclose it in a set of tildes (~) and superscripted with a set of carets (^)

Monospace text formatting is often used to emulate how source code appears in computer terminals, simple text editors, and integrated development environments (IDEs). In Asciidoctor 1.5, inline content is rendered using a fixed-width font, i.e. monospaced font, when it is enclosed in a single set of backticks (`). A character bounded by other characters must be enclosed in a double set of backticks (``).

Monospaced text can be bold and italicized, as long as the markup sets are entered in the right order. The monospace markup must be the outermost set, then the bold set, and the italic markup must always be the innermost set.

When text is enclosed in a set of single or double hash symbols (#), and no style is assigned to it, the text will be rendered as highlighted (<marked>).

Additionally, text marked with hash symbols can be assigned built-in styles, such as big and green.

You can format text with custom styles that you define as well.

When rendered to HTML, the word asciidoctor is wrapped in <span> tags and the role userinput is used as the element’s CSS class.

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.

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:

Asciidoctor offers numerous bullet styles for lists. The list marker (bullet) is set using the list’s block style.

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

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

Here’s an unordered list that has square bullets:

List items can be marked complete using checklists.

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

When checklists are rendered to HTML, the checkbox markup is transformed into an HTML checkbox with the appropriate checked state. The data-item-complete attribute on the checkbox is set to 1 if the item is checked, 0 if not. The checkbox is used in place of the item’s bullet.

Since HTML generated by Asciidoctor is usually static, the checkbox is set as disabled to make it appear as a simple mark. If you want to make the checkbox interactive (i.e., clickable), add the interactive option to the checklist (shown here using the shorthand syntax for Options):

As a bonus, if you enable font-based icons, the checkbox markup (in non-interactive lists) is transformed into a font-based icon!

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:

You can mix and match the three list types, ordered, unordered, and labeled, within a single hybrid list. 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 labeled list section demonstrates how to combine all three list types.

For ordered lists, Asciidoctor supports the numeration styles such as lowergreek and decimal-leading-zero.

The full list of numeration styles that can be applied to an ordered list are as follows:

* These styles are only supported by the HTML converters.

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

* Default numeration if block style is not specified

When the role shorthand (.custom) is used on an ordered list, the numeration style is no longer omitted.

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:

The number of columns in a table is determined by the number of cells found in the first non-blank line after the table delimiter (|===) or by the values assigned to the cols attribute.

For example, the syntax in the two examples below will both render a table with two columns.

When a single number is assigned to the cols attribute, its value indicates the number of columns. Each column will be the same width. However, the number of columns can also be assigned as a comma delimited list. The number of entries in the list determines the number of columns.

The comma delimited list below creates a table with four columns of equal width.

This syntax provides that same result:

Now, let’s talk about that asterisk in the syntax above.

The AsciiDoc syntax provides a variety of ways to control the size, style and layout of content within columns. These specifiers can be applied to whole columns.

To apply a specifier to a column, you must set the cols attribute and assign it a value. A column specifier can contain any of the following components:

Each component is optional.

The multiplier operator (*) is used when you want a specifier to apply to more than one consecutive column. If used, the multiplier must always be placed at the beginning of the specifier.

For example:

The alignment component allows you to horizontally or vertically align a column’s content. Content can be horizontally aligned left (<), center (^), or right (>).

To horizontally center the content in all of the columns, add the ^ operator after the multiplier.

What if you only want to center the content in the last column? Assign the default styles to the preceding columns, and ^ to the last column in a comma separated list.

Let’s specify a different horizontal alignment for each column.

You’ll notice that the content in the examples above is only centered on the horizontal. It can also be aligned vertically when the alignment operator is prefixed with a dot (.). Content can be vertically aligned to the top (<), middle (^), or bottom (>) of a cell.

To vertically align the content to the middle of the cells in all of the columns, add a . and then the ^ operator after the multiplier.

If you only want to align the content to the bottom of each cell in the last column, you’d assign the default styles to the preceding columns, and > to the last column in a comma separated list.

Let’s specify a different vertical alignment for each column.

Finally, we’ll also horizontally center the content in the last column.

When both a horizontal and vertical alignment is assigned to a column, the horizontal alignment operator must precede the vertical operator.

The width component sets the width of a column. Its value can be a proportional integer (the default is 1) or a percentage (1 to 99).

When assigning percentage values to the cols attribute, you do not need to include the percent sign (%).

Let’s create a table with custom widths and alignments.

The style component must always be located at the end of the specifier. When no style name is provided column contents will be processed as regular inline text.

The column styles are described in the table below.

Let’s apply the header style to the first column, the monospaced style to the second, the strong style to the third, and the emphasis style to the fourth.

Specifiers can also be applied to individual cells.

In addition to sharing many of the column specifier capabilities, cell specifiers allow cells to span rows and columns. Like a column specifier, a cell specifier is made up of components. These components, listed and defined below, are all optional.

A cell specifier is prefixed directly to the cell delimiter (|) preceding the content you want to customize.

The span component can duplicate a cell or have it span multiple rows or columns.

To duplicate a cell in multiple, consecutive columns, prefix the | with the multiplication factor and the * operator.

To have a cell span multiple, consecutive columns, prefix the | with the span factor and the + operator.

If you want to have a cell span multiple, consecutive rows, prefix the span factor with a dot (.).

The alignment component for cells works the same as the column specifier alignment component.

The style component can also be applied to individual cells. For example, you can apply the AsciiDoc element styles to an individual cell by prefixing the vertical bar with an a.

Source code listing can be placed inside cells by using the listing syntax.

For the grand finale, let’s apply a variety of specifiers to individual cells.

The first row of a table is promoted to a header row if the header option is set (either explicitly or implicitly).

You can enable the header option by adding the header keyword to the comma-separated list of values in the options attribute on the table. You can also enable the header option by adding the %header directive to the table style (the first positional attribute).

In the example below, the table has an attribute list containing an options attribute that includes the header option.

Alternately, you can define the header row based on how you layout the table. Asciidoctor use the following conventions to determine when the first row should become the header row:

As seen in the result of the example below, if all of these rules hold, then the first row of the table is treated as a header.

If you want to suppress this implicit behavior of promoting the first row to a header row, set the option value noheader (or add the %noheader directive to the table style).

Notice that when the implicit method of assigning the header row is used, it’s not necessary to set the cols attribute. That’s because the number of columns are determined by the number of cells in the first line if the cols attribute is absent.

The last row of a table can be styled as a footer by adding the footer keyword to the options attribute.

By default, a table will span the width of the content area. To constrain the width of the table to a fixed value, set the width attribute in the table’s attribute list. The width is an integer percentage value ranging from 1 to 100. The % sign is optional.

Alternately, you can make the width fit the content by setting the autowidth option. The columns inherit this setting, so individual columns will also be sized according to the content.

If you want each column to have an automatic width, but want the table to span the width of the content area, add the spread role to the table (or, as of 1.5.5, set the width attribute to 100%).

The borders on a table are controlled using the frame and grid attributes. You can combine these two attributes to achieve a variety of border styles for your tables.

If you specify a title on a table, the title will be used as part of the table’s caption. Adding a title also designates the table as a formal table.

By default, the title of a formal table is prefixed with the label Table <n>. followed by a space, where <n> is the 1-based index of all formal tables in the document.

You can customize the caption label by specifying the caption attribute. If you want a space between the label and the title, you must add a trailing space to the value of the caption attribute. (Don’t let the name of the attribute mislead you. The caption attribute only sets the caption’s label, not the whole caption line).

If you want to exclude the caption label altogether, simply assign a blank value to the caption attribute.

Alternatively, you can disable the caption label for tables globally by undefining the table-caption document attribute.

Tables can be created from data stored as Comma Separated Values (CSV) and Delimiter Separated Values (DSV). To use one of these dataset types, set the value of the format attribute on the table to csv or dsv, respectively. The main difference between tables with one of these formats and psv tables is how the data inside the table delimiters is arranged.

When the format attribute is set to csv, the data separator is a comma (,), as seen in the table below.

When the format attribute is set to dsv, the data separator is a colon (:).

Asciidoctor also provides shorthand notation for setting CSV and DSV table formats. The first position of the table block delimiter (i.e., |===) can be replaced by the data delimiter to set the table format (e.g., ,===).

To set the format of the table to CSV using shorthand notation, simply replace the leading pipe (|) in the table delimiter with a command (,), as shown here:

In the same way, the DSV format can be specified by replacing the leading pipe (|) with a colon (:).

DSV and CSV datasets don’t support formatting of individual cells. However, you can apply formatting, such as the AsciiDoc style, to a column of cells using a table-wide column spec:

Keep in mind that endlines are not preserved in CSV and DSV data. That does somewhat limit the type of content you can put in these cells, particularly when using the AsciiDoc cell style.

DSV and CSV datasets can be, and often are, inserted into a table using the include directive.