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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
= What's New in Asciidoctor PDF
:navtitle: What's New
//{page-component-version}
:doctype: book
//:page-toclevels: 0
:leveloffset: 1
:url-milestone-2-0-0: {url-project-issues}?q=is%3Aissue+milestone%3Av2.0.0+is%3Aclosed
= Asciidoctor PDF {page-component-version}
_**Release date:** 2022.05.04 | *Issue label:* {url-milestone-2-0-0}[{page-component-display-version}^]_
[#roles]
== Paragraph roles and text indent
In Asciidoctor PDF 2.0, you can define custom roles in your theme and apply them to specific paragraphs in your document.
See xref:theme:custom-role.adoc[] to learn how to create a custom role and xref:roles.adoc#custom[Use a custom role] for how to assign a custom role to a paragraph.
In light of roles now being supported on paragraphs, the `lead` category in the theme has been dropped and replaced by a built-in role named `lead`.
See xref:theme:role.adoc#built-in[Built-in roles] for details.
To control the indent of inner paragraphs (instead of all paragraphs), you can set the new `prose-text-indent-inner` key in your theme.
See xref:theme:prose.adoc[] for details.
[#breakable]
== Breakable by default
In Asciidoctor PDF 2.0, the following blocks are breakable by default, which includes automatic anchor and caption orphan prevention:
* Admonitions
* Block images
* Code blocks (literal, listing, and source)
* Examples
* Open blocks
* Quote blocks
* Sidebars
* Verses
Tables and sections are breakable by default, but do not provide automatic anchor and caption orphan prevention.
For tables, that means the anchor and caption can be left on the current page if the table is advanced to the next page.
For sections, that means the section's title may be left on the current page if the first content block doesn't fit.
However, you can turn on orphan prevention for tables and sections by adding the (seemingly redundant) xref:breakable-and-unbreakable.adoc#breakable[breakable option] as a hint.
[#unbreakable]
== Unbreakable option
The `unbreakable` option can be applied to all delimited blocks (including admonitions and tables), but not sections.
When the xref:breakable-and-unbreakable.adoc#unbreakable[unbreakable option] is applied to a block, the converter will advance the block and its caption and anchor to the next page if it detects that the block would break across pages and it can fit on a single page.
== Notitle option
The `untitled` option has been renamed to `notitle`.
With the name change, it's also gained new capabilities.
The `notitle` option hides a section title in the body of a document, but displays the title in the TOC and allows the anchor resulting from that title to still be referencable.
It can also be used to add an entry to the TOC for a preamble, anonymous preface, and imported PDF pages.
See xref:notitle.adoc[] for examples and more details.
== Blocks and block captions
Blocks and block captions gained a lot of new features in Asciidoctor PDF 2.0.
Here are just a few of the highlights:
Smart bottom margins::
Blocks now have smarter bottom margins that prevent extra space from being added below them, particularly when blocks are nested or used inside an AsciiDoc table cell.
Border width::
The border width of delimited blocks, admonitions, and block images can be customized per edge with the xref:theme:blocks.adoc#border-width[border-width key].
Border style::
The border style of delimited blocks, admonitions, and block images can be changed with the xref:theme:blocks.adoc#border-style[border-style key].
Border styles include dashed, dotted, double, and solid.
Line height::
Wherever font properties are accepted in the theme, you can now control the line height of blocks using the `line-height` key.
Anchor positioning::
The anchor location for blocks can be positioned relative to the content using the `block-anchor-top` theme key.
Caption text alignment::
The text alignment of captions can now be controlled independent of the block alignment using the global xref:theme:caption.adoc[caption-text-align theme key] or per block category with `<category>-caption-text-align`.
The xref:theme:text.adoc#caption-text-align[image-caption-text-align] and xref:theme:tables.adoc#caption-text-align[table-caption-text-align] theme keys accept the value `inherit` in addition to the standard text alignment values.
The value `inherit` resolves to the alignment of the block image or table.
Global caption text decoration::
The text decoration style, color, and width can be applied to captions globally with the `caption-text-decoration-style`, `caption-text-decoration-color`, and `caption-text-decoration-width` theme keys.
See xref:theme:caption.adoc[] for more information.
Caption background color::
You can now specify a background color for captions globally using the `caption-background-color` theme key or per block category (`<category>-caption-background-color`).
See xref:theme:caption.adoc[] for more information.
Caption max-width::
A caption's `max-width` value can be set to a percentage of the content by passing the percentage as an argument to `fit-content` function.
First line of abstract::
The theme can control the font color of first line of abstract using `abstract-first-line-font-color` key.
.*Notable fixes for blocks*
* Syntax highlighting isn't applied to a source block if the `specialchars` substitution is disabled.
* Borders, shading, and padding aren't applied to collapsible blocks.
* The `callouts` substitution can be removed on code blocks.
== Tables
Border widths and styles::
The table border width can be customized per edge with the xref:theme:blocks.adoc#border-width[border-width key].
The border style can be xref:theme:tables.adoc#border-style[specified per edge by assigning an array of styles] to the `border-style` key.
Border styles include dashed, dotted, and solid.
Grid widths and styles::
The width of table grid lines can be specified for rows and columns with the xref:theme:tables.adoc#grid-width[grid-width key].
The style of the grid lines can be specified for rows and columns with the xref:theme:tables.adoc#grid-style[grid-style key].
Grid styles include dashed, dotted, and solid.
//allow horizontal and vertical lines of table grid to be styled independently (#1875) (*@hextremist*)
Maximum caption width::
The maximum caption width for tables can be set to a percentage of the content by passing an argument to the `fit-content` function.
Caption end:: The `table-caption-side` theme key has been xref:theme:tables.adoc#end[renamed to table-caption-end].
.*Notable fixes for tables*
* An error message is logged if a table cell is truncated.
* Instead of raising an error, the converter logs an error and skips the table if the content cannot fit within the designated width of a cell.
* The content of an AsciiDoc table cell is prevented from overrunning the footer or subsequent pages.
* The top and bottom padding is taken into account when computing the height of AsciiDoc table cell.
* Vertical center alignment is correctly applied to regular table cells.
* The border bottom is correctly applied to a table row when frame and grid are none.
== Callout lists and numbers
The theming language now has a xref:theme:callout.adoc[callout-list category].
The new theme keys let you customize the font properties, text alignment, and item spacing of callout lists.
The `callout-list` category includes the `margin-top-after-code` key that can control the top margin of callout lists that immediately follow a code block.
.*Notable fixes for callouts*
* Callout numbers in a callout list stay with primary text when an item is advanced to the next page.
* A sequence of two or more callouts separated by spaces in a code block are processed correctly.
* The font family assigned to `conums` in the theme is applied to the callout numbers displayed in code blocks.
== Images
Caption end:: You can now configure whether the caption for a block image is placed above or below the image using the `caption-end` theme key.
See xref:theme:block-image.adoc#caption[Block Image Category Keys] for the list of available `image-caption` theme keys and their value types.
== Running content and page numbering
xref:theme:add-running-content.adoc#start-at[Select the page where running content starts]:: Specify the page on which the running content starts being displayed by assigning an integer to the `start-at` theme key on the `running-content` category.
Running content can also start after the TOC, wherever the TOC is placed, by assigning the keyword `after-toc` to the `start-at` key.
xref:theme:page-numbers.adoc#start-at[Configure where integer page numbering starts]:: Specify the page on which the integer (1-based) page numbering begins using the `start-at` key on the `page-numbering` category.
Integer page numbering can start at the front cover by assigning the keyword `cover` to the `start-at` key.
Or, you can have the page numbering start after the TOC, wherever the TOC is placed, by assigning `after-toc` to the `start-at` key.
Alternatively, the theme can specify an offset from the first body page where the page numbering should begin when an integer is assigned to `start-at`.
== Fonts
normal_italic:: The xref:theme:text.adoc#font-style[new normal_italic value] for the `font-style` key resets the font style to normal, then applies the italic variant of a font family.
== Deprecated
The following features are deprecated with the release of Asciidoctor PDF 2.0.0 and will be removed in the next major release.
* The `blockquote` category prefix is deprecated in the theme; use the `quote` prefix instead.
See xref:theme:quote.adoc[].
* The `key` category prefix is deprecated in the theme; use the `kbd` prefix instead.
See xref:theme:keyboard.adoc[].
* The `literal` category prefix is deprecated in the theme; use the `codespan` prefix instead.
See xref:theme:codespan.adoc[].
* The `outline-list` category prefix is deprecated in the theme; use the `list` prefix instead.
See xref:theme:list.adoc[].
* The `Optimizer#generate_file` method is deprecated; use `Optimizer#optimize_file` instead.
== Removed
The following dependencies and deprecated features have been removed with the release of Asciidoctor PDF 2.0.0.
* Support for Ruby < 2.7 and JRuby < 9.2 has been removed.
* The `untitled` option has been removed; use the `notitle` option instead.
* Support for the deprecated `pdf-style` and `pdf-stylesdir` attributes has been removed.
* The deprecated Pdf module alias in the API has been removed in favor of PDF.
* The deprecated "`ascii`" fonts have been removed; only the more complete "subset" fonts are now bundled with the gem.
* The previously undocumented `vertical-spacing` key has been removed from the built-in themes.
* The `top-margin` key on block and prose categories in theme has been removed; space between delimited blocks and lists is now controlled using bottom margins only.
* The `lead` category keys in theme have been replaced with the built-in role named `lead`.
* `safe_yaml gem` has been removed; `YAML.safe_load` from the Ruby stdlib is used instead.
* Support for the `<color>` tag in passthrough content has been removed; use `<font color="...">` instead (may affect themes).
* The [.path]_asciidoctor-pdf/converter_ and [.path]_asciidoctor-pdf/version_ shim scripts have been removed; use [.path]_asciidoctor/pdf/converter_ and [.path]_asciidoctor/pdf/version_ instead.
* The unneeded `_mb` functions (e.g., `uppercase_mb`) have been removed; multibyte support for `upcase`, `downcase`, and `capitalize` is now provided by corelib.
|
