rearchitect modules and filenames and drop asciidoctor folder under docs

15 files changed, 1485 insertions, 0 deletions

diff --git a/docs/modules/ROOT/nav-converters.adoc b/docs/modules/ROOT/nav-converters.adoc
new file mode 100644
index 00000000..6bc03330
--- /dev/null
+++ b/docs/modules/ROOT/nav-converters.adoc
@@ -0,0 +1 @@
+* xref:converters.adoc[]
diff --git a/docs/modules/ROOT/nav-docinfo.adoc b/docs/modules/ROOT/nav-docinfo.adoc
new file mode 100644
index 00000000..dd0e50db
--- /dev/null
+++ b/docs/modules/ROOT/nav-docinfo.adoc
@@ -0,0 +1,3 @@
+* xref:docinfo.adoc[]
+//** Adding Header Content
+//** Adding Footer Content
diff --git a/docs/modules/ROOT/nav-errors.adoc b/docs/modules/ROOT/nav-errors.adoc
new file mode 100644
index 00000000..5c15a194
--- /dev/null
+++ b/docs/modules/ROOT/nav-errors.adoc
@@ -0,0 +1 @@
+* xref:errors-and-warnings.adoc[]
diff --git a/docs/modules/ROOT/nav-lang.adoc b/docs/modules/ROOT/nav-lang.adoc
new file mode 100644
index 00000000..278dbd67
--- /dev/null
+++ b/docs/modules/ROOT/nav-lang.adoc
@@ -0,0 +1 @@
+* xref:language-support.adoc[]
diff --git a/docs/modules/ROOT/nav-safe-modes.adoc b/docs/modules/ROOT/nav-safe-modes.adoc
new file mode 100644
index 00000000..be07ed4d
--- /dev/null
+++ b/docs/modules/ROOT/nav-safe-modes.adoc
@@ -0,0 +1,2 @@
+* xref:safe-modes.adoc[]
+** xref:attributes-and-safe-modes.adoc[]
diff --git a/docs/modules/ROOT/nav-top.adoc b/docs/modules/ROOT/nav-top.adoc
new file mode 100644
index 00000000..98431ff5
--- /dev/null
+++ b/docs/modules/ROOT/nav-top.adoc
@@ -0,0 +1,2 @@
+* xref:features.adoc[]
+* xref:whats-new.adoc[]
diff --git a/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc b/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
new file mode 100644
index 00000000..4d28d210
--- /dev/null
+++ b/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
@@ -0,0 +1,46 @@
+= Manage Attributes By Safe Mode
+// anchor: set-safe-attrs
+
+Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and scripts while a document is processing.
+Each level includes the restrictions enabled in the prior security level.
+
+Asciidoctor provides access to the xref:safe-modes.adoc[current safe mode] through built-in attributes.
+You can use these attributes to enable or disable content based on the current safe mode of the processor.
+
+The safe mode can be referenced by one of the following attributes:
+
+* The value of the `safe-mode-name` attribute (e.g., unsafe, safe, etc.)
+* The value of the `safe-mode-level` attribute (e.g., 0, 10, etc.)
+* The presence of the `safe-mode-<name>` attribute, where `<name>` is the safe mode name.
+
+The attributes in the next example define replacement text for features that are disabled in high security environments:
+
+[source,asciidoc]
+----
+\ifdef::safe-mode-secure[]
+Link to chapters instead of including them.
+\endif::safe-mode-secure[]
+----
+
+This feature is particularly handy for displaying content on GitHub, where the safe mode is set to its most restrictive setting, secure.
+
+You can set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and the xref:api:set-safe-mode.adoc[API].
+
+////
+Allow the include directive to import a file from a URI.
+
+Example:
+
+ include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[]
+
+To be secure by default, the allow-uri-read attribute must be set in the API or CLI (not document) for this feature to be enabled. It's also completely disabled if the safe mode is SECURE or greater.
+Since this is a potentially dangerous feature, it’s disabled if the safe mode is SECURE or greater. Assuming the safe mode is less than SECURE, you must also set the allow-uri-read attribute to permit Asciidoctor to read content from a URI.
+
+I decided the following defaults for the header_footer option make the most sense:
+
+true if using the cli (use -s to disable, consistent with asciidoc)
+false if using the API, unless converting directly to a file, in which case true is the default
+The basic logic is that if you are writing to a file, you probably want to create a standalone document. If you are converting to a string, then you probably want an embedded document. Of course, you can always set it explicitly, this is just a default setting.
+
+The reason I think the header_footer default is important is because we don't want people switching from Markdown to AsciiDoc and be totally taken by surprise when they start getting a full HTML document. On the other hand, if you are converting to a file (or using the cli), then it makes a lot of sense to write a standalone document. To me, it just feels natural now.
+////
diff --git a/docs/modules/ROOT/pages/converters.adoc b/docs/modules/ROOT/pages/converters.adoc
new file mode 100644
index 00000000..9340f9f0
--- /dev/null
+++ b/docs/modules/ROOT/pages/converters.adoc
@@ -0,0 +1,103 @@
+= Available Converters
+
+Asciidoctor parses AsciiDoc documents and then uses a converter to generate the output format of your choice, such as HTML, DocBook, or PDF.
+
+== What's a converter?
+
+A converter takes AsciiDoc and transforms it into another format.
+Each converter produces a specific output format, such as HTML or DocBook XML.
+
+Asciidoctor provides several built-in converters and the ability to add on other converters.
+In addition to generating traditional articles and books from AsciiDoc documents, you can also use Asciidoctor to create HTML-based slide decks, static websites, and documentation sites.
+When using these add-on converters, you may need to add some additional structure rules to a document.
+However, nothing in this structure restricts you from still being able to publish the content as a normal document, too.
+
+Each converter is mapped to a name that you specify using the `-b` (`--backend`) command line option or `backend` API option.
+
+== Built-in converters
+
+These built-in converters are bundled with Asciidoctor.
+
+HTML::
+The HTML 5 converter (`html` or `html5`) generates HTML 5 styled with CSS3.
+This is the converter Asciidoctor uses by default.
+
+xref:html-backend:index.adoc#xhtml[XHTML]::
+The XHTML variant of the HTML 5 converter.
+To use the XHTML converter, assign `xhtml` or `xhtml5` to the `backend` option.
+
+xref:docbook-backend:index.adoc[DocBook]::
+The DocBook 5.0 converter generates DocBook 5.0 XML.
+To use the DocBook converter, assign `docbook` or `docbook5` to the `backend` option.
+
+xref:manpage-backend:index.adoc[Man page]::
+The man page converter generates manual pages for software used on Unix and Unix-like operating systems.
+To use the man page converter, assign `manpage` to the `backend` option.
+
+== Add-on converters
+
+You can use add-on converters, which plug into Asciidoctor by adding the appropriate library to the runtime path (e.g., `-r asciidoctor-pdf`).
+
+PDF::
+The PDF converter (`pdf`) generates a portable document format.
+Requires the https://rubygems.org/gems/asciidoctor-pdf[asciidoctor-pdf^] gem.
+
+EPUB3::
+The EPUB3 converter (`epub3`) generates a distribution and interchange format standard for digital publications and documents.
+Requires the https://rubygems.org/gems/asciidoctor-epub3[asciidoctor-epub3^] gem.
+
+Reveal.js::
+The Reveal.js converter generates a Reveal.js presentation from an AsciiDoc document.
+Requires https://github.com/asciidoctor/asciidoctor-reveal.js[Asciidoctor Reveal.js^].
+
+Bespoke::
+The Bespoke converter generates a Bespoke presentation from an AsciiDoc document.
+Requires https://github.com/asciidoctor/asciidoctor-bespoke[Asciidoctor Bespoke^].
+
+////
+LaTeX::
+The LaTeX, a document preparation system for high-quality typesetting.
+Requires the https://rubygems.org/gems/asciidoctor-latex[asciidoctor-latex^] gem.
+
+mallard::
+Mallard 1.0 XML.
+Requires the https://github.com/asciidoctor/asciidoctor-mallard[asciidoctor-mallard^] gem (not yet released).
+
+=== Static site generators
+
+* Jekyll
+* Middleman
+* Antora
+////
+
+// TODO describe the role of template converters (e.g., asciidoctor-backends)
+
+////
+Pulled directly from the user manual - need to decide where this information goes and how it should be presented.
+
+== PDFs
+
+Conversion from AsciiDoc to PDF is made possible by a number of tools.
+
+{uri-asciidoctor-pdf}[Asciidoctor PDF]::
+A native PDF converter for Asciidoctor (converts directly from AsciiDoc to PDF using Prawn).
++
+Instructions for installing and using Asciidoctor PDF are documented in the project's {uri-asciidoctor-pdf-readme}[README].
+The tool provides built-in theming via a YAML configuration file, which is documented in the {uri-asciidoctor-pdf-theming-guide}[theming guide].
++
+TIP: Asciidoctor PDF is the preferred tool for converting to PDF and is fully supported by the Asciidoctor community.
+
+a2x::
+A DocBook toolchain frontend provided by that AsciiDoc Python project.
++
+To use this tool, you should first convert to DocBook using Asciidoctor, then convert the DocBook to PDF using a2x.
+a2x accepts a DocBook file as input and can convert it to a PDF using either Apache FOP or dblatex.
+Instructions for using a2x are documented in the project's {uri-a2x-manpage}[man page].
+
+{fopub-ref}[asciidoctor-fopub]::
+A DocBook toolchain frontend similar to a2x, but which only requires Java to be installed on your machine.
++
+Instructions for using asciidoctor-fopub are documented in the project's {fopub-doc-ref}[README].
+To alter the look and feel of the PDF, it's necessary to pass XSL parameters or modify the XSLT.
+More information about customization can be found in http://www.sagehill.net/docbookxsl/[DocBook XSL: The Complete Guide].
+////
diff --git a/docs/modules/ROOT/pages/docinfo.adoc b/docs/modules/ROOT/pages/docinfo.adoc
new file mode 100644
index 00000000..2c2cc28c
--- /dev/null
+++ b/docs/modules/ROOT/pages/docinfo.adoc
@@ -0,0 +1,255 @@
+= Docinfo Files
+:url-docbook-info-ref: https://tdg.docbook.org/tdg/5.0/info.html
+:url-richfaces-docinfo: https://github.com/richfaces/richfaces-docs/blob/master/Developer_Guide/src/main/docbook/en-US/Developer_Guide-docinfo.xml
+// um anchor: docinfo-file
+
+You can add custom content to the head or footer of an output document using docinfo files.
+Docinfo files are useful for injecting auxiliary metadata, stylesheet, and script information into the output not added by the converter.
+
+The docinfo feature does not apply to all backends.
+While it works when converting to output formats such as HTML and DocBook, it does not work when converting to PDF using Asciidoctor PDF.
+
+The docinfo feature must be explicitly enabled using the `docinfo` attribute (see <<enable-docinfo>>).
+Which docinfo files get used depends on the value of the `docinfo` attribute as well as the backend.
+
+[#head]
+== Head docinfo files
+
+The content of head docinfo files gets injected into the top of the document.
+For HTML, the content is append to the `<head>` element.
+For DocBook, the content is appended to the root `<info>` element.
+
+The docinfo file for HTML output may contain valid elements to populate the HTML `<head>` element, including:
+
+* `<base>`
+* `<link>`
+* `<meta>`
+* `<noscript>`
+* `<script>`
+* `<style>`
+
+CAUTION: Use of the `<title>` element is not recommend as it's already emitted by the converter.
+
+You do not need to include the enclosing `<head>` tag as it's assumed to be the envelope.
+
+Here's an example:
+
+.A head docinfo file for HTML output
+[source,html]
+----
+<meta name="keywords" content="open source, documentation">
+<meta name="description" content="The dangerous and thrilling adventures of an open source documentation team.">
+<link rel="stylesheet" href="basejump.css">
+<script src="map.js"></script>
+----
+
+Docinfo files for HTML output must be saved with the `.html` file extension.
+See <<name-docinfo>> for more details.
+
+The docinfo file for DocBook 5.0 output may include any of the {url-docbook-info-ref}[<info> element's children^], such as:
+
+* `<address>`
+* `<copyright>`
+* `<edition>`
+* `<keywordset>`
+* `<publisher>`
+* `<subtitle>`
+* `<revhistory>`
+
+The following example shows some of the content a docinfo file for DocBook might contain.
+
+.A docinfo file for DocBook 5.0 output
+[source,xml]
+----
+<author>
+  <personname>
+    <firstname>Karma</firstname>
+    <surname>Chameleon</surname>
+  </personname>
+  <affiliation>
+    <jobtitle>Word SWAT Team Leader</jobtitle>
+  </affiliation>
+</author>
+
+<keywordset>
+  <keyword>open source</keyword>
+  <keyword>documentation</keyword>
+  <keyword>adventure</keyword>
+</keywordset>
+
+<printhistory>
+  <para>April, 2021. Twenty-sixth printing.</para>
+</printhistory>
+----
+
+Docinfo files for DocBook output must be saved with the `.xml` file extension.
+See <<name-docinfo>> for more details.
+
+To see a real-world example of a docinfo file for DocBook, checkout the {url-richfaces-docinfo}[RichFaces Developer Guide docinfo file^].
+
+[#footer-docinfo]
+== Footer docinfo files
+
+Footer docinfo files are differentiated from head docinfo files by the addition of `-footer` to the file name.
+In the HTML output, the footer content is inserted immediately after the footer div (i.e., `<div id="footer">`).
+In the DocBook output, the footer content is inserted immediately before the ending tag (e.g., `</article>` or `</book>`).
+
+TIP: One possible use of the footer docinfo file is to completely replace the default footer in the standard stylesheet.
+Just set the attribute `nofooter`, then apply a custom footer docinfo file.
+
+// Not here! Good info, but does nothing to clarify the previous paragraphs and could confuse.
+////
+TIP: To change the text in the "Last updated" line in the footer, set the text in the attribute `last-update-label` (for example, `:last-update-label: <your text> Last Updated`). +
+To disable the "Last updated" line in the footer, unassign the attribute `last-update-label` (however, this leaves an empty footer div). +
+To disable the footer completely, set the attribute `nofooter`. Then having a footer docinfo file effectively replaces the default footer with your custom footer.
+////
+
+[#name-docinfo]
+== Naming docinfo files
+
+The file that gets selected to provide the docinfo depends on which converter is in use (html, docbook, etc) and whether the docinfo scope is configured for a specific document ("`private`") or for all documents in the same directory ("`shared`").
+The file extension of the docinfo file must match the file extension of the output file (as specified by the `outfilesuffix` attribute, a value which always begins with a period (`.`)).
+
+.Docinfo file naming
+[cols="<10,<20,<30,<30"]
+|===
+|Mode |Location |Behavior |Docinfo file name
+
+.2+|Private
+|Head
+|Adds content to `<head>`/`<info>` for <docname>.adoc files.
+|`<docname>-docinfo<outfilesuffix>`
+
+|Footer
+|Adds content to end of document for <docname>.adoc files.
+|`<docname>-docinfo-footer<outfilesuffix>`
+
+.2+|Shared
+|Head
+|Adds content to `<head>`/`<info>` for any document in same directory.
+|`docinfo<outfilesuffix>`
+
+|Footer
+|Adds content to end of document for any document in same directory.
+|`docinfo-footer<outfilesuffix>`
+|===
+
+[#enable-docinfo]
+== Enabling docinfo
+
+To specify which file(s) you want to apply, set the `docinfo` attribute to any combination of these values:
+
+* `private-head`
+* `private-footer`
+* `private` (alias for `private-head,private-footer`)
+* `shared-head`
+* `shared-footer`
+* `shared` (alias for `shared-head,shared-footer`)
+
+Setting `docinfo` with no value is equivalent to setting the value to `private`.
+
+For example:
+
+[source,asciidoc]
+----
+:docinfo: shared,private-footer
+----
+
+This docinfo configuration will apply the shared docinfo head and footer files, if they exist, as well as the private footer file, if it exists.
+
+// NOTE migrate this NOTE to the migration guide once 1.6 is released
+[NOTE]
+====
+
+`docinfo` attribute values were introduced in Asciidoctor 1.5.5 to replace the less descriptive `docinfo1` and `docinfo2` attributes.
+Here are the equivalents of the old attributes using the new values:
+
+* `:docinfo:` = `:docinfo: private`
+* `:docinfo1:` = `:docinfo: shared`
+* `:docinfo2:` = `:docinfo: shared,private`
+====
+
+Let's apply this to an example:
+
+You have two AsciiDoc documents, [.path]_adventure.adoc_ and [.path]_insurance.adoc_, saved in the same folder.
+You want to add the same content to the head of both documents when they're converted to HTML.
+
+. Create a docinfo file containing `<head>` elements.
+. Save it as docinfo.html.
+. Set the `docinfo` attribute in [.path]_adventure.adoc_ and [.path]_insurance.adoc_ to `shared`.
+
+You also want to include some additional content, but only to the head of [.path]_adventure.adoc_.
+
+. Create *another* docinfo file containing `<head>` elements.
+. Save it as [.path]_adventure-docinfo.html_.
+. Set the `docinfo` attribute in [.path]_adventure.adoc_ to `shared,private-head`
+
+If other AsciiDoc files are added to the same folder, and `docinfo` is set to `shared` in those files, only the [.path]_docinfo.html_ file will be added when converting those files.
+
+== Locating docinfo files
+
+By default, docinfo files are searched for in the same folder as the document file.
+If you want to keep them anywhere else, set the `docinfodir` attribute to their location:
+
+[source,asciidoc]
+----
+:docinfodir: common/meta
+----
+
+Note that if you use this attribute, only the specified folder will be searched; docinfo files in the document folder will no longer be found.
+
+== Attribute substitution in docinfo files
+
+Docinfo files may include attribute references.
+Which substitutions get applied is controlled by the `docinfosubs` attribute, which takes a comma-separated list of substitution names.
+The value of this attribute defaults to `attributes`.
+
+For example, if you created the following docinfo file:
+
+.Docinfo file containing a revnumber attribute reference
+[source,xml]
+----
+<edition>{revnumber}</edition>
+----
+
+And this source document:
+
+.Source document including a revision number
+[source,asciidoc]
+----
+= Document Title
+Author Name
+v1.0, 2020-12-30
+:doctype: book
+:backend: docbook
+:docinfo:
+----
+
+Then the converted DocBook output would be:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<book xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" lang="en">
+  <info>
+    <title>Document Title</title>
+    <date>2020-12-30</date>
+    <author>
+      <personname>
+        <firstname>Author</firstname>
+        <surname>Name</surname>
+      </personname>
+    </author>
+    <authorinitials>AN</authorinitials>
+    <revhistory>
+      <revision>
+        <revnumber>1.0</revnumber> <!--.-->
+        <date>2020-12-30</date>
+        <authorinitials>AN</authorinitials>
+      </revision>
+    </revhistory>
+  </info>
+</book>
+----
+<.> The revnumber attribute reference was replaced by the source document's revision number in the converted output.
diff --git a/docs/modules/ROOT/pages/errors-and-warnings.adoc b/docs/modules/ROOT/pages/errors-and-warnings.adoc
new file mode 100644
index 00000000..9b3c2dee
--- /dev/null
+++ b/docs/modules/ROOT/pages/errors-and-warnings.adoc
@@ -0,0 +1,262 @@
+= Errors and Warnings
+
+////
+um anchor: appendix#app-messages
+
+Only includes the CLI. asciidoctorj and the asciidoctor API are not included.
+When there are enough documented, maybe add another table for them. Although these users are programmers-wouldn't they just run it in the debugger?
+
+Testing was carried out with
+Asciidoctor 1.5.5 [https://asciidoctor.org]
+Runtime Environment (ruby 2.3.1p112 (2016-04-26) [i386-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
+////
+
+All warning, error, and failure messages emitted by the Asciidoctor CLI are written to the console via stderr (i.e., standard error).
+Most messages also apply to the API, but they're written directly to stderr.
+
+== Notification types
+
+<<warning,WARNING>>::
+Warnings do not stop conversion, but they indicate possible problems, and the output may not be what you were expecting.
+
+<<error,ERROR>>::
+Errors do not stop conversion, but the output document will almost certainly be wrong.
+
+<<fail,FAILED>>::
+Failures are fatal; no output document will be produced.
+
+The messages listed in the following sections may contain some of the following representative placeholders:
+
+<docname>::
+Represents the basename of the source file being processed (e.g., `sample.adoc`).
+
+<file>::
+Represents a path to the input file or other referenced file.
+
+<uri>::
+Represents a URI being referenced.
+
+<x> or <y>::
+Placeholders for other contextual information in the message.
+
+[#warning]
+== Warning messages
+
+[options="header,breakable",cols="<60,<50,<30"]
+|===
+|Message |Troubleshooting |Also see
+
+|abstract block cannot be used in a document without a title when doctype is book. Excluding block content.
+|Invalid book document structure.
+|#user-abstract#
+
+|cannot retrieve contents of <x> at URI: <uri> (allow-uri-read attribute not enabled)
+|Reading from a URI is only allowed in certain safe modes and the allow-uri-read attribute must be passed to the application.
+|#include-uri#
+
+|could not retrieve contents of <x> at URI: <uri>
+|Web address not found.
+|
+
+|could not retrieve image data from URI: <uri>
+|Web address not found. Only occurs with `allow-uri-read` and `data-uri`. Check the URI.
+|#include-images-by-full-url#
+
+|dropping line containing reference to missing attribute: <x>
+|An attribute cannot be resolved and the `attribute-missing` attribute is set to `drop-line`.
+|#catch-a-missing-or-undefined-attribute#
+
+|file does not exist or cannot be read: <file>
+|You specified a stylesheet (`-a stylesheet=<file>`) but <file> does not exist or is not readable.
+|
+
+|gem 'thread_safe' is not installed. This gem is recommended when registering custom converters.
+|You have registered a custom converter, and you have not installed the thread_safe gem.
+|
+
+|gem 'thread_safe' is not installed. This gem is recommended when using custom backend templates.
+|You are using custom templates (`-T <template_dir>`), but you have not installed the thread_safe gem.
+|
+
+|image to embed not found or not readable: <file>
+|You used `:data-uri:` but the file could not be found.
+|#managing-images#
+
+|include file not readable: <file>
+|You do not have permission to access the file.
+|#include-nonasciidoc#
+
+|input path <file> is a <x>, not a file
+|The path is not a file (perhaps it is a socket or a block device).
+|#include-nonasciidoc#
+
+|optional gem 'asciimath' is not installed. Functionality disabled.
+|asciimath is one of the libraries used for equations.
+|#stem#
+
+|optional gem 'coderay' is not installed. Functionality disabled.
+|CodeRay is used for source code highlighting.
+|#coderay#
+
+|skipping reference to missing attribute: <x>
+|An attribute cannot be resolved and the `attribute-missing` attribute is set to `skip`.
+|#catch-a-missing-or-undefined-attribute#
+
+|tables must have at least one body row
+|
+|#tables#
+
+|tag '<x>' not found in include file: <file>
+|You tried to include by tagged region, but the included document does not have that tag.
+|#include-partial#
+
+|<docname>: id assigned to <type> already in use: <id>
+|<id> is a duplicate ID, meaning it has already been assigned to a node of <type> (e.g., section, block, anchor).
+If you don't see the problem in <docname>, check that the duplicate ID isn't coming from a file which is being included.
+|
+
+|<docname> callout list item index: expected <x> got <y>
+|Callouts are expected to be in numerical order, just like any ordered list.
+|#callouts#
+
+|<docname> include <x> not readable: <y>
+|If <y> is a file, do you have read permissions for it?
+If it is a URI and `-a allow-uri-read` is set, does it exist?
+|
+
+|<docname> include file not found: <file>
+|Probably a typo or missing file. If not, make sure you understand the search process.
+|#include-directive#, #include-resolution#
+
+|<docname> invalid empty <x> detected in style attribute
+|The first positional attribute in the block attributes could not be parsed.
+|#options#
+
+|<docname> invalid style for <x> block: <y>
+|You have added a custom style to a block, but you haven't registered a custom block extension to handle it.
+|
+
+|<docname> invalid style for paragraph: <x>
+|You have a line `[<name-of-style>]` before a paragraph, but `name-of-style` isn't a recognized built-in style.
+|#style#
+
+|<docname> list item index: expected <x>, got <y>
+|You gave explicit numbers on an ordered list, but they were not sequential. Asciidoctor renumbers them for you, and gives this warning.
+|#ordered-lists#
+
+|<docname> multiple ids detected in style attribute
+|Multiple IDs cannot be specified in the block style (e.g., `[#cat#dog]`).
+// But [#wibble,id="wobble"] does not generate an error
+|#id#
+
+|<docname> no callouts refer to list item <x>
+|The callout is missing or not recognized.
+In source listings, is the callout the last thing on the line?
+|#callouts#
+
+|<docname> section title out of sequence
+|Invalid document structure. Check section levels.
+|#sections#
+|===
+
+[#error]
+== Error messages
+
+[options="header,breakable",cols="<60,<50,<30"]
+|===
+|Message |Troubleshooting |Also see
+
+|input file <file> missing or cannot be read
+|Check that the file exists and that the filename is not misspelled.
+|#using-the-command-line-interface#
+
+|include file has illegal reference to ancestor of jail, auto-recovering
+|The safe mode is restricting access to an include file outside of the base directory.
+|#running-asciidoctor-securely#
+
+|input file and output file cannot be the same: <file>
+|Choose a different output directory or filename.
+|
+
+|partintro block can only be used when doctype is book and it\'s a child of a part section. Excluding block content.
+|Invalid book document structure.
+|#book-parts-and-chapters#
+
+|unmatched macro: endif::<x>[]
+|`endif::[]` with no unclosed preceding `ifdef::<x>[]`.
+|#ifdef-directive#
+
+|<docname> dropping cell because it exceeds specified number of columns
+// The extra cells are dropped, but this message is not produced ???
+|
+|#tables#
+
+|<docname> illegal block content outside of partintro block
+|Invalid book document structure.
+|#book-parts-and-chapters#
+
+|<docname> invalid part, must have at least one section (e.g., chapter, appendix, etc.)
+|Invalid book document structure.
+|#book-parts-and-chapters#
+
+|<docname> malformed manpage title
+|Invalid manpage document structure.
+|#man-pages#
+
+|<docname> malformed name section body
+|Invalid manpage document structure.
+|#man-pages#
+
+|<docname> maximum include depth of 64 exceeded
+|Does your file include itself, directly or indirectly?
+|
+
+|<docname> mismatched macro: endif::<x>[], expected endif::<y>[]
+|ifdef/endif blocks must be strictly nested.
+|#ifdef-directive#
+
+|<docname> name section expected
+|Invalid manpage document structure.
+|#man-pages#
+
+|<docname> name section title must be at level 1
+|Invalid manpage document structure.
+|#man-pages#
+
+|<docname> only book doctypes can contain level 0 sections
+|Illegal use of a level-0 section when doctype is not book.
+|#sections#
+
+|<docname> table missing leading separator, recovering automatically
+|Check for missing cell separator characters at the start of the line.
+|#tables#
+|===
+
+[#fail]
+== Failure messages
+
+[options="header,breakable",cols="<60,<50,<30"]
+|===
+|Message |Troubleshooting |Also see
+
+|missing converter for backend '<x>'. Processing aborted. (RuntimeError)
+|You used -b with an invalid or missing backend.
+|
+
+//|Failed to load AsciiDoc document - undefined method `convert' for nil:NilClass
+//|
+//|#cli-options#
+
+|'tilt' could not be loaded
+|You must have the tilt gem installed (`gem install tilt`) to use custom backend templates
+|
+|===
+
+////
+API only
+
+|ERROR
+|IOError, %(target directory does not exist: #{to_dir})
+|API, the mkdirs option is not set, and the target directory does not already exist.
+|
+////
diff --git a/docs/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc
new file mode 100644
index 00000000..f5ed7914
--- /dev/null
+++ b/docs/modules/ROOT/pages/features.adoc
@@ -0,0 +1,67 @@
+= Asciidoctor's Features and Benefits
+:navtitle: Features and Benefits
+:url-rewrite: https://github.com/ocpsoft/rewrite/tree/master/transform-markup
+:url-manpage: {url-project}/man/asciidoctor
+// user-manual: Asciidoctor's most notable benefits
+// The primary benefits and supporting features of the application.
+
+While Asciidoctor aims to offer full compliance with the AsciiDoc syntax, it's more than just a clone.
+
+.Built-in and custom templates
+Asciidoctor uses a set of built-in ERB templates to generate HTML 5 and DocBook output that is structurally equivalent to what AsciiDoc produces.
+Any of these templates can be replaced by a custom template written in any template language available in the Ruby ecosystem.
+Custom template rendering is handled by the Tilt template abstraction library.
+Tilt is one of the most popular gems in the Ruby ecosystem.
+
+.Parser and object model
+Leveraging the Ruby stack isn't the only benefit of Asciidoctor.
+Unlike the AsciiDoc Python implementation, Asciidoctor parses and converts the source document in discrete steps.
+This makes conversion optional and gives Ruby programs the opportunity to extract, add or replace information in the document by interacting with the document object model Asciidoctor assembles.
+Developers can use the full power of the Ruby programming language to play with the content in the document.
+
+.Performance and security
+No coverage of Asciidoctor would be complete without mention of its _speed_.
+Despite not being an original goal of the project, Asciidoctor has proven startlingly fast.
+It loads, parses, and converts documents a *100 times as fast* as the Python implementation.
+That's good news for developer productivity and good news for GitHub or any server-side application that needs to render AsciiDoc markup.
+Asciidoctor also offers several levels of security, further justifying its suitability for server-side deployments.
+
+.Beyond Ruby
+Asciidoctor's usage is not limited to the Ruby community.
+Thanks to {url-jruby}[JRuby^], a port of Ruby to the JVM, Asciidoctor can be used inside Java applications as well.
+Plugins are available for #asciidoctor-maven-plugin Apache Maven#, #asciidoctor-gradle-plugin Gradle#, and {url-rewrite}[Rewrite^].
+These plugins are based on the #AsciidoctorJ# for Asciidoctor.
+
+Asciidoctor also ships with a command line interface (CLI).
+The Asciidoctor CLI, {url-manpage}[asciidoctor^], is a drop-in replacement for the `asciidoc.py` script from the AsciiDoc Python distribution.
+
+////
+
+AsciiDoc is about being able to focus on expressing your ideas, writing with ease and passing on knowledge without the distraction of complex applications or angle brackets.
+In other words, it's about discovering _writing zen_.
+
+AsciiDoc works because:
+
+- It's readable
+- It's concise
+- It's comprehensive
+- It's extensible
+- It produces beautiful output (HTML, DocBook, PDF, ePub and more)
+
+AsciiDoc is both easy to write and easy to read (in raw form).
+It's also easy to proof and edit.
+After all, it's plain text, just like that familiar e-mail.
+
+The AsciiDoc syntax is intuitive because it recognizes time-tested, plain text conventions for marking up or structuring the text.
+The punctuation was carefully chosen to look like what it means.
+A user unfamiliar with AsciiDoc can figure out the structure and semantics (i.e., what you mean) just by looking at it.
+Best of all, *it only requires a text editor to read or write*.
+
+AsciiDoc allows you to focus on the actual writing and only worry about tweaking the output when you are ready to render the document.
+The plain-text of an AsciiDoc document is easily converted into a variety of output formats, beautifully formatted, without having to rewrite the content.
+
+Copy text from an e-mail into a document and see how quickly you can turn it into documentation.
+Almost immediately, you'll find your writing zen and enjoy the rewarding experience of sharing knowledge.
+
+Live or die by documentation? Live.
+////
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
new file mode 100644
index 00000000..637ce9f3
--- /dev/null
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -0,0 +1,97 @@
+= Asciidoctor Documentation
+:navtitle: Introduction
+
+[caption=Migration in Progress]
+CAUTION: This documentation is in migration.
+If you're looking for the current Asciidoctor documentation, visit https://asciidoctor.org/docs.
+
+This section of the website contains the documentation for {url-project}[Asciidoctor^], a Ruby-based AsciiDoc processor.
+Asciidoctor also serves as the reference implementation for how the AsciiDoc language is interpreted.
+If you're looking for the documentation for the AsciiDoc language itself, refer to the xref:asciidoc::index.adoc[AsciiDoc section] of this website.
+//You can also find the documentation for AsciidoctorJ, Asciidoctor.js, and various extensions and integrations in other areas of this website.
+
+== What is Asciidoctor?
+
+Asciidoctor is a fast, open source text processor for parsing AsciiDoc into a document model and converting to output formats such as [.nowrap]#HTML 5#, [.nowrap]#DocBook 5#, PDF, and [.nowrap]#EPUB 3#.
+
+To simplify installation, Asciidoctor is packaged and distributed as a RubyGem (aka gem) named https://rubygems.org/gem/asciidoctor[asciidoctor] to {url-rubygem}[RubyGems.org^].
+The asciidoctor gem can be installed on all major operating systems using Ruby packaging tools.
+Asciidoctor is also distributed as a package for numerous Linux distributions as well as macOS.
+
+The Asciidoctor software is open source under the terms of the MIT license and {url-org}[hosted on GitHub^].
+
+== Basic usage
+
+Asciidoctor provides two primary interfaces for processing AsciiDoc documents:
+
+[cols=2*]
+|===
+| CLI | API
+
+a|
+ $ asciidoctor document.adoc
+
+
+a|
+[source,ruby]
+----
+require 'asciidoctor'
+Asciidoctor.convert_file \
+  'document.adoc', safe: :safe
+----
+
+|See xref:cli:index.adoc[] to learn more about this interface.
+|See xref:api:index.adoc[] to learn more about this interface.
+|===
+
+== Relationship to AsciiDoc
+
+AsciiDoc is the language. +
+Asciidoctor is the processor.
+
+You compose documents using the xref:asciidoc::index.adoc[AsciiDoc language], which is a text-based writing format.
+The AsciiDoc language was designed to be unobtrusive and concise to simplify writing and make it more pleasant.
+But AsciiDoc itself is not a publishing format.
+It's more like a shorthand.
+That's where an AsciiDoc processor comes in.
+
+//Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree into a set of built-in templates to produce HTML, PDF, DocBook, man page, and other output formats.
+//You have the option of writing your own converter or loading Tilt-supported templates to customize the generated output or produce alternative formats.
+//Asciidoctor also offers a responsive theme based on Foundation to style the HTML5 output.
+
+An AsciiDoc processor, such as Asciidoctor, reads the AsciiDoc source and converts it to publishable formats such as HTML 5 or PDF.
+It can also convert it to formats which themselves can be processed by a publishing toolchain, such as DocBook.
+
+Since AsciiDoc is not published as is, the processing step provides an opportunity to augment the document by expanding shorthand codes, layering in integrations, and applying a pleasant visual style.
+That augmentation is a large part of what Asciidoctor does.
+
+In brief, you give AsciiDoc source to Asciidoctor and it gives you a result you can publish.
+
+== Ecosystem
+
+When we talk about Asciidoctor in this section, we are talking about the core processor and built-in converters.
+Asciidoctor also has an ecosystem of extensions, converters, build plugins, and tools to help you author and publish AsciiDoc.
+You can find the documentation for these projects elsewhere on this site or in the Asciidoctor organization on GitHub.
+
+== Beyond Ruby
+
+Although Asciidoctor is written in Ruby, it does not mean you are stuck using Ruby.
+You can also run Asciidoctor using a JVM or JavaScript.
+
+=== Java / JVM
+
+Thanks to https://github.com/asciidoctor/asciidoctorj[AsciidoctorJ^], Asciidoctor can be used in any program that runs on a Java Virtual Machine (JVM).
+Under the covers, AsciidoctorJ uses JRuby to run Asciidoctor, but this is hidden behind a Java API.
+AsciidoctorJ even provides an alternate CLI, which means you can get the full Asciidoctor experience with only a Java runtime.
+Building atop AsciidoctorJ, there are also plugins that integrate Asciidoctor into Apache Maven, Gradle, or Javadoc builds.
+
+=== JavaScript
+
+Thanks to xref:asciidoctor.js::index.adoc[Asciidoctor.js], Asciidoctor can also be used in JavaScript.
+The Asciidoctor.js project uses Opal to transpile the Ruby source in Asciidoctor to JavaScript.
+The result is a fully-functional version of Asciidoctor that works on any JavaScript runtime, such as a modern browser or Node.js.
+Asciidoctor.js even provides an alternate CLI, which means you can get the full Asciidoctor experience with only a JavaScript runtime.
+Asciidoctor.js is used to power the AsciiDoc language preview extensions for Chrome, Atom, Brackets, and other web-based tooling.
+
+To be accurate, you can run Asciidoctor using Ruby, a JVM, or JavaScript.
+This documentation focuses on the Ruby version of Asciidoctor.
diff --git a/docs/modules/ROOT/pages/language-support.adoc b/docs/modules/ROOT/pages/language-support.adoc
new file mode 100644
index 00000000..4af521ff
--- /dev/null
+++ b/docs/modules/ROOT/pages/language-support.adoc
@@ -0,0 +1,159 @@
+= Language Support
+:url-docbook-i8n: http://www.sagehill.net/docbookxsl/Localizations.html
+:url-lang-attributes: {url-org}/asciidoctor/blob/master/data/locale/attributes.adoc
+// um anchor: language-support
+
+The built-in labels, messages, and syntax keywords in Asciidoctor are English by default.
+However, Asciidoctor is not restricted to working with English-only content.
+Asciidoctor can process the full range of the UTF-8 character set.
+That means you can write your document in any language, save the file with UTF-8 encoding, and expect Asciidoctor to convert the text properly.
+Furthermore, you can customize the built-in labels (e.g., "`Appendix`") to match the language in which you are writing.
+
+There are some caveats to know about:
+
+* Currently, the official HTML and PDF converters only fully support left-to-right (and top-to-bottom) reading.
+Support for right-to-left (RTL) is being worked on.
+See {url-org}/asciidoctor/issues/1601[issue #1601^] for details.
+In the interim, you can leverage the DocBook toolchain to get right-to-left support.
+* Attributes that store dates and times (e.g., `docdatetime`) are always formatted like `2019-01-04 19:26:06 GMT+0000`.
+* Message (aka logging) strings are always in English.
+* Asciidoctor does not support the language conf files used by AsciiDoc Python.
+However, Asciidoctor does provide {url-lang-attributes}[a translation file^] that can be used for a similar purpose.
+
+[#customizing-labels]
+== Translating built-in labels
+
+When converting to DocBook, you can rely on the DocBook toolchain to translate (most) built-in labels.
+To activate this feature, simply set the `lang` attribute to a valid country code (which defaults to `en` for English).
+For example:
+
+----
+$ asciidoctor -a lang=es -b docbook article.adoc
+----
+
+The list of supported languages, as well as additional language considerations for DocBook, are described in {url-docbook-i8n}[DocBook XSL: The Complete Guide^].
+
+The `lang` attribute _does not_ enable automatic translation of built-in labels when converting directly to HTML or PDF.
+It's merely a hint to configure the DocBook toolchain.
+If you're not using the DocBook toolchain for publishing, you must translate each built-in label yourself.
+One way is to set the following attributes in the document header or by passing the attributes via the API or CLI:
+
+.Attributes that control built-in labels
+[%autowidth]
+|===
+|Attribute name |Used for |Default
+
+|appendix-caption
+|Appendix titles.
+|Appendix
+
+|caution-caption
+|CAUTION admonitions (when icons are not in use).
+|Caution
+
+|chapter-label
+|Prefix added to chapter titles (i.e., level-1 section titles when doctype is book). _(pdf converter only)_
+|Chapter
+
+|example-caption
+|Example titles.
+|Example
+
+|figure-caption
+|Automatically prefixed to figure titles.
+|Figure
+
+|important-caption
+|IMPORTANT admonitions (when icons are not in use).
+|Important
+
+|last-update-label
+|Label for when the document was last updated.
+|Last updated
+
+|listing-caption
+|The label for listing blocks.
+By default, listing blocks do not have captions.
+If you specify `listing-caption`, then you also turn on captions for listing blocks.
+|_not set_
+
+|manname-title
+|Label for the program name section in the man page.
+|NAME
+
+|note-caption
+|NOTE admonitions (when icons are not in use).
+|Note
+
+|preface-title
+|Title text used for the anonymous preface (when the `doctype` is book).
+|_not set_
+
+|table-caption
+|Automatically prefixed to table titles.
+|Table
+
+|tip-caption
+|TIP admonitions (when icons are not in use).
+|Tip
+
+|toc-title
+|Title of the table of contents.
+|Table of Contents
+
+|untitled-label
+|The document title, for documents that have only body content.
+|Untitled
+
+|version-label
+|The label preceding the revnumber in the document's byline.
+|Version
+
+|warning-caption
+|WARNING admonitions (when icons are not in use).
+|Warning
+|===
+
+If you plan to support multiple languages, you'll want to define the attributes for each language inside a conditional preprocessor directive.
+For example:
+
+[source]
+----
+\ifeval::["{lang}" == "de"]
+:caution-caption: Achtung
+...
+\endif::[]
+----
+
+Of course, you're probably hoping this has already been done for you.
+Indeed, it has!
+
+You can find an {url-lang-attributes}[AsciiDoc file^] in the Asciidoctor repository that provides translations of these attributes for most major languages.
+The translations are defined using AsciiDoc attribute entries inside conditional preprocessor blocks, just as suggested above.
+
+To use this file to translate the built-in labels according the value of the `lang` attribute (just like the DocBook toolchain does), follow these steps:
+
+. Download the AsciiDoc file {url-lang-attributes}[attributes.adoc^] from the Asciidoctor repository.
+. Put the file in the folder [.path]_locale_ relative to your document.
+. Add the following line to the header of your AsciiDoc document:
++
+[source]
+----
+\include::locale/attributes.adoc[]
+----
+
+. Set the language using the `lang` attribute.
+This attribute must be set before the include directive gets processed.
+For example:
+
+ -a lang=es
+
+The built-in labels will now be translated automatically based on the value of the `lang` attribute.
+
+There's an ongoing discussion about how to make language support even simpler ({url-org}/asciidoctor/issues/1129[issue #1129^]).
+Input is welcome.
+
+== Translation
+
+Asciidoctor (or DocBook) currently does not support translation of content out of the box.
+There's a proposal to integrate gettext (https://discuss.asciidoctor.org/Professional-providers-translating-Asciidoc-tt2692.html#none[discussion^]), and suggestions are welcome.
diff --git a/docs/modules/ROOT/pages/safe-modes.adoc b/docs/modules/ROOT/pages/safe-modes.adoc
new file mode 100644
index 00000000..3e06f836
--- /dev/null
+++ b/docs/modules/ROOT/pages/safe-modes.adoc
@@ -0,0 +1,83 @@
+= Safe Modes
+
+Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and scripts while a document is processing.
+Each level includes the restrictions enabled in the prior security level.
+
+== Safe mode levels
+
+`UNSAFE`::
+A safe mode level that disables any security features enforced by Asciidoctor.
+Ruby is still subject to its own restrictions.
++
+*This is the default safe mode for the CLI.*
+Its integer value is `0`.
+
+`SAFE`::
+This safe mode level prevents access to files which reside outside of the parent directory of the source file.
+The `include` directive is enabled, but paths to `include` files must be within the parent directory.
+This mode allows assets (such as the stylesheet) to be embedded in the document.
++
+Its integer value is `1`.
+
+`SERVER`::
+A safe mode level that disallows the document from setting attributes that would affect conversion of the document.
+This level trims `docfile` to its relative path and prevents the document from:
++
+--
+* setting `source-highlighter`, `doctype`, `docinfo` and `backend`
+* seeing `docdir` (as it can reveal information about the host filesystem)
+
+It allows `icons` and `linkcss`.
+
+Its integer value is `10`.
+--
+
+`SECURE`::
+A safe mode level that disallows the document from attempting to read files from the file system and including their contents into the document.
+Additionally, it:
++
+--
+* disables icons
+* disables the `include` directive
+* data can not be retrieved from URIs
+* prevents access to stylesheets and JavaScripts
+* sets the backend to `html5`
+* disables `docinfo` files
+* disables `data-uri`
+* disables interactive (`opts=interactive`) and inline (`opts=inline`) modes for SVGs
+* disables `docdir` and `docfile` (as these can reveal information about the host filesystem)
+* disables source highlighting
+
+xref:extensions:register.adoc[Asciidoctor extensions] may still embed content into the document depending whether they honor the safe mode setting.
+
+*This is the default safe mode for the API.*
+Its integer value is `20`.
+--
+
+////
+|===
+
+|{empty} |Unsafe |Safe |Server |Secure
+
+|URI access
+|system access
+|base directory access
+|docdir
+|docfile
+|docinfo
+|backend
+|doctype
+|source-highlighter
+|macros
+|include
+|data-uri
+|linkcss
+|icons
+
+|===
+
+TIP: GitHub processes AsciiDoc files using the `SECURE` level.
+////
+
+The safe mode can be set from the  xref:cli:set-safe-mode.adoc[CLI] and the xref:api:set-safe-mode.adoc[API].
+You can also xref:attributes-and-safe-modes.adoc[manage attributes by safe mode].
diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc
new file mode 100644
index 00000000..2ca77a17
--- /dev/null
+++ b/docs/modules/ROOT/pages/whats-new.adoc
@@ -0,0 +1,403 @@
+//= What's New (Asciidoctor {page-component-version})
+= What's New ({page-component-version})
+:doctype: book
+:page-toclevels: 0
+:url-releases-asciidoctor: {url-org}/asciidoctor/releases
+:url-milestone: {url-org}/asciidoctor/milestone/33?closed=1:
+
+_**Cumulative issues resolved:** {url-milestone}[2.0.x^]_
+
+= Asciidoctor 2.0.11
+
+_**Release date:** 2020.11.02_
+
+== Bug fixes
+
+* Fix infinite loop when callout list with obsolete syntax is found inside list item (#3472)
+* Fix infinite loop when xreftext contains a circular reference path in HTML and manpage converters (#3543)
+* Apply text formatting to table cells in implicit header row when column has the "a" or "l" style (#3760)
+* Fix errant reference warning for valid reference when running in compat mode (#3555)
+* Initialize backend traits for converter (if not previously initialized) using assigned basebackend; mimics Asciidoctor < 2 behavior (#3341)
+* Set source_location on preamble block when sourcemap option is enabled (#3799)
+* Link the notitle and showtitle attributes so they act as opposites for the same toggle (#3804)
+* Pass options to constructor of Rouge lexer instead of #lex method; restores compatibility with Rouge >= 3.4 (#3336)
+* Don't clobber cgi-style options on language when enabling start_inline option on the Rouge PHP lexer (#3336)
+* Fix parsing of wrapped link and xref text, including when an attrlist signature is detected (#3331)
+* Restore deprecated writable number property on AbstractBlock
+* Always use title as xreftext if target block has an empty caption, regardless of xrefstyle value (#3745)
+* Allow a bibliography reference to be used inside a footnote (#3325)
+* Fix bottom margin collapsing on AsciiDoc table cell (#3370)
+* Remove excess hard line break in multi-line AsciiMath blocks (#3407)
+* Only strip trailing spaces from lines of AsciiDoc include file (#3436)
+* Remove errant optional flag in regexp for menu macro that breaks Asciidoctor.js (#3433)
+* Preserve repeating backslashes when generating manpage output (#3456)
+* Honor percentage width specified on macro of inline SVG (#3464)
+* Removing leading and trailing blank lines in AsciiDoc include file to match assumption of parser (#3470)
+* Activate extensions when :extensions option is set even if Extensions API is not yet loaded (#3570)
+* Don't activate global extensions if :extensions option is false (#3570)
+* Escape ellipsis at start of line in manpage output (#3645) (*@jnavila*)
+* Don't register footnote with ID if a footnote is already registered with that ID (#3690)
+* Honor start attribute on ordered list in manpage output (#3714)
+* Warn instead of crashing if SVG to inline is empty (#3638) (*@mogztter*)
+* Compute highlight line ranges on source block relative to value of start attribute (#3519) (*@mogztter*)
+* Prevent collapsible block from incrementing example number by assigning an empty caption (#3639)
+* Use custom init function for highlight.js to select the correct `code` elements (#3761)
+* Fix resolved value of :to_dir when both :to_file and :to_dir options are set to absolute paths (#3778)
+* Fix crash if value of `stylesheets` attribute contains a folder and the destination directory for the stylesheet does not exist (even when the `:mkdirs` option is set) (#3808)
+* Fix crash if value passed by API for `copycss` attribute is not a string (#3592)
+* Restore label in front of each bibliography entry in DocBook output that was dropped by fix for #3085 (#3782)
+* Apply max width to each top-level container instead of body in HTML output (#3513)
+* Don't apply border-collapse: separate to HTML for table blocks; fixes double border at boundary of colspan/rowspan (#3793) (*@ahus1*)
+* Don't remove right border on last table cell in row (#2563)
+* Rework table borders to leverage border collapsing (apply frame border to table, grid border to cells, and selectively override border on cells to accommodate frame) (#3387)
+
+== Compliance
+
+* Add support for muted option to self-hosted video (#3408)
+* Move style tag for convert-time syntax highlighters (coderay, rouge, pygments) into head (#3462)
+* Move style tag for client-side syntax highlighters (highlight.js, prettify) into head (#3503)
+* Define entry point API methods (load, convert, load_file, convert_file) as class methods instead of module_function to avoid conflict with Kernel.load (#3625)
+* Retain attribute order on HTML code tag for source block to remain consistent with output from 1.5.x (#3786)
+* Correct language code for Korean language file from kr to ko (#3807) (*@jnavila*)
+
+== Improvements
+
+* Apply word wrap (i.e., `word-wrap: anywhere`) to body in default stylesheet (#3544)
+* Allow `nobreak` and `nowrap` roles to be used on any inline element (#3544)
+* Add CSS class to support pre-wrap role to preserve leading, trailing, and repeating spaces in phrase (#3815)
+* Preserve guard around XML-style callout when icons are not enabled (#3319)
+* Use `.fam C` command to switch font family for verbatim blocks to monospaced text in manpage output (#3561)
+* Remove redundant test for halign and valign attributes on table cell in DocBook converter
+* Allow encoding of include file to be specified using encoding attribute (#3248)
+* Allow template to be used to override outline by only specifying the outline template (#3491)
+* Upgrade MathJax from 2.7.5 to 2.7.9
+* Upgrade highlight.js from 9.15.10 to 9.18.3 (note that this increases script size from 48.8 KB to 71.5 KB)
+* Skip unused default attribute assignments for embedded document
+* Allow a URL macro to have a preceding single or double quote (#3376)
+* Add support for erubi template engine; use it in place of erubis in test suite; note the use of erubis is deprecated (#3737)
+* Download and embed remote custom stylesheet if allow-uri-read is set (#3765)
+* Remove direction property from default stylesheet (#3753) (*@abdnh*)
+* remove max width setting on content column for print media in default stylesheet (#3802)
+* Normalize frame value "topbot" to "ends" in HTML output (consistently use frame-ends class) (#3797)
+* Add role setter method on AbstractNode (#3614)
+* Map chapter-signifier and part-signifier attributes in locale attribute files to replace chapter-label and part-label (#3817)
+
+== Build and infrastructure
+
+* Run test suite on TruffleRuby nightly (*@mogztter*, *@erebor*)
+* Upgrade TruffleRuby to 20.0.0 (*@mogztter*)
+* Trigger upstream builds for AsciidoctorJ on Github Actions (*@robertpanzer*)
+
+= Asciidoctor 2.0.10
+
+_**Release date:** 2019.05.31_
+
+== Bug fixes
+
+* fix Asciidoctor.convert_file to honor `header_footer: false` option when writing to file (#3316)
+* fix placement of title on excerpt block (#3289)
+* always pass same options to SyntaxHighlighter#docinfo, regardless of value of location argument
+* fix signature of SyntaxHighlighter#docinfo method (#3300)
+* when `icons` is set to `image`, enable image icons, but don't use it as the value of the `icontype` attribute (#3308)
+
+= Asciidoctor 2.0.9
+
+_**Release date:** 2019.04.30_
+
+== Bug fixes
+
+* process multiple single-item menu macros in same line (#3279)
+* register images in catalog correctly (#3283)
+* rename AbstractNode#options method to AbstractNode#enabled_options so it doesn't get shadowed by Document#options (#3282)
+* don't fail to convert document if alt attribute is not set on block or inline image (typically by an extension)
+* fix lineno of source location on blocks that follow a detached list continuation (#3281)
+* assume inline image type is "image" if not set (typically by an extension)
+
+= Asciidoctor 2.0.8
+
+_**Release date:** 2019.04.22_
+
+== Bug fixes
+
+* restore background color applied to literal blocks by default stylesheet (#3258)
+* use portability constants (CC_ALL, CC_ANY) in regular expressions defined in built-in converters (DocBook5 and ManPage)
+* use portability constant (CC_ANY) in regular expression for custom inline macros
+* use smarter margin collapsing for AsciiDoc table cell content; prevent passthrough content from being cut off (#3256)
+* don't limit footnote ref to ASCII charset; allow any word character in Unicode to be used (#3269)
+
+== Improvements
+
+* register_for methods accept arguments as symbols (#3274)
+* use Concurrent::Map instead of Concurrent::Hash in template converter
+* use module_function keyword to define methods in Helpers
+* move regular expression definitions to separate source file (internal change)
+
+= Asciidoctor 2.0.7
+
+_**Release date:** 2019.04.13_
+
+== Bug fixes
+
+* fix crash when resolving ID from text and at least one candidate contains an unresolved xref (#3254)
+* fix compatibility with Rouge 2.0
+
+== Improvements
+
+* improve documentation for the `-a` CLI option; explain that `@` modifier can be placed at end of name as alternative to end of value
+* move source for main API entry points (load, load_file, convert, convert_file) to separate files (internal change)
+* define main API entry points (load, load_file, convert, convert_file) as module functions
+
+= Asciidoctor 2.0.6
+
+_**Release date:** 2019.04.04_
+
+== Bug fixes
+
+* assume implicit AsciiDoc extension on interdoc xref macro target with no extension (e.g., `document#`); restores 1.5.x behavior (#3231)
+* don't fail to load application if call to Dir.home fails; use a rescue with fallback values (#3238)
+* Helpers.rootname should only consider final path segment when dropping file extension
+
+== Improvements
+
+* implement Helpers.extname as a more efficient and flexible File.extname method
+* check for AsciiDoc file extension using end_with? instead of resolving the extname and using a lookup
+
+= Asciidoctor 2.0.5
+
+_**Release date:** 2019.04.01_
+
+== Bug fixes
+
+* fix crash when source highlighter is Rouge and source language is not set on block (#3223)
+* update CLI and SyntaxHighlighter to allow Asciidoctor to load cleanly on Ruby 2.0 - 2.2
+* CLI should use $stdin instead of STDIN to be consistent with the use of $stdout
+* mark encoding of stdio objects used in CLI as UTF-8 (#3225)
+* make Asciidoctor::SyntaxHighlighter::Config.register_for method public as documented
+
+= Asciidoctor 2.0.4
+
+_**Release date:** 2019.03.31_
+
+== Bug fixes
+
+* allow Asciidoctor to load cleanly on Ruby 2.0 - 2.2 for distributions that provide support for these older Ruby versions
+* make Asciidoctor::Converter::Config.register_for method public as documented
+* remove unused Asciidoctor::Converter::BackendTraits#derive_backend_traits private method
+* move Asciidoctor::Converter::BackendTraits.derive_backend_traits method to Asciidoctor::Converter
+* mark render and render_file methods as deprecated in API docs
+
+= Asciidoctor 2.0.3
+
+_**Release date:** 2019.03.28_
+
+== Bug fixes
+
+* fix crash when attrlist is used on literal monospace phrase (#3216)
+* update use of magic regexp variables to fix compatibility with Opal / Asciidoctor.js (#3214)
+
+= Asciidoctor 2.0.2
+
+_**Release date:** 2019.03.26_
+
+== Bug fixes
+
+* apply verbatim substitutions to literal paragraphs attached to list item (#3205)
+* implement #lines and #source methods on Table::Cell based on cell text (#3207)
+
+= Asciidoctor 2.0.1
+
+_**Release date:** 2019.03.25_
+
+== Bug fixes
+
+* convert titles of cataloged block and section nodes containing attribute references eagerly to resolve attributes while in scope (#3202)
+* customize MathJax (using a postfilter hook) to apply displaymath formatting to AsciiMath block (#2498)
+* fix misspelling of deprecated default_attrs DSL function (missing trailing "s")
+* remove unused location property (attr_accessor :location) on DocinfoProcessor class
+* look for deprecated extension option :pos_attrs if :positional_attrs option is missing (#3199)
+* add detail to load error message if path differs from gem name (#1884)
+
+== Build and infrastructure
+
+* bundle .yardopts in RubyGem (#3193)
+
+= Asciidoctor 2.0.0
+
+_**Release date:** 2019.03.22_
+
+== Enhancements and compliance
+
+* drop support for Ruby < 2.3 and JRuby < 9.1 and remove workarounds (#2764)
+* drop support for Slim < 3 (#2998)
+* drop the converter for the docbook45 backend from core; moved to https://github.com/asciidoctor/asciidoctor-docbook45 (#3005)
+* apply substitutions to section and block titles in normal substitution order (#1173)
+* make syntax highlighter pluggable; extract all logic into adapter classes (#2106)
+* add syntax highlighter adapter for Rouge (#1040)
+* redesign Converter API based on SyntaxHighlighter API; remap deprecated API to new API to ensure compatibility (#2891)
+* repurpose built-in converters as regular converters (#2891)
+* make registration and resolution of global converters thread-safe (#2891)
+* fold the default converter factory into the Converter module (#2891)
+* add a default implementation for Converter#convert in the Base converter (#2891)
+* rename Converter::BackendInfo to Converter::BackendTraits; map backend_info to new backend_traits method (#2891)
+* allow built-in converter classes to be resolved using Converter#for and instantiated using Converter#create (#2891)
+* allow converter factory to be passed using :converter_factory API option (#2891)
+* honor htmlsyntax if defined on converter (#2891)
+* add backend_traits_source keyword argument to CompositeConverter constructor (#2891)
+* add support for start attribute when using prettify to highlight source blocks with line numbering enabled
+* use String#encode to encode String as UTF-8 instead of using String#force_encoding (#2764)
+* add FILE_READ_MODE, URI_READ_MODE, and FILE_WRITE_MODE constants to control open mode when reading files and URIs and writing files (#2764)
+* set visibility of private and protected methods (#2764)
+* always run docinfo processor extensions regardless of safe mode (gives control to extension) (#2966)
+* use infinitive verb form for extension DSL method names; map deprecated method names where appropriate
+* add docinfo insertion slot for header location to built-in converters (#1720)
+* add support for the `muted` option on vimeo videos (allows autoplay to work in Chrome) (#3014)
+* use value of prettify-theme attribute as is if it starts with http:// or https:// (#3020)
+* allow icontype to be set using icons attribute (#2953)
+* when using a server-side syntax highlighter, highlight content of source block even if source language is not set (#3027)
+* automatically promote a listing block without an explicit style to a source block if language is set (#1117)
+* remove the 2-character (i.e., `""`) quote block syntax
+* don't allow block role to inherit from document attribute; only look for role in block attributes (#1944)
+* split out functionality of -w CLI flag (script warnings) from -v CLI flag (verbose logging) (#3030)
+* log possible invalid references at info level (#3030)
+* log dropped lines at info level when attribute-missing=drop-line (#2861)
+* honor attribute-missing setting when processing include directives and block macros (#2855)
+* log warning when include directive is not resolved due to missing attribute or blank target; always include warning in output document (#2868)
+* use the third argument of AbstractNode#attr / AbstractNode#attr? to set the name of a fallback attribute to look for on the document (#1934)
+* change default value of third argument to Abstractnode#attr / AbstractNode#attr? to nil so attribute doesn't inherit by default (#3059)
+* look for table-frame, table-grid, and table-stripes attributes on document as fallback for frame, grid, and stripes attributes on table (#3059)
+* add support for hover mode for table stripes (stripes=hover) (#3110)
+* always assume the target of a shorthand interdocument xref is a reference to an AsciiDoc document (source-to-source) (#3021)
+* if the target of a formal xref macro has a file extension, assume it's a path reference (#3021)
+* never assume target of a formal xref macro is a path reference unless a file extension or fragment is present (#3021)
+* encode characters in URI to comply with RFC-3986
+* implement full support for styled xreftext in manpage converter (#3077)
+* allow the ID and role properties to be set on a list item of ordered and unordered lists via the API (#2840)
+* yield processor instance to registration block for document processor if block has non-zero arity (i.e., has parameters)
+* add Document#parsed? method to check whether document has been parsed
+* modify Cell class to extend from AbstractBlock instead of AbstractNode (#2963)
+* implement block? and inline? methods on Column, both which return false (#2963)
+* drop verse table cell style (treat as normal table cell) (#3111)
+* allow negated subs to be specified on inline pass macro (#2191)
+* log warning if footnoteref macro is found and compat mode is not enabled (#3114)
+* log info message if inline macro processor returns a String value (#3176)
+* apply subs to Inline node returned by inline macro processor if subs attribute is specified (#3178)
+* add create_inline_pass helper method to base extension processor class (#3178)
+* log debug message instead of warning if block style is unknown (#3092)
+* allow backend to delegate to a registered backend using the syntax synthetic:delegate when using custom templates (e.g., slides:html) (#891)
+* AbstractBlock#find_by looks inside AsciiDoc table cells if traverse_documents selector option is true (#3101)
+* AbstractBlock#find_by finds table cells, which can be selected using the :table_cell context in the selector (#2524)
+* allow ampersand to be used in e-mail address (#2553)
+* propogate ID assigned to inline passthrough (#2912)
+* rename control keywords in find_by to better align with the standard NodeFilter terminology
+* stop find_by iteration if filter block returns :stop directive
+* rename header_footer option to standalone (while still honoring header_footer for backwards compatibility) (#1444)
+* replace anchors and xrefs before footnotes (replace footnotes last in macros substitution group)
+* apply substitution for custom inline macro before all other macros
+* only promote index terms automatically (A, B, C becomes A > B > C + B > C + C) if indexterm-promotion option is set on document (#1487)
+* add support for see and see-also on index terms; parse attributes on indexterm macros if text contains `=` (#2047)
+* drop :indexterms table from document catalog (in preparation for solution to #450 in a 2.x release)
+* load additional languages for highlight.js as defined in the comma-separated highlightjs-languages attribute (#3036)
+* log warning if conditional expression in ifeval directive is invalid (#3161)
+* drop lines that contain an invalid preprocessor directive (#3161)
+* rename AbstractBlock#find_by directives; use :prune in place of :skip_children and :reject in place of :skip
+* convert example block into details/summary tag set if collapsible option is set; open by default if open option is set (#1699)
+* substitute replacements in author values used in document header (#2441)
+* require space after semi-colon that separates multiple authors (#2441)
+* catalog inline anchors at start of callout list items (#2818) (*@owenh000*)
+* add parse_attributes helper method to base extension Processor class (#2134)
+
+== Improvements
+
+* propagate document ID to DocBook output (#3011)
+* always store section numeral as string; compute roman numeral for part at assignment time (@vmj)
+* refactor code to use modern Hash syntax
+* define LIB_DIR constant; rename *_PATH constants to *_DIR constants to be consistent with RubyGems terminology (#2764)
+* only define ROOT_DIR if not already defined (for compatibility with Asciidoctor.js)
+* move custom docinfo content in footer below built-in docinfo content in footer in HTML converter (#3017)
+* read and write files using File methods instead of IO methods (#2995)
+* value comparison in AbstractNode#attr? is only performed if expected value is truthy
+* align default CodeRay style with style for other syntax highlighters (#2106)
+* ensure linenos class is added to linenos column when source highlighter is pygments and pygments-css=style
+* disable table stripes by default (#3110)
+* rename CSS class of Pygments line numbering table to linenotable (to align with Rouge) (#1040)
+* remove unused Converter#convert_with_options method (#2891)
+* add -e, --embedded CLI flag as alias for -s, --no-header-footer (require long option to specify eRuby impl) (#1444)
+* don't store the options attribute on the block once the options are parsed (#3051)
+* add an options method on AbstractNode to retrieve the set of option names (#3051)
+* pass :input_mtime option to Document constructor; let Document constructor assign docdate/time/year attributes (#3029)
+* never mutate strings; add a `frozen_string_literal: true` magic comment to top of all Ruby source files (#3054)
+* always use docdate and doctime to compute docyear and docdatetime (#3064)
+* rename PreprocessorReader#exceeded_max_depth? to PreprocessorReader#exceeds_max_depth? and return nil if includes are disabled
+* stop populating :ids table in document catalog (#3084)
+* always use :refs table in document catalog to look for registered IDs (#3084)
+* don't compute and store reference text in document catalog (#3084)
+* populate reference text table lazily for resolving ID by reference text (#3084)
+* don't store fallback reference text on :bibref node (#3085)
+* call AbstractNode#reftext instead of AbstractNode#text to retrieve reference text for bibref node (#3085)
+* only map unparsed attrlist of inline macro to target when format is short
+* add clearer exception message when source data is binary or has invalid encoding (#2884)
+* rename context for table cell and table column to :table_cell and :table_column, respectively
+* rename hardbreaks document attribute to hardbreaks-option; retain hardbreaks as a deprecated alias (#3123)
+* extend TLD for implicit e-mail addresses to 5 characters (#3154)
+* truncate with precision (instead of rounding) when computing absolute width for columns in DocBook output (#3131)
+* drop legacy LaTeX math delimiters (e.g, `$..$`) if present (#1339)
+* use proper terminology in warning message about mismatched preprocessor directive (#3165)
+* rename low-level extension attribute name :pos_attrs to :positional_attrs
+* mark default_attrs extension DSL method deprecated in favor of default_attributes
+* upgrade MathJax to 2.7.5
+
+== Bug fixes
+
+* fix crash caused by inline passthrough macro with the macros sub clearing the remaining passthrough placeholders (#3089)
+* fix crash if ifeval directive is missing expression (#3164)
+* prevent relative leveloffset from making section level negative and causing hang (#3152)
+* don't fail to parse Markdown-style quote block that only contains attribution line (#2989)
+* enforce rule that Setext section title must have at least one alphanumeric character; fixes problem w/ block nested inside quote block (#3060)
+* apply header subs to doctitle value when assigning it back to the doctitle document attribute (#3106)
+* don't fail if value of pygments-style attribute is not recognized; gracefully fallback to default style (#2106)
+* do not alter the $LOAD_PATH (#2764)
+* fix crash if stem block is empty (#3118)
+* remove conditional comment for IE in output of built-in HTML converter; fixes sidebar table of contents (#2983)
+* fix styling of source blocks with linenums enabled when using prettify as syntax highlighter (#640)
+* update default stylesheet to support prettify themes (#3020)
+* remove hard-coded color values on source blocks in default stylesheet (#3020)
+* add fallback if relative path cannot be computed because the paths are located on different drives (#2944)
+* ignore explicit section level style (#1852)
+* don't eat space before callout number in source block if line-comment attribute is empty (#3121)
+* check if type is defined in a way that's compatible with autoload
+* fix invalid check for DSL in extension class (previously always returned true)
+* scope constant lookups (#2764)
+* use byteslice instead of slice to remove BOM from string (#2764)
+* don't fail if value of -a CLI option is empty string or equals sign (#2997)
+* allow failure level of CLI to be set to info
+* Reader#push_include should not fail if data is nil
+* fix deprecated ERB trim mode that was causing warning (#3006)
+* move time anchor after query string on vimeo video to avoid dropping options
+* allow color for generic text, line numbers, and line number border to inherit from Pygments style (#2106)
+* enforce and report relative include depth properly (depth=0 rather than depth=1 disables nested includes)
+* allow outfilesuffix to be soft set from API (#2640)
+* don't split paragraphs in table cell at line that resolves to blank if adjacent to other non-blank lines (#2963)
+* initialize the level to WARN when instantiating the NullLogger
+* next_adjacent_block should not fail when called on dlist item (#3133)
+* don't suppress browser styles for summary tag; add pointer cursor and panel margin bottom (#3155)
+* only consider TLDs in e-mail address that have ASCII alpha characters
+* allow underscore in domain of e-mail address
+
+== Build and infrastructure
+
+* clear SOURCE_DATE_EPOCH env var when testing timezones (PR #2969) (*@aerostitch*)
+* remove compat folder (removes the AsciiDoc Python config file that provides pseudo-compliance with Asciidoctor and a stylesheet for an old Font Awesome migration)
+* add Ruby 2.6.0 to build matrix
+* stop running CI job on unsupported versions of Ruby
+* exclude test suite, build script, and Gemfile from gem (#3044)
+* split build tasks out into individual files
+
+////
+== Sections and book parts
+
+Hide the titles of special sections, such as the dedication, with `untitled` (DocBook backend only).
+
+Number all sections, including special sections, with `:sectnums: all`.
+
+Number book parts with `:partnums:`.
+////