1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
= Upgrade from Asciidoctor 1.5.x to 2.0
IMPORTANT: 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 xref:asciidoc-py.adoc[].
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
[cols="~,~,~,~"]
|===
|Feature |Deprecated |New |Notes
|_italic text_
|pass:['italic text']
|pass:[_italic text_]
|Allowed with `compat-mode`.
See xref:asciidoc:text:italic.adoc[].
|`monospace text`
|pass:[+monospace text+]
|pass:[`monospace text`]
|Allowed with `compat-mode`.
See xref:asciidoc:text:monospace.adoc[].
|`+literal monospace text+`
|pass:[`literal monospace text`]
|pass:[`+literal monospace text+`]
|Allowed with `compat-mode`.
See xref:asciidoc:text:monospace.adoc#literal-monospace[Literal monospace].
|Curved "`double quotes`"
|pass:[``double quotes'']
|pass:["`double quotes`"], editor keybinding, or Unicode character in numeric character reference form
|See xref:asciidoc:text:quotation-marks-and-apostrophes.adoc[].
|Curved '`single quotes`'
|pass:[`single quotes']
|pass:['`single quotes`'], editor keybinding, or Unicode character in numeric character reference form
|See xref:asciidoc:text:quotation-marks-and-apostrophes.adoc[].
|===
=== Table of contents
[cols="~,~,~,~"]
|===
|Feature |Deprecated |New |Notes
|Scrollable, left margin TOC
|`toc2`
|`+:toc: left+`
|See xref:asciidoc:toc:position.adoc[].
|TOC location
|`toc-placement` and `toc-position`
|`+:toc: <value>+`
|See xref:asciidoc:toc:position.adoc[].
|User-specified TOC location
|`+:toc-placement: manual+`
|`+:toc: macro+`
|See xref:asciidoc:toc:position.adoc[].
|===
=== Document header
[cols="~,~,~,~"]
|===
|Feature |Deprecated |New |Notes
|Two-line style (setext) document title
|`Title` +
`+=====+`
|`={nbsp}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 xref:asciidoc:document:title.adoc[].
|===
=== API
[cols="~,~,~"]
|===
|Feature |Deprecated |New
|Render class method
|`+.render(input, options = {}) ⇒ Object+`
|`+.convert(input, options = {}) ⇒ Object+`
|===
== New features
Visit xref:ROOT:whats-new.adoc[] for a complete list of new Asciidoctor features.
////
== Proposed changes for future versions
[cols="15,20,20,5,20"]
|===
|Feature |Deprecated |New |As of Version |Notes
|Delimited open block
|pass:[--] +
open block content +
pass:[--]
|New syntax will allow for nested delimited open blocks
|2.0
|
|Set backend
|Set the backend from a document
|Backends can only be set in the CLI, environment, and API
|2.0
|
|Link attributes
|Set `linkattrs` to use link attribute syntax
|`linkattrs` is set implicitly so link attributes are available automatically
|2.0
|
|UI macros
|Set `experimental` to use the UI macros
|UI macros are available automatically
|2.0
|
|Document roles
|Roles are inherited; roles don't wrap the document
|Roles aren't inherited; roles wrap the document
|2.0
|
|===
////
////
== Compatibility mode
When it isn't feasibly to update your documents prior to upgrading Asciidoctor, you can run Asciidoctor in compatibility mode.
Compatibility mode is activated by setting the `compat-mode` attribute and allows Asciidoctor to accept and apply the deprecated syntax and/or behavior.
However, *not all deprecated syntax or behavior is available under the compatibility mode*.
////
|
