Upgrade from Asciidoctor 1.5.x to 2.0

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

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

Table of contents

Feature Deprecated New 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 header

Feature Deprecated New Notes

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.

API

Feature Deprecated New

Render class method

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

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

New features

Visit What’s New in 2.0 for a complete list of new Asciidoctor features.