Before You Upgrade

This page if for users upgrading from a previous version of Asciidoctor to the latest stable version of Asciidoctor. If your migrating from AsciiDoc Python, see the documentation for migrating from AsciiDoc Python to Asciidoctor.

When you upgrade Asciidoctor you may also need to update some of the syntax and attributes in your AsciiDoc documents. Major version releases can include new AsciiDoc syntax capabilities as well as syntax changes that make it more consistent.

Updated and deprecated features

The syntax, attributes, and commands listed below have been updated or deprecated. In most cases, they’ve been replaced with a new feature that provides improved functionality.

Inline formatting

Feature Deprecated New As of Version 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., “)


Curved ‘single quotes’

`single quotes'

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


Table of contents

Feature Deprecated New As of Version Notes

Scrollable, left margin TOC


:toc: left


TOC location

toc-placement and toc-position

:toc: <value>


User-specified TOC location

:toc-placement: manual

:toc: macro


Document header

Feature Deprecated New As of Version 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. However, 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.


Feature Deprecated New As of Version Notes

render class method

.render(input, options = {}) ⇒ Object

.convert(input, options = {}) ⇒ Object


New features

Visit What’s New for a complete list of new Asciidoctor and AsciiDoc features.

Proposed changes for future versions

Feature Deprecated New As of Version Notes

Delimited open block

open block content

New syntax will allow for nested delimited open blocks


Set backend

Set the backend from a document

Backends can only be set in the CLI, environment, and API


Link attributes

Set linkattrs to use link attribute syntax

linkattrs is set implicitly so link attributes are available automatically


UI macros

Set experimental to use the UI macros

UI macros are available automatically


Document roles

Roles are inherited; roles don’t wrap the document

Roles aren’t inherited; roles wrap the document



Upgrade on Linux

Upgrade Asciidoctor using the package manager on many Linux distributions including Fedora, RHEL, Debian, Ubuntu, and Alpine Linux.

Upgrade on macOS

Upgrade Asciidoctor using Homebrew on macOS.

Upgrade using gem update

Upgrade Asciidoctor using the gem update command.