Migrate from AsciiDoc.py

AsciiDoc.py (aka AsciiDoc Python) is the original AsciiDoc processor, which has now been superseded by Asciidoctor. If you’re currently using AsciiDoc.py to convert your AsciiDoc documents and are ready to switch to Asciidoctor, you’ll need to migrate your legacy AsciiDoc content to the official AsciiDoc syntax defined and supported by Asciidoctor. In doing so, you’ll also benefit from the enhancements that have been added to the AsciiDoc language since Asciidoctor took over development of the language. This page covers those differences and how to migrate.

This documentation specifically covers migration from AsciiDoc.py 8.6.

Processor call

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

$ asciidoctor document.adoc

If you’re document makes heavy use of the legacy AsciiDoc syntax supported by AsciiDoc.py, you may have better luck enabling compat mode:

$ asciidoctor -a compat-mode document.adoc

However, compat mode is strictly a migration aid. You should only use it as an interim measure while your migrating your content. It’s not something you want to rely on long term and is considered deprecated.

Default HTML backend

AsciiDoc.py used XHTML 1.1 as its default output. Asciidoctor’s default output is HTML 5 (i.e., backend=html5) and the html backend maps to html5.

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 Asciidoctor and AsciiDoc.py stylesheets look quite different, but they’re mostly interchangable since the underlying HTML structure of the two processors is nearly identical.

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

Asciidoctor has improved the AsciiDoc syntax to make it more consistent and, in some cases, more concise. This section outlines those improvements and how they different from the legacy AsciiDoc supported by AsciiDoc.py.

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. See Italic.

monospace text

+monospace text+

`monospace text`

Allowed with compat-mode. See Monospace.

literal monospace text

`literal monospace text`

`+literal monospace text+`

Allowed with compat-mode. See Literal monospace.

Curved “double quotes”

``double quotes''

"`double quotes`", editor keybinding, or Unicode character in numeric character reference form

See Quotation Marks and Apostrophes.

Curved ‘single quotes’

`single quotes'

'`single quotes`', editor keybinding, or Unicode character in numeric character reference form

See Quotation Marks and Apostrophes.

Sizes and overline

big, small, overline

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

See Using Custom Inline Styles.

Underline and line-through

underline, line-through

[.underline], [.line-through]

See Using Custom Inline Styles.

Colors

Name of color

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

See Using Custom Inline Styles.

Table of contents

Feature AsciiDoc.py Asciidoctor Notes

Scrollable, left margin TOC

toc2

:toc: left

See Position the TOC.

TOC location

toc-placement and toc-position

:toc: <value>

See Position the TOC.

User-specified TOC location

:toc-placement: manual

:toc: macro

See Position the TOC.

Document and section titles

Feature AsciiDoc.py Asciidoctor Notes

Implicit document title attribute

First content line at document top is set as title

= Title

Allowed with compat-mode. See Document Title.

Two-line style (setext) document title

Title
=====

= Title

Asciidoctor accepts the two-line heading style to set the document title. But, by using it, compat-mode is implicitly set. To use the new syntax, use = Title or explicitly unset compat-mode. See Document Title.

Underlined section titles

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

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

See Section Titles and Levels.

Section numbers

numbered

sectnums

See Section Numbers.

Tables

Feature AsciiDoc.py Asciidoctor Notes

Table cell

a| or asciidoc|

a| only

See Add Cells and Rows to a Table.

Table cell separator

A Python regular expression.

One or more literal characters or \t for tab.

See Add Cells and Rows to a Table, Table Data Formats, and custom separators.

Horizontal and vertical alignment for tables cells

halign, valign

Column and cell specifiers

See Align Content by Column and Align Content by Cell.

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.

See Delimited blocks.

Substitutions

Feature AsciiDoc.py Asciidoctor Notes

Substitute +

replacements2

post_replacements

See Post Replacement Substitutions.

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

plaintext

not implemented

Close equivalent is a passthrough block or a listing block with the indent attribute.

Mathematical expressions

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

Miscellaneous

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

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 blocks, 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.

showcomments

In AsciiDoc.py, single line comments could be turned into DocBook <remark> elements using showcomments. This feature isn’t implemented in Asciidoctor, but you can send remarks to the output, using an extension, or ifdef directives and passthrough blocks like the example shown below.

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

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.

Localization

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

AsciiDoc.py extensions

The extension mechanism is completely different in Asciidoctor, but 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 source highlighters.

  • Source highlighter values are built-in.

  • 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 topics

In both AsciiDoc.py and Asciidoctor, the --help CLI option shows the command usage by default. It can also show a syntax crib sheet using --help syntax or the man page using --help manpage.

In AsciiDoc.py, the --help manpage option emits a plaintext version of the man page. Asciidoctor, on the other hand, outputs the formatted man page so you can use it with a man pager. 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 with Asciidoctor, you can route the output through the col command as follows:

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

Alternately, you can view the manpage for Asciidoctor online at asciidoctor(1).