Migrate from AsciiDoc.py to Asciidoctor

In order to take advantage of the new features and syntax in Asciidoctor, you’ll need to migrate legacy AsciiDoc documents written for AsciiDoc Python (AsciiDoc.py) to the AsciiDoc syntax supported by Asciidoctor.

This documentation specifically covers migration from AsciiDoc.py 8 to the latest stable version of Asciidoctor.

Processor call

The Asciidoctor processor is a drop-in replacement for AsciiDoc.py. For most documents, you can simply replace the call to AsciiDoc.py (asciidoc) with the equivalent call to Asciidoctor (asciidoctor).

$ asciidoctor document.adoc

You can also run Asciidoctor on the JVM using AsciidoctorJ or with JavaScript using Asciidoctor.js.

Default HTML backend

AsciiDoc.py used XHTML 1.1 as its default output. Asciidoctor’s default output is HTML 5 (the html5 converter).

Themes

AsciiDoc.py provided a theming mechanism that encapsulated CSS, JavaScript, and images. The --theme option activated one of these themes, which was resolved from your home directory. In Asciidoctor, you control the theme using CSS stylesheets, which you specify using -a stylesheet=<stylesheet>.

If you require more advanced theming, you can inject additional resources using a docinfo file or a postprocessor extension.

Default HTML stylesheet

The AsciiDoc.py and Asciidoctor stylesheets look quite different, but they are compatible (for the most part) since the formatting is based on the same HTML structure and CSS classes. If you prefer the AsciiDoc.py stylesheet, you can use it by copying it from the AsciiDoc.py stylesheets directory and instructing Asciidoctor to apply it using:

$ asciidoctor -a stylesheet=asciidoc.css document.adoc

Keep in mind that the default stylesheet in Asciidoctor is just that, a default. If you don’t like its appearance, you can customize it.

Unlike AsciiDoc.py, Asciidoctor loads some resources from a CDN. It’s possible to configure Asciidoctor to load all resources from local files. For instance, you can unset the webfonts attribute so that the generated HTML does not use fonts from Google Fonts. There are similar attributes to control how additional resources are resolved.

Updated and deprecated AsciiDoc syntax

If a feature or attribute isn’t mentioned in the following tables, than it works in Asciidoctor just like it worked in AsciiDoc.py.

Inline formatting

Feature AsciiDoc.py Asciidoctor Notes

italic text

'italic text'

_italic text_

Allowed with compat-mode

monospace text

+monospace text+

`monospace text`

Allowed with compat-mode

literal monospace text

`literal monospace text`

`+literal monospace text+`

Allowed with compat-mode

Curved “double quotes”

``double quotes''

"`double quotes`", editor keybinding, or the Unicode character in numeric character reference form (e.g., &#8220;)

Curved ‘single quotes’

`single quotes'

'`single quotes`', editor keybinding, or the Unicode character in numeric character reference form (e.g., &#8217;)

Sizes, lines, and colors

big, small, underline, overline, line-through, colors

user-specified [.<role-name>] and associated formatting in stylesheet

See custom text styles

Table of contents

Feature AsciiDoc.py Asciidoctor Notes

Scrollable, left margin ToC

toc2

:toc: left

ToC location

toc-placement and toc-position

:toc: <value>

User-specified ToC location

:toc-placement: manual

:toc: macro

Document header

Feature AsciiDoc.py Asciidoctor Notes

Implicit document title attribute

First content line at document top is set as title

= Title

Allowed with compat-mode

Two-line style document title

= Title
=====

= Title

Asciidoctor accepts the two-line heading style to set the document title. But by using it, you implicitly set compat-mode. If you want to use the new Asciidoctor syntax, make sure to use = Title or explicitly unset the compat-mode attribute.

Sections
Feature AsciiDoc.py Asciidoctor Notes

Underlined titles

Underline length must match title length +/- 2 characters.

== Level 1 section title
=== Level 2 section title
==== Level 3 section title
===== Level 4 section title

See section levels and titles

Section numbers

numbered

sectnums

Tables

Feature AsciiDoc.py Asciidoctor Notes

AsciiDoc table cell

a| or asciidoc|

a| only

Table cell separator

A Python regular expression.

One or more literal characters or \t for tab.

Horizontal and vertical alignment for tables cells

halign, valign

Column and cell specifiers

See align column content or cell content.

Make tables full page width in DocBook

options="pgwide"

not implemented

Blocks

Feature AsciiDoc.py Asciidoctor Notes

Block delimiters

Delimiter lines do not have to match in length.

The length of start and end delimiter lines must match exactly.

General
Feature AsciiDoc.py Asciidoctor Notes

ifeval::[ ]

Evaluates any Python expression.

Evaluates simple logical expressions testing the value of attributes.

See ifeval directive

Provide name of current document

infile

not implemented

Provide directory of current document

indir

not implemented

Substitute (+)

replacements2

Renamed to post_replacements

See post replacement substitutions

Suppress inline substitutions and retain block indents when importing large blocks of plain text

plaintext

not implemented

Closest Asciidoctor equivalent is a passthrough block or a listing block with an indent attribute.

Turn single line comments into DocBook <remark> elements

showcomments

not implemented

If you want to send remarks to the output, use an extension, or:

 ifdef::showcomments+basebackend-docbook[]
 ++++
 <remark>Your comment here</remark>
 ++++
 endif::[]

Apply special formatting to named text.

specialwords

not implemented

Replace tabs with spaces in all text, using a default tab size of 8

tabsize (in-document and include directive)

in-document only

Asciidoctor only replaces tabs with spaces in verbatim content blocks (listing, literal, etc.), and the attribute has no default. In other words, tabs are not expanded in verbatim content blocks unless this attribute is set on the block or the document. For all other text, Asciidoctor tabs are fixed at 4 spaces by the CSS. See normalize block indentation for more detail.

Mathematical expressions

AsciiDoc.py and Asciidoctor can convert embedded LaTeX and AsciiMath expressions (e.g., asciimath:[expression], latexmath:[expression], etc.). In Asciidoctor, you’ll need to activate STEM support first using the stem attribute.

Configuration files

Asciidoctor does not use .conf files or filters, so --conf-file, --dump-conf, and --filter are not applicable. Instead, Asciidoctor provides an extension API that replaces the configuration-based extension and filter mechanisms in AsciiDoc.py.

Internationalization

AsciiDoc.py had built-in .conf files that translated built-in labels. In Asciidoctor, you must define the translations for these labels explicitly. See language support for details.

AsciiDoc.py extensions

The extension mechanism is completely different in Asciidoctor, but the most of the standard extensions have been re-implemented, so they should work with minor changes.

AsciiDoc.py Asciidoctor

source

  • You can choose from a number of syntax highlighters.

  • Highlighters are built-in, not separately installed.

  • src_numbered, src_tab, args are not implemented directly, but check the highlighter you are using for what features it has and how to configure them.

music

Not implemented.

[latex] block macro

Use a stem block.

graphviz

Use Asciidoctor Diagram.

Custom extensions

AsciiDoc.py custom extensions are Python commands, so they don’t work with Asciidoctor. Depending on the Asciidoctor processor you choose, you can re-write your extensions in Ruby, Java, or JavaScript.

Doctest

AsciiDoc.py --doctest ran its unit tests. See the test suite for how to run the Asciidoctor unit tests. Asciidoctor also has a doctest tool which you can use when creating custom HTML or XML-based converters.

Help

AsciiDoc.py had --help syntax to show a syntax cheatsheet, and --help manpage to show the command usage as a Linux manpage. Asciidoctor only has --help, which shows the command usage.

If you installed Asciidoctor using a Linux package, you can view the manpage using:

$ man asciidoctor

If you installed Asciidoctor using RubyGems, you have to tell the man command where to find the manpage using:

$ man "`gem which asciidoctor | xargs dirname`/../man/asciidoctor.1"

You can also view the manpage online.