Differences between Asciidoctor and AsciiDoc

> Asciidoctor > Asciidoctor Documentation >

Asciidoctor aims to be compliant with the AsciiDoc syntax, but there are some differences to keep in mind. Many of these differences exist so that Asciidoctor can:

  • enforce rules we believe are too lax or ambiguous in AsciiDoc

  • process documents faster and smarter

Additionally, Asciidoctor offers new syntax, attributes, and features to help you write, style, and publish your documents.

The known cases where Asciidoctor differs from AsciiDoc are categorized and listed in the sections below.

Syntax

  • Asciidoctor does not support the deprecated index term syntax (++ and +++)

  • In the Header, Asciidoctor does not wrap the email next to the author name in angle brackets

  • Asciidoctor allows the email field to be a URL and renders it as such

  • Asciidoctor properly calculates author initials if attribute reference is used in name

  • Asciidoctor allows the author and revision attributes to be referenced in subsequent attribute entries in header (unlike AsciiDoc)

  • Asciidoctor allows multiple authors to be defined, separated by semicolon. In DocBook backend, the authors are listed in an <authorgroup> element.

  • Asciidoctor allows the document id to be set using above the document header (adds id attribute to <body> tag)

Attributes and Macros

  • Asciidoctor is much more lenient about attribute list parsing (double quotes are rarely needed, though you may want to keep them for compatibility)

  • Asciidoctor adds the type attribute on ordered lists to provide hint for numbering style when stylesheet is absent (such as in embedded mode)

  • Asciidoctor recognizes opts as an alias for the options attribute

  • Asciidoctor introduces the hardbreaks attribute, which inserts a line break character after each line of wrapped text

  • Asciidoctor will parse attributes in link macros if the linkattrs attribute is set on the document

  • The ifeval::[] macro is constrained for the strict purpose of comparing values of attributes

  • Assigning value to the listing-caption attribute will enable automatic captions for listings (like examples, tables and figures)

Table of Contents (ToC)

  • Asciidoctor reifies the ToC in the header of the document instead of relying on JavaScript to create it

  • Asciidoctor sets CSS class on ToC element, read from the toc-class attribute; defaults to ToC attribute name (toc or toc2).

  • Asciidoctor honors the id, title, role and levels attributes set on the toc macro.

  • Asciidoctor does not output two ToCs with the same id.

Sections

  • Section title underlines must be within 1 character of the length of the title (AsciiDoc allows an offset of 3)

  • Asciidoctor introduces the idseparator attribute to customize the separator used in generated section ids (AsciiDoc hardcodes _)

  • Asciidoctor supports up to 6 section levels (to cover all heading levels in HTML) whereas AsciiDoc stops at 5; note the 6 section level is only available using the single-line section title syntax

Blocks

  • Asciidoctor enforces symmetric block delimiters (the length of start and end delimiters for a block must match!)

  • Asciidoctor can handle blocks which span multiple include files unlike AsciiDoc Python

  • Asciidoctor does not require commas between attributes with quoted values in a block attribute list

  • Asciidoctor is nice about using a section title syntax inside a delimited block by simply ignoring it (AsciiDoc issues warnings)

  • The Admonition block caption can be overridden in Asciidoctor using the caption block attribute

  • Asciidoctor honors the alternate style name "discrete" for a floating title (i.e., [discrete])

  • Asciidoctor supports the pass style on open blocks and paragraphs

Source code highlighting

  • Asciidoctor supports syntax highlighting of listing, literal or open blocks that have the "source" style and a language specified out of the box

    • Asciidoctor honors the source-highlighter values coderay (CodeRay), pygments (Pygments via pygments.rb), highlight.js and prettify

    • Asciidoctor gracefully falls back to a listing block if no source language is specified

Lists

  • Asciidoctor removes indentation for non-literal paragraphs in a list item

    In general, Asciidoctor handles whitespace much more intelligently

  • Asciidoctor does not output an empty <dd> for labeled list items that don’t have a definition

Horizontal rule

  • In Asciidoctor, a horizontal ruler can have attributes

Tables

  • Asciidoctor skips over line comments in tables, whereas AsciiDoc doesn’t

  • Asciidoctor uses its own API rather than a commandline invocation to handle table cells that have AsciiDoc content

  • Asciidoctor supports resolving variables from parent document in table cells with AsciiDoc content

  • AsciiDoc doesn’t carry over the doctype attribute passed from the commandline when rendering AsciiDoc table cells, whereas Asciidoctor does

  • Asciidoctor only recognizes the single character notation for column and cell formatting (e.g., a but not asciidoc)

  • Asciidoctor does not support deprecated tables (you don’t want them anyway)

Images

  • Asciidoctor strips the file extension from the target image when generating alt text if no alt text is provided

Icons

  • Asciidoctor can set the extension for icons using the icontype attribute (AsciiDoc defaults to .png)

Markdown-style syntax

  • Asciidoctor supports markdown-style blockquotes as well as a shorthand for a blockquote paragraph.

  • Asciidoctor supports markdown-style headings (section titles)

Outputs and Stylesheets

HTML backend and output

  • Asciidoctor’s default backend is the HTML 5 backend; it matches AsciiDoc’s HTML 5 backend (AsciiDoc’s default HTML backend is XHTML 1.1)

  • Asciidoctor adds the viewport meta tag to <head> to optimize mobile viewing

  • Asciidoctor handles inline anchors cleanly

    • AsciiDoc adds an <a> tag in the line and that markup gets caught in the generated id

    • Asciidoctor promotes the id of the anchor as the section id

  • Asciidoctor strips XML entities from the section title before generating the id (makes for cleaner section ids)

  • Asciidoctor uses <code> instead of <span class="monospace"> around inline literal text in the HTML backend

  • Asciidoctor creates xref labels using the text from the linked section title when rendering HTML to match how DocBook works

  • Asciidoctor allows commas to be used in xref labels, whereas AsciiDoc cuts off the label at the location of the first comma

  • Asciidoctor uses the <blockquote> for the content and <cite> tag for attribution title in the HTML output for quote blocks, requiring some additional styling to match AsciiDoc

    blockquote.content { padding: 0; margin; 0 }
cite { color: navy; }

  • Admonition block style is added to class of outer div in Asciidoctor’s html5 backend

  • Asciidoctor wraps <col> elements in <colgroup> in tables

  • Asciidoctor uses <code> around content in monospaced table cells

Stylesheets

  • Asciidoctor includes a modern default stylesheet based on Foundation.

  • Asciidoctor links to, rather than embeds, the default stylesheet into the document by default (e.g., linkcss). To include the default stylesheet, you can either use the copycss attribute to tell Asciidoctor to copy it to the output directory, or you can embed it into the document using the linkcss! attribute. You can also provide your own stylesheet using the stylesheet attribute.

Processor

  • Asciidoctor sets these additional built-in attributes

    asciidoctor

    indicates Asciidoctor is being used; useful for conditional processing

    asciidoctor-version

    indicates which version of Asciidoctor is in use

  • Asciidoctor does not support system evaluation macros

  • Asciidoctor does not support displaying comments in rendered documents

SafeMode

  • Asciidoctor enables safe mode by default when using the API (SafeMode::SECURE)

  • Asciidoctor safe mode is even more safe than AsciiDoc’s safe mode

  • The include::[] macro is converted to a link to the target document when SafeMode is SECURE or greater (this makes for a friendly experience on GitHub)

Next steps and help

If there’s a difference you don’t see in this list, check the issue tracker to see if it’s an outstanding feature, or file an issue to report the difference.

Now that you’ve reviewed how AsciiDoc and Asciidoctor differ, you may want to learn more about the AsciiDoc syntax and the growing variety of integrations, backends, and customizations the Asciidoctor project is developing.

First, learn how to install the Asciidoctor toolchain.

Need an overview of the AsciiDoc syntax?

Want to dive deep into the details of the syntax?

Are you ready to convert your AsciiDoc document into HTML, DocBook or PDF?

Interested in building a theme from the Asciidoctor Stylesheet Factory or applying a custom stylesheet?

Additional guides are listed on the Documentation page. Also, don’t forget to join the Asciidoctor mailing list, where you can ask questions and leave comments.