90. Migrating from AsciiDoc Python

The purpose of this section is to help you migrate legacy AsciiDoc documents written for AsciiDoc Python to the modern AsciiDoc syntax supported by Asciidoctor and to learn about equivalent tools and extensions.

The differences are minor, so most documents will need very few changes, if any. Once you’ve made the necessary changes, this section also describes how to take advantage of the new features provided in Asciidoctor.

This section specifically covers migration from AsciiDoc Python 8 to Asciidoctor 1.5.x. The content assumes you’ve already updated any content that is deprecated as of AsciiDoc Python 8.

90.1. Command Line Interface

Asciidoctor was designed from the outset to be a (much faster) drop-in replacement for AsciiDoc Python. For most documents, you can simply replace the call to AsciiDoc Python:

$ asciidoc document.adoc

with an equivalent call to Asciidoctor:

$ asciidoctor -a compat-mode document.adoc

If you run into trouble, check out the differences below, namely Deleted and Deprecated Syntax and Attributes.

Keep in mind you can also run Asciidoctor on the JVM using AsciidoctorJ or with JavaScript using Asciidoctor.js.

90.1.1. Help Topics

In both AsciiDoc Python and Asciidoctor, the --help CLI option shows the command usage by default. They differ in how they handle the optional topic argument.

In AsciiDoc Python, the --help syntax topic shows a syntax cheatsheet and the --help manpage topic shows a plaintext version of the man page.

Asciidoctor only supports the manpage help topic. However, it outputs the formatted man page rather than the plaintext version. Therefore, to view it, you need to pipe the result to the man command as follows:

$ asciidoctor --help manpage | man /dev/stdin

or

$ asciidoctor --help manpage | man -l -

If you want to view the plaintext version, you can route the output through the col command as follows:

$ asciidoctor --help manpage | man -l - | col -bx

You can also view the man page for Asciidoctor online at asciidoctor(1).

To get help with the AsciiDoc syntax in Asciidoctor, refer to the AsciiDoc Syntax Quick Reference.

90.1.2. Configuration Files

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

90.1.3. Internationalization

AsciiDoc Python has built-in .conf files that are used to translate built-in labels. You load the .conf file for a given language by setting the lang attribute to a supported language code (e.g., -a lang=<language code>). In Asciidoctor, you must define the translations for these labels explicitly. See Using Asciidoctor with Other Languages for details.

90.1.4. Themes

AsciiDoc Python provides a theming mechanism that encapsulates CSS, JavaScript and images. The --theme option activates one of these themes, which is resolved from your home directory. In Asciidoctor, you control the theme using CSS (i.e., a stylesheet) only, which you can specify using -a stylesheet=<stylesheet>.

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

90.1.5. Default HTML Backend

AsciiDoc Python uses XHTML 1.1 as its default output (the xhtml11 backend), though it supports HTML5 output as well (the html5 backend). Asciidoctor defaults to creating HTML5 output (the html5 backend), which closely adheres to the backend by the same name in AsciiDoc Python. The web has moved forward since AsciiDoc Python was created, so the switch to HTML5 is recommended anyway.

90.1.6. Doctest

AsciiDoc Python --doctest runs units tests. See Tests 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.

90.2. Changed Syntax

These changes are not backward-compatible, but if you set the compat-mode attribute, Asciidoctor will accept the AsciiDoc Python syntax. For the long term, you should update to the Asciidoctor syntax. Consult the Migration Guide to get the full details and learn how to migrate smoothly.

AsciiDoc syntax affected by compat mode
Feature AsciiDoc Python (or Asciidoctor in compat mode) Asciidoctor (no compat mode)

italic text

'italic text' or _italic text_

_italic text_

monospaced text

+monospaced text+

`monospaced text`

monospaced text (literal)

`{asciidoc-version}`

`+{asciidoc-version}+`

``double quotes''

``double quotes''
not available in compat mode

"`double quotes`" or insert the Unicode quote characters using your editor

`single quotes'

`single quotes'
not available in compat mode

'`single quotes`' or insert the Unicode quote characters using your editor

Document title [1]

Title or = Title
=====

= Title

[1] Asciidoctor accepts the two-line heading style to set the document title. However, by using it, you implicitly set compat-mode. If you want to use the new Asciidoctor syntax, make sure to use the single-line style for the document title or unset the compat-mode attribute explicitly.

The following changes are not affected by the compat-mode attribute:

AsciiDoc syntax not affected by compat mode
Feature AsciiDoc Python Asciidoctor

Underlined titles

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

Underline length must match title length +/- 1 character (Underlined titles are deprecated anyway. See Sections.)

ifeval::[]

Evaluates any Python expression.

Evaluates simple logical expressions testing the value of attributes. See ifeval directive.

Block delimiters

Delimiter lines do not have to match in length.

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

AsciiDoc table cell

a| or asciidoc|

a| only

Table cell separator

A Python regular expression.

One or more literal characters or \t for tab.

90.3. Deleted and Deprecated Syntax and Attributes

These are attributes that either no longer exist, work differently, or have better alternatives.

Deleted and deprecated syntax and attributes
AsciiDoc Python Asciidoctor Notes

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

deprecated

Character attributes to apply formatting directly. Usually better to apply a role, then apply the formatting based on that role by using a stylesheet.

halign, valign for table cells

Column and cell specifiers

See Cell Formatting.

infile

not implemented

Provides the name and directory of the current document. (Distinct from docfile, because infile may be an included document, and docfile is always the master document.) No Asciidoctor equivalent.

indir

asciidoc

asciidoctor

AsciiDoc Python sets asciidoc to show that it is the current processor. Asciidoctor sets asciidoctor instead.

toc2

toc

Combined in a single attribute, see Table of Contents.

toc-placement

toc-position

options="pgwide"

not implemented

DocBook attribute to make tables full page width, whatever the current indent. No Asciidoctor equivalent.

options="unbreakable"

In Asciidoctor, this only works for tables, not paragraphs.

plaintext

not implemented

AsciiDoc Python uses this to suppress inline substitutions and retain block indents when importing large blocks of plain text. Asciidoctor deliberately does not implement it; the closest Asciidoctor equivalent is a passthrough block.

replacements2

post_replacements

Renamed.

presubs

-

Not required.

showcomments

not implemented

In AsciiDoc Python, turns single line comments into DocBook <remark> elements. Asciidoctor considers this an inappropriate use of comments. If you want to send remarks to the output, use an extension, or:

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

specialwords

not implemented

In AsciiDoc Python, applies special formatting to named text. In Asciidoctor this could be implemented using an extension.

tabsize (in-document and include directive)

in-document only

AsciiDoc Python replaces tabs with spaces in all text, using a default tab size of 8. 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.

90.4. Default HTML Stylesheet

You’ll notice that the AsciiDoc Python and Asciidoctor stylesheets look quite different. However, they are compatible (for the most part) since the formatting is based on the same HTML structure and CSS classes. If you happen to prefer the AsciiDoc Python stylesheet, you can use it by copying it from the AsciiDoc Python 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 either customize it or choose another stylesheet. You can find a collection of alternative themes in the Asciidoctor Stylesheet Factory.
Unlike AsciiDoc Python, 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.

90.5. Mathematical Expressions

Both AsciiDoc Python and Asciidoctor can convert embedded LaTeX and AsciiMath expressions (e.g., asciimath:[expression], latexmath:[expression], etc), but with Asciidoctor you need to activate STEM support first using the stem attribute (see Activating stem support).

For block content, AsciiDoc Python uses a [latex] style delimited block. In Asciidoctor, use a stem passthrough block instead. See Block Stem Content.

90.6. AsciiDoc Python Extensions

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

Standard extensions
AsciiDoc Python Asciidoctor

source

  • You can choose from a number of highlighters Syntax Highlighting Source Code.

  • 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 passthrough block Block Stem Content.

graphviz

Incorporated into Asciidoctor Diagram.

90.7. Custom Extensions

AsciiDoc Python custom extensions will not work with Asciidoctor because AsciiDoc Python extensions are essentially Python commands, and the Asciidoctor extensions are Ruby (or Java) classes. To re-write your extensions, see Extensions.

90.8. Features Introduced by Asciidoctor

90.8.1. New Syntax

Asciidoctor has shorthand for id, role, style and options. See Setting Attributes on an Element for details.

The following longhand syntax in AsciiDoc Python:

[[id]]
[style,role="role",options="option1,option2"]

can be written using the shorthand supported by Asciidoctor:

[style#id.role%option1%option2]

The longhand forms still work, but you should use the new forms for future compatibility, convenience and readability.

90.8.2. Enhancements

There are lots of new features and improvements Asciidoctor. These are some of the more interesting ones when migrating:

A detailed list of the improvements is shown in Differences between Asciidoctor and AsciiDoc Python.

See the AsciiDoc Style Guide and Recommended Practices for ways to make your documents clearer and more consistent.