rearchitect modules and filenames and drop asciidoctor folder under docs

91 files changed, 5188 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:`.
+////
diff --git a/docs/modules/api/nav.adoc b/docs/modules/api/nav.adoc
new file mode 100644
index 00000000..25a3a937
--- /dev/null
+++ b/docs/modules/api/nav.adoc
@@ -0,0 +1,6 @@
+* xref:index.adoc[]
+** xref:convert-strings.adoc[]
+** xref:generate-html-toc.adoc[]
+** xref:load-templates.adoc[]
+** xref:set-safe-mode.adoc[]
+** xref:options.adoc[]
diff --git a/docs/modules/api/pages/convert-strings.adoc b/docs/modules/api/pages/convert-strings.adoc
new file mode 100644
index 00000000..1f4a102a
--- /dev/null
+++ b/docs/modules/api/pages/convert-strings.adoc
@@ -0,0 +1,89 @@
+= Load and Convert Strings Using the API
+:navtitle: Load and Convert Strings
+
+To parse an AsciiDoc-formatted string into a document object model, use:
+
+[source,ruby]
+----
+doc = Asciidoctor.load '*This* is Asciidoctor.'
+----
+
+To convert the AsciiDoc-formatted string directly to HTML, use:
+
+[source,ruby]
+----
+puts Asciidoctor.convert '*This* is Asciidoctor.'
+----
+
+Here's the output you will see:
+
+[source,html]
+----
+<div class="paragraph">
+<p><strong>This</strong> is Asciidoctor.</p>
+</div>
+----
+
+When converting a string, Asciidoctor does not output a standalone document by default.
+Instead, it generates embeddable output.
+Let's learn why that is and how to control it.
+
+== Embedded output
+
+When you pass a string to `Asciidoctor.convert` to convert it to a backend format, such as HTML, this method only returns the converted content for those blocks.
+It does not include the frame around that content (i.e., the header and footer) that is needed to make a standalone document.
+Instead, it makes an _embedded_ document.
+This default was chosen to make Asciidoctor consistent with other lightweight markup processors like Markdown.
+
+Here's what's included in an embedded document:
+
+* The document title, but only if the `showtitle` attribute is set (no attribution and revision information)
+* The table of contents if the `toc` attribute is enabled (and not macro or preamble)
+* The converted document body
+* The footnotes unless the `nofootnotes` attribute is set
+
+== Standalone output
+
+You can still generate a standalone document when converting a string.
+To convert from an AsciiDoc string to a standalone output document, you need to explicitly set the `header_footer` option to `true`.
+
+[source,ruby]
+----
+puts Asciidoctor.convert '*This* is Asciidoctor.', header_footer: true
+----
+
+Now you will see a full HTML file.
+
+When the input or output is a file, the `header_footer` option is enabled by default.
+
+[source,ruby]
+----
+Asciidoctor.convert '*This* is Asciidoctor.', to_file: 'out.html'
+----
+
+If you want to generate embedded output when starting with a file, set the `header_footer` option to `false`.
+However, most of the time you'll want to generate a standalone document when converting a file (which is why it's default).
+
+When converting a string, the TOC is only included by default when using the `header_footer` option as shown above (whether it's enabled implicitly or explicitly).
+However, you can force it to be included without the header and footer by setting the `toc` attribute with a value of `macro` and using the `toc::[]` macro in the string itself.
+
+== Convert inline markup only
+
+If you only want the inline markup to be returned, set the `:doctype` option to `'inline'`:
+
+[source,ruby]
+----
+puts Asciidoctor.convert '*This* is Asciidoctor.', :doctype => 'inline'
+----
+
+In this mode, Asciidoctor will only process the first block (e.g., paragraph) in the document and ignore the rest.
+
+== Convert to DocBook
+
+You can produce DocBook 5.0 by setting the `backend` option to `'docbook'`.
+Since embeddable DocBook isn't that useful, we also enable the standalone document (i.e., header and footer) by setting the `header_footer` option to `true`.
+
+[source,ruby]
+----
+puts Asciidoctor.convert '*This* is Asciidoctor.', header_footer: true, backend: 'docbook'
+----
diff --git a/docs/modules/api/pages/generate-html-toc.adoc b/docs/modules/api/pages/generate-html-toc.adoc
new file mode 100644
index 00000000..c53a538b
--- /dev/null
+++ b/docs/modules/api/pages/generate-html-toc.adoc
@@ -0,0 +1,33 @@
+= Generate an HTML TOC
+
+Asciidoctor's HTML 5 converter has built-in support for generating a TOC.
+This TOC generator can also be used as a general purpose API.
+This logic is available via the `outline` method on the HTML5 converter.
+
+The `outline` method excepts a Document object and an optional Hash of options, and returns an HTML string.
+It can be resolved and invoked from anywhere using the following:
+
+[source,ruby]
+----
+html_toc = (Asciidoctor::Converter.for 'html5').outline document
+----
+
+The method can also be executed from inside a converter template (e.g., Slim, Haml, or ERB).
+When using a composite converter, this call will be run through the converter chain.
+
+[source,ruby]
+----
+= converter.convert document, 'outline'
+----
+
+The method is also available through the Document API:
+
+[source,ruby]
+----
+html_doc = document.converter.convert document, 'outline'
+----
+
+The `outline` method accepts the following options:
+
+sectnumlevels:: the number of section levels to number (defaults to the value of the `sectnumlevels` attribute.
+toclevels:: the depth of the toc (defaults to the value of the `toclevels` attribute)
diff --git a/docs/modules/api/pages/index.adoc b/docs/modules/api/pages/index.adoc
new file mode 100644
index 00000000..5c909faa
--- /dev/null
+++ b/docs/modules/api/pages/index.adoc
@@ -0,0 +1,50 @@
+= Process AsciiDoc Using the API
+:url-api: https://www.rubydoc.info/gems/asciidoctor
+////
+API introduction for Asciidoctor
+included in the user-manual Quickstarts, Using the Ruby API
+doc-asciidoctorj is now url-asciidoctorj-docs but! that means I need to fix docref: link:/docs and doc-asciidoctorj: {docref}/asciidoctorj
+////
+
+In addition to its CLI, Asciidoctor provides a Ruby API.
+The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub.
+
+Asciidoctor also has a Java API that mirrors the Ruby API.
+The Java API calls through to the Ruby API using an embedded JRuby runtime.
+See the AsciidoctorJ documentation for more information.
+
+== Load and convert a document using the API
+
+To use Asciidoctor in your application, you first need to require the gem:
+
+[source,ruby]
+require 'asciidoctor'
+
+This one statement makes all of the {url-api}[public APIs in Asciidoctor] available to your script or application.
+Now you can start processing AsciiDoc documents.
+The main entry points in the Asciidoctor API are the static methods to load or convert AsciiDoc documents, which we'll cover on this page.
+
+To parse a file into an `Asciidoctor::Document` object:
+
+[source,ruby]
+doc = Asciidoctor.load_file 'my-sample.adoc'
+
+You can get information about the document:
+
+[source,ruby]
+puts doc.doctitle
+puts doc.attributes
+
+To convert a file containing AsciiDoc markup to HTML 5, use:
+
+[source,ruby]
+Asciidoctor.convert_file 'my-sample.adoc'
+
+The command will output to the file [.path]_my-sample.html_ in the same directory.
+
+You can convert the file to DocBook 5.0 by setting the `:backend` option to `'docbook'`:
+
+[source,ruby]
+Asciidoctor.convert_file 'my-sample.adoc', backend: 'docbook'
+
+The command will output to the file [.path]_my-sample.xml_ in the same directory.
diff --git a/docs/modules/api/pages/load-templates.adoc b/docs/modules/api/pages/load-templates.adoc
new file mode 100644
index 00000000..487ecd57
--- /dev/null
+++ b/docs/modules/api/pages/load-templates.adoc
@@ -0,0 +1,24 @@
+= Load Custom Templates
+:url-tilt: https://github.com/rtomayko/tilt
+:url-tests: {url-org}/asciidoctor/tree/master/test
+
+Asciidoctor allows you to override the converter methods used to convert almost any individual AsciiDoc element.
+If you provide a directory of {url-tilt}[Tilt^]-compatible templates, named in such a way that Asciidoctor can figure out which template goes with which element, Asciidoctor will use the templates in this directory instead of its built-in templates for any elements for which it finds a matching template.
+It will fallback to its default templates for everything else.
+
+[source,ruby]
+----
+puts Asciidoctor.convert '*This* is Asciidoctor.', :header_footer => true,
+  :template_dir => 'templates'
+----
+
+The Document and Section templates should begin with `document` and `section`, respectively.
+The file extension is used by Tilt to determine which view framework it will use to use to interpret the template.
+For instance, if you want to write the template in ERB, you'd name these two templates `document.html.erb` and `section.html.erb`.
+The first file extension, `.html`, maps to the converter and the second, `.erb` maps to the template engine.
+To use Haml as the template engine, you'd name the templates `document.html.haml` and `section.html.haml`.
+
+Templates for block elements, like a paragraph or sidebar, are named after the block they handle.
+For instance, to override the default paragraph template with an ERB template, put a file named `paragraph.html.erb` in the template directory you pass to the `Document` constructor using the `:template_dir` option.
+
+For more usage examples, see the {url-tests}[test suite^].
diff --git a/docs/modules/api/pages/options.adoc b/docs/modules/api/pages/options.adoc
new file mode 100644
index 00000000..5a498567
--- /dev/null
+++ b/docs/modules/api/pages/options.adoc
@@ -0,0 +1,165 @@
+= API Options
+
+[cols="15m,15,15,15,15"]
+|===
+|Name |Description |Default value |Allowed values |CLI equivalent
+
+|:attributes
+|Sets additional document attributes, which override equivalently-named attributes defined in the document unless the name or value ends with `@`.
+When using the Hash form, a `nil` value unsets the attribute and a `false` value soft unsets the attribute.
+|_not set_
+|Any number of #builtin-attributes,built-in# or user-defined attributes in one of the following formats:
+
+Hash: +
+`{'name'\=>'value'}` +
+Array: +
+`['name=value']` +
+String: +
+`'name=value'`
+|`-a`, `--attributes`
+
+|:backend
+|Selects the converter to use (as registered with this keyword).
+|html5
+|html5, docbook5, manpage, or any backend registered through an active converter
+|`-b`, `--backend`
+
+|:base_dir
+|Sets the base (aka working) directory containing the document and resources.
+|The directory of the source file, or the working directory if the source is read from a stream.
+|file path
+|`-B`, `--base-dir`
+
+|:catalog_assets
+|If true, tells the parser to capture images and links in the reference table.
+(Normally only IDs, footnotes and indexterms are included).
+The reference table is available via the `references` property on the `document` AST object.
+//NOTE: This is still a primitive and experimental feature.
+//It is intended for early adopters to address special use cases.
+_(Experimental)._
+|false
+|_boolean_
+|_n/a_
+
+|:converter
+|Specifies a user-supplied `Asciidoctor::Converter` instance, used in place of the converter that is automatically resolved from the backend value.
+|_not set_
+|`Asciidoctor::Converter` instance
+|_n/a_
+_(Can be emulated using a combination of `-r` and `-b`)._
+
+|:doctype
+|Sets the document type.
+|article
+|article, book, manpage, inline
+|`-d`, `--doctype`
+
+|:eruby
+|Specifies the eRuby implementation to use for executing the converter templates written in ERB.
+|erb
+|erb, erubis
+|`-e`, `--eruby`
+
+|:extensions
+|A Ruby block that registers (and possibly defines) xref:extensions:register.adoc[Asciidoctor extensions] for this instance of the processor.
+|_not set_
+|A Ruby block that conforms to the Asciidoctor extensions API (the same code that would be passed to the `Extensions.register` method).
+|_n/a_
+_(Can be emulated using `-r`)._
+
+|:extensions_registry
+|Overrides the xref:extensions:register.adoc[extensions registry] instance.
+Instead of providing a Ruby block containing extensions to register, this option lets you replace the extension registry itself, giving you complete control over how extensions are registered for this processor.
+|_not set_
+|`Extensions::Registry` instance
+|_n/a_
+
+|:header_footer
+|If true, add the document header and footer (i.e., framing) around the body content in the output.
+NOTE: The default value for this option is opposite of the default value for the CLI.
+|false
+|_boolean_
+|`-s`, `--no-header-footer`
+
+|:mkdirs
+|If true, the processor will create the necessary output directories if they don't yet exist.
+|false
+|_boolean_
+|_n/a_
+_(Implicitly enabled)._
+
+|:parse
+|If true, the source is parsed eagerly (i.e., as soon as the source is passed to the `load` or `load_file` API).
+If false, parsing is deferred until the `parse` method is explicitly invoked.
+|true
+|_boolean_
+|_n/a_
+
+|:safe
+|Sets the xref:ROOT:safe-modes.adoc[safe mode].
+|:secure
+|:unsafe, :safe, :server, :secure
+|`-S`, `--safe-mode`
+
+|:sourcemap
+|Keeps track of the file and line number for each parsed block.
+(Useful for tooling applications where the association between the converted output and the source file is important).
+|false
+|_boolean_
+|_n/a_
+
+|:template_cache
+|If true, enables the built-in cache used by the template converter when reading the source of template files.
+Only relevant if the `:template_dirs` option is specified.
+|true
+|_boolean_
+|_n/a_
+
+|:template_dir
+|Specifies a directory of Tilt-compatible templates to be used instead of the default built-in templates.
+*Deprecated. Please use `:template_dirs` instead.*
+|_not set_
+|file path
+|`-T`, `--template-dir`
+
+|:template_dirs
+|An array of directories containing Tilt-compatible converter templates to be used instead of the default built-in templates.
+|_not set_
+|An array of file paths
+|`-T`, `--template-dir`
+
+|:template_engine
+|Template engine to use for the custom converter templates.
+The gem with the same name as the engine will be loaded automatically.
+This name is also used to build the full path to the custom converter templates.
+|_auto_ +
+(Set based on the file extension of the custom converter templates found).
+|Template engine name (e.g., slim, haml, erb, etc.)
+|`-E`, `--template-engine`
+
+|:template_engine_options
+|Low-level options passed directly to the template engine.
+//(You can see an example in the Bespoke.js converter at https://github.com/asciidoctor/asciidoctor-bespoke/blob/v1.0.0.alpha.1/lib/asciidoctor-bespoke/converter.rb#L24-L28).
+|_not set_
+|A nested Hash of options with the template engine name as the top-level key and the option name as the second-level key.
+|_n/a_
+
+|:timings
+|Capture time taken to read, parse, and convert document.
+*Internal use only.*
+|_not set_
+|`Asciidoctor::Timings` instance
+|`-t`, `--timings`
+
+|:to_file
+|The name of the output file to write, or true to use the default output file (`docname` + `outfilesuffix`).
+|_not set_
+|true, file path
+|`-o`, `--out-file`
+
+|:to_dir
+|Destination directory for output file(s), relative to `base_dir`.
+|The directory containing the source file, or the working directory if the source is read from a stream.
+|file path
+|`-D`, `--destination-dir`
+|===
diff --git a/docs/modules/api/pages/set-safe-mode.adoc b/docs/modules/api/pages/set-safe-mode.adoc
new file mode 100644
index 00000000..dcf13af6
--- /dev/null
+++ b/docs/modules/api/pages/set-safe-mode.adoc
@@ -0,0 +1,18 @@
+= Set the Safe Mode Using the API
+:navtitle: Set Safe Mode
+
+The default xref:ROOT:safe-modes.adoc[safe mode] in the API is `SECURE`.
+You can change the safe mode using a string, symbol or integer value.
+The value must be set in the document constructor using the `:safe` option.
+
+ result = Asciidoctor.convert_file('master.adoc', :safe => 'server')
+
+or
+
+ result = Asciidoctor.convert_file('master.adoc', :safe => :server)
+
+or
+
+ result = Asciidoctor.convert_file('master.adoc', :safe => 10)
+
+You can also set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and xref:ROOT:attributes-and-safe-modes.adoc[manage attributes by safe mode].
diff --git a/docs/modules/cli/nav.adoc b/docs/modules/cli/nav.adoc
new file mode 100644
index 00000000..4e7bdbf9
--- /dev/null
+++ b/docs/modules/cli/nav.adoc
@@ -0,0 +1,6 @@
+* xref:index.adoc[]
+** xref:output-file.adoc[]
+** xref:process-multiple-files.adoc[]
+** xref:io-piping.adoc[]
+** xref:set-safe-mode.adoc[]
+** xref:options.adoc[]
diff --git a/docs/modules/cli/pages/index.adoc b/docs/modules/cli/pages/index.adoc
new file mode 100644
index 00000000..6451af8c
--- /dev/null
+++ b/docs/modules/cli/pages/index.adoc
@@ -0,0 +1,32 @@
+= Process AsciiDoc Using the CLI
+:url-manpage: https://github.com/asciidoctor/asciidoctor/blob/master/man/asciidoctor.adoc
+
+////
+command-line-usage.adoc
+Command line usage quick start for Asciidoctor
+included in the install-toolchain and user-manual documents
+////
+
+When the Asciidoctor gem is installed successfully, the Asciidoctor command line interface (CLI) will be available on your PATH.
+To confirm that Asciidoctor is available, execute:
+
+ $ asciidoctor --version
+
+The following information should be output in your terminal:
+
+[subs=attributes+]
+ Asciidoctor {release-version} [https://asciidoctor.org]
+
+To invoke Asciidoctor from the CLI and convert an `.adoc` file, execute:
+
+ $ asciidoctor <asciidoc-file>
+
+This will use the built-in defaults for options and create a new file in the same directory as the input file, with the same base name, but with the `.html` extension.
+
+The xref:options.adoc[] describes the available Asciidoctor CLI options and parameters.
+
+Full help is provided in the {url-manpage}[Asciidoctor man page^] or via:
+
+ $ asciidoctor --help
+
+//There is also an `asciidoctor-safe` command, which turns on safe mode by default, preventing access to files outside the parent directory of the source file.
diff --git a/docs/modules/cli/pages/io-piping.adoc b/docs/modules/cli/pages/io-piping.adoc
new file mode 100644
index 00000000..9b9eb5ce
--- /dev/null
+++ b/docs/modules/cli/pages/io-piping.adoc
@@ -0,0 +1,45 @@
+= Pipe Content Through the CLI
+
+In addition to converting files, the Asciidoctor CLI can read content from standard input (STDIN) and/or write content to standard output (STDOUT).
+This feature is called piping.
+
+Using the `-` flag, you can pipe content to the `asciidoctor` command.
+This flag tells Asciidoctor read the source from standard input (STDIN).
+For example:
+
+ $ echo 'content' | asciidoctor -
+
+NOTE: Any variation of STDIN will work.
+
+This command is effectively the same as:
+
+ $ echo 'content' | asciidoctor -o - -
+
+When reading source from STDIN, Asciidoctor doesn't have a reference to an input file.
+Therefore, it sends the converted text to standard output (STDOUT) by default.
+
+If, instead, you want to write the full document to an output file, you specify it using the `-o` flag.
+For example, the following command writes a standalone HTML document to [.path]_output.html_ instead of STDOUT:
+
+ $ echo 'content' | asciidoctor -o output.html -
+
+When you pipe content to the `asciidoctor` command, it no longer has a concept of where the document is located.
+Therefore, relative references such as includes may not work as expected.
+To resolve this problem, you should specify an absolute base directory using the `-B` option:
+
+ $ echo 'content' | asciidoctor -B /path/to/basedir -o output.html -
+
+Alternately, you can set an artificial document directory by passing an absolute path to the `docdir` attribute:
+
+ $ echo 'content' | asciidoctor -a docdir=/path/to/docdir -o output.html -
+
+Try both approaches to determine which one suits your needs better.
+
+When piping source from STDIN to STDOUT through the `asciidoctor` command, you often just want the converted body (i.e., embeddable HTML).
+To produce that variant, add the `-s` flag:
+
+ $ echo 'content' | asciidoctor -s -
+
+Or perhaps you want to include the doctitle as well:
+
+ $ echo -e '= Document Title\n\ncontent' | asciidoctor -s -a showtitle -
diff --git a/docs/modules/cli/pages/options.adoc b/docs/modules/cli/pages/options.adoc
new file mode 100644
index 00000000..4c4a2236
--- /dev/null
+++ b/docs/modules/cli/pages/options.adoc
@@ -0,0 +1,138 @@
+= CLI Options
+// um anchor: appendix#cli-options
+// DO NOT EDIT THIS FILE
+// Copy the content from asciidoctor/man/asciidoctor.adoc
+
+== Security Settings
+
+*-B, --base-dir*=_DIR_::
+  Base directory containing the document and resources.
+  Defaults to the directory containing the source file or, if the source is read from a stream, the working directory.
+  When combined with the safe mode setting, can be used to chroot the execution of the program.
+
+*-S, --safe-mode*=_SAFE_MODE_::
+  Set safe mode level: _unsafe_, _safe_, _server_, or _secure_.
+  Disables potentially dangerous macros in source files, such as `include::[]`.
+  If not set, the safe mode level defaults to _unsafe_ when Asciidoctor is invoked using this script.
+
+*--safe*::
+  Set safe mode level to _safe_.
+  Enables include directives, but prevents access to ancestor paths of source file.
+  Provided for compatibility with the asciidoc command.
+  If not set, the safe mode level defaults to _unsafe_ when Asciidoctor is invoked using this script.
+
+== Document Settings
+
+*-a, --attribute*=_ATTRIBUTE_::
+  Define, override, or unset a document attribute.
+  Command-line attributes take precedence over attributes defined in the source file unless either the name or value ends in _@_.
++
+_ATTRIBUTE_ is normally formatted as a key-value pair, in the form _NAME=VALUE_.
+Alternate forms are _NAME_ (where the _VALUE_ defaults to an empty string), _NAME!_ (unsets the _NAME_ attribute), and _NAME=VALUE@_ (or _NAME@=VALUE_) (where _VALUE_ does not override the _NAME_ attribute if it's already defined in the source document).
+Values containing spaces should be enclosed in quotes.
++
+This option may be specified more than once.
+
+*-b, --backend*=_BACKEND_::
+  Backend output file format: _html5_, _docbook5_, and _manpage_ are supported out of the box.
+  You can also use the backend alias names _html_ (aliased to _html5_) or _docbook_ (aliased to _docbook5_).
+  Other values can be passed, but if Asciidoctor cannot resolve the backend to a converter, it will fail.
+  Defaults to _html5_.
+
+*-d, --doctype*=_DOCTYPE_::
+  Document type: _article_, _book_, _manpage_, or _inline_.
+  Sets the root element when using the _docbook_ backend and the style class on the HTML body element when using the _html_ backend.
+  The _book_ document type allows multiple level-0 section titles in a single document.
+  The _manpage_ document type enables parsing of metadata necessary to produce a man page.
+  The _inline_ document type allows the content of a single paragraph to be formatted and returned without wrapping it in a containing element.
+  Defaults to _article_.
+
+== Document Conversion
+
+*-D, --destination-dir*=_DIR_::
+  Destination output directory.
+  Defaults to the directory containing the source file or, if the source is read from a stream, the working directory.
+  If specified, the directory is resolved relative to the working directory.
+
+*-E, --template-engine*=_NAME_::
+  Template engine to use for the custom converter templates.
+  The gem with the same name as the engine will be loaded automatically.
+  This name is also used to build the full path to the custom converter templates.
+  If a template engine is not specified, it will be auto-detected based on the file extension of the custom converter templates found.
+
+*-e, --eruby*::
+  Specifies the eRuby implementation to use for executing the custom converter templates written in ERB.
+  Supported values are _erb_ and _erubis_.
+  Defaults to _erb_.
+
+*-I, --load-path*=_DIRECTORY_::
+  Add the specified directory to the load path, so that _-r_ can load extensions from outside the default Ruby load path.
+  This option may be specified more than once.
+
+*-n, --section-numbers*::
+  Auto-number section titles.
+  Synonym for *--attribute sectnums*.
+
+*-o, --out-file*=_OUT_FILE_::
+  Write output to file _OUT_FILE_.
+  Defaults to the base name of the input file suffixed with _backend_ extension.
+  The file is resolved relative to the working directory.
+  If the input is read from standard input or a named pipe (fifo), then the output file defaults to stdout.
+  If _OUT_FILE_ is _-_, then the output file is written to standard output.
+
+*-R, --source-dir*=_DIR_::
+  Source directory.
+  Currently only used if the destination directory is also specified.
+  Used to preserve the directory structure of files converted within this directory in the destination directory.
+  If specified, the directory is resolved relative to the working directory.
+
+*-r, --require*=_LIBRARY_::
+  Require the specified library before executing the processor, using the standard Ruby require.
+  This option may be specified more than once.
+
+*-s, --no-header-footer*::
+  Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document.
+  This option is useful for producing documents that can be inserted into an external template.
+
+*-T, --template-dir*=_DIR_::
+  A directory containing custom converter templates that override one or more templates from the built-in set.
+  (requires _tilt_ gem)
++
+If there is a subfolder that matches the engine name (if specified), that folder is appended to the template directory path.
+Similarly, if there is a subfolder in the resulting template directory that matches the name of the backend, that folder is appended to the template directory path.
++
+This option may be specified more than once.
+Matching templates found in subsequent directories override ones previously discovered.
+
+== Processing Information
+
+*--failure-level*=_LEVEL_::
+  The minimum logging level that triggers a non-zero exit code (failure).
+  If this option is not set (default: FATAL), the program exits with exit code zero even if warnings or errors have been logged.
+
+*-q, --quiet*::
+  Silence application log messages and script warnings.
+
+*--trace*::
+  Include backtrace information when reporting errors.
+
+*-v, --verbose*::
+  Verbosely print processing information to stderr, including debug-level log messages.
+
+*-w, --warnings*::
+  Turn on script warnings (applies to executed code).
+
+*-t, --timings*::
+  Print timings report to stderr (time to read, parse, and convert).
+
+== Program Information
+
+*-h, --help* [_TOPIC_]::
+  Print a help message.
+  Show the command usage if _TOPIC_ is not specified or recognized.
+  Dump the Asciidoctor man page (in troff/groff format) if _TOPIC_ is _manpage_.
+
+*-V, --version*::
+  Print program version number.
++
+*-v* can also be used if no source files are specified.
diff --git a/docs/modules/cli/pages/output-file.adoc b/docs/modules/cli/pages/output-file.adoc
new file mode 100644
index 00000000..5867a201
--- /dev/null
+++ b/docs/modules/cli/pages/output-file.adoc
@@ -0,0 +1,39 @@
+= Specify an Output File
+// Included in user-manual: Specifying an output file
+
+By default, the Asciidoctor CLI writes the converted output file to the same directory as the input file.
+If an output file is not specified, the name of the output file is derived from the input file by replacing its file extension with the file extension that matches the output format (e.g., replacing .adoc with .html).
+
+You can instruct the Asciidoctor CLI to write content to a different output file (or directory).
+There are several circumstances when you'll want to specify a different output file:
+
+* You want to write the output file to a different name, perhaps to append a qualifier such as a version string.
+* You want to write the output file to a different directory.
+* You are piping content to the CLI, but want to write the output to a file (in this case, an output file is required).
+
+CAUTION: If you specify the output file as a relative path, it will be resolved relative to the current working directory instead of the directory of the input file (i.e., specifying the output file implicitly sets the output directory too).
+
+To specify the output file, you'll use the `-o` option.
+For example, let's say we want to convert [.path]_mydoc.adoc_ and write the output to a filename that includes the current date.
+You'd use:
+
+ $ asciidoctor -o mydoc-$(date +%Y-%m-%d).html mydoc.adoc
+
+We could write it to another folder as well by prefixing the output file with a folder name:
+
+ $ asciidoctor -o build/mydoc-$(date +%Y-%m-%d).html mydoc.adoc
+
+If you only want to specify the output directory, but let the filename be defaulted, use the `-D` option:
+
+ $ asciidoctor -D build mydoc.adoc
+
+The `-D` option can also be used when processing multiple input files:
+
+ $ asciidoctor -D build *.adoc
+
+If you are piping content to the CLI, the default is to write the output to STDOUT.
+If you want to write the output to a file in this case, you have to specify one:
+
+ $ cat mydoc.adoc | asciidoctor -o build/mydoc-$(date +%Y-%m-%d).html -
+
+See xref:io-piping.adoc[] to learn more.
diff --git a/docs/modules/cli/pages/process-multiple-files.adoc b/docs/modules/cli/pages/process-multiple-files.adoc
new file mode 100644
index 00000000..0d565b77
--- /dev/null
+++ b/docs/modules/cli/pages/process-multiple-files.adoc
@@ -0,0 +1,48 @@
+= Process Multiple Source Files
+
+The Asciidoctor CLI can convert multiple files in a single invocation.
+If you pass multiple source filenames or a filename pattern to the CLI, Asciidoctor will convert each file in turn.
+
+Let's assume there exist two AsciiDoc files in the current directory, [.path]_a.adoc_ and [.path]_b.adoc_.
+You can pass both files to Asciidoctor using a single command, as follows:
+
+ $ asciidoctor a.adoc b.adoc
+
+Asciidoctor will convert both files, transforming [.path]_a.adoc_ to [.path]_a.html_ and [.path]_b.adoc_ to [.path]_b.html_.
+
+To save some typing, you can use the glob operator (`+*+`) to match all AsciiDoc files in the current directory using a single argument:
+
+ $ asciidoctor *.adoc
+
+Your shell will automatically expand the pattern and interpret the command exactly as you had typed it above:
+
+ $ asciidoctor a.adoc b.adoc
+
+You can pass all AsciiDoc files inside direct subfolders using the glob operator (`+*+`) in place of the directory name:
+
+ $ asciidoctor */*.adoc
+
+To match all files in the current directory and direct subfolders, combine both glob patterns:
+
+ $ asciidoctor *.adoc */*.adoc
+
+Since the globs in this command rely on shell expansion, the command is not portable across platforms.
+To make it portable, you can allow the Asciidoctor CLI to expand the globs.
+To do so, instruct the shell to not expand the glob by quoting the pattern, as shown here:
+
+ $ asciidoctor '*.adoc' '*/*.adoc'
+
+This time, the arguments `+*.adoc+` and `+*/*.adoc+` are passed directly to Asciidoctor instead of being expanded.
+Asciidoctor handles the glob matching in a manner that is portable across platforms.
+
+But it gets better.
+The glob handling in Asciidoctor (which matches the rules of file globbing in Ruby) is likely more powerful than what your shell offers.
+For example, you can match AsciiDoc files in the current folder and in folders of any depth using the double glob operator (`+**+`).
+
+ $ asciidoctor '**/*.adoc'
+
+Most shells do not honor this double glob pattern.
+
+In conclusion, when specifying a glob pattern, we always recommend enclosing the argument in quotes.
+
+CAUTION: To process multiple nested AsciiDoc files at once and apply a custom stylesheet, you'll need to xref:html-backend:apply-stylesheet.adoc#style-nested[manage the stylesheet's location].
diff --git a/docs/modules/cli/pages/set-safe-mode.adoc b/docs/modules/cli/pages/set-safe-mode.adoc
new file mode 100644
index 00000000..31110060
--- /dev/null
+++ b/docs/modules/cli/pages/set-safe-mode.adoc
@@ -0,0 +1,19 @@
+= Set the Safe Mode Using the CLI
+:navtitle: Set the Safe Mode
+
+When Asciidoctor is invoked via the CLI, the xref:ROOT:safe-modes.adoc[safe mode] is set to `UNSAFE` by default.
+You can change the security level by executing one of the following commands:
+
+`-S`, `--safe-mode=SAFE_MODE`::
+Sets the safe mode level of the document according to the assigned level (`UNSAFE`, `SAFE`, `SERVER`, `SECURE`).
+
+`--safe`, `asciidoctor-safe`::
+Sets the safe mode level to `SAFE`.
+Provided for compatibility with the python AsciiDoc `safe` command.
+
+////
+-B, --base-dir=DIR
+Base directory containing the document and resources. Defaults to the directory containing the source file, or the working directory if the source is read from a stream. Can be used as a way to chroot the execution of the program.
+////
+
+You can also set the xref:api:set-safe-mode.adoc[safe mode from the API] and xref:ROOT:attributes-and-safe-modes.adoc[manage attributes by safe mode].
diff --git a/docs/modules/docbook-backend/nav.adoc b/docs/modules/docbook-backend/nav.adoc
new file mode 100644
index 00000000..31f850ee
--- /dev/null
+++ b/docs/modules/docbook-backend/nav.adoc
@@ -0,0 +1 @@
+* xref:index.adoc[]
diff --git a/docs/modules/docbook-backend/pages/index.adoc b/docs/modules/docbook-backend/pages/index.adoc
new file mode 100644
index 00000000..c6ef9962
--- /dev/null
+++ b/docs/modules/docbook-backend/pages/index.adoc
@@ -0,0 +1,82 @@
+= Generate DocBook from AsciiDoc
+:navtitle: Generate DocBook
+:url-docbook45: https://github.com/asciidoctor/asciidoctor-docbook45
+:url-yelp: https://wiki.gnome.org/action/show/Apps/Yelp
+
+== DocBook 5.0 converter
+
+Asciidoctor can produce DocBook 5.0 XML output.
+There's a corresponding DocBook element for each AsciiDoc element.
+
+== Generate DocBook with the docbook converter
+
+To convert the [.path]_mysample.adoc_ document to DocBook 5.0 format, call the processor with the backend flag set to `docbook`.
+
+ $ asciidoctor -b docbook mysample.adoc
+
+A new XML document, named [.path]_mysample.xml_, will now be present in the current directory.
+
+ $ ls
+ mysample.adoc  mysample.html  mysample.xml
+
+Here's a snippet of the XML generated by the DocBook converter.
+
+.XML generated from AsciiDoc
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<article xmlns="http://docbook.org/ns/docbook"
+    xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
+  <info>
+    <title>Hello, AsciiDoc!</title>
+    <date>2018-09-03</date>
+    <author>
+      <personname>
+        <firstname>Doc</firstname>
+        <surname>Writer</surname>
+      </personname>
+      <email>doc@example.com</email>
+    </author>
+    <authorinitials>DW</authorinitials>
+  </info>
+  <simpara>
+    An introduction to <link xl:href="https://asciidoctor.org">Asciidoctor</link>.
+  </simpara>
+  <section xml:id="_first_section">
+    <title>First Section</title>
+    <itemizedlist>
+      <listitem>
+        <simpara>item 1</simpara>
+      </listitem>
+      <listitem>
+        <simpara>item 2</simpara>
+      </listitem>
+    </itemizedlist>
+  </section>
+</article>
+----
+
+On Linux, you can view the DocBook file with {url-yelp}[Yelp^].
+
+ $ yelp mysample.xml
+
+The DocBook converter produces output that is compliant to the DocBook 5.0 specification.
+
+A summary of the differences are as follows:
+
+* XSD declarations are used on the document root instead of a DTD
+* `<info>` elements for document info instead of `<articleinfo>` and `<bookinfo>`
+* elements that hold the author's name are wrapped in a `<personname>` element
+* the id for an element is defined using an `xml:id` attribute
+* `<link>` is used for links instead of `<ulink>`
+* the URL for a link is defined using the `xl:href` attribute
+
+If you're using the Asciidoctor API, you can generate a DocBook document directly from your application.
+
+.Generate DocBook output from the API
+[source,ruby]
+----
+Asciidoctor.convert_file 'mysample.adoc', backend: 'docbook'
+----
+
+If you need to output DocBook 4.5, you may find the community-supported {url-docbook45}[DocBook 4.5 Converter] useful.
diff --git a/docs/modules/extensions/nav.adoc b/docs/modules/extensions/nav.adoc
new file mode 100644
index 00000000..e209f801
--- /dev/null
+++ b/docs/modules/extensions/nav.adoc
@@ -0,0 +1,11 @@
+* xref:index.adoc[]
+** xref:register.adoc[]
+** xref:preprocessor.adoc[]
+** xref:tree-processor.adoc[]
+** xref:postprocessor.adoc[]
+** xref:docinfo-processor.adoc[]
+** xref:block-processor.adoc[]
+** xref:compound-block-processor.adoc[]
+** xref:block-macro-processor.adoc[]
+** xref:inline-macro-processor.adoc[]
+** xref:include-processor.adoc[]
diff --git a/docs/modules/extensions/pages/block-macro-processor.adoc b/docs/modules/extensions/pages/block-macro-processor.adoc
new file mode 100644
index 00000000..df451c43
--- /dev/null
+++ b/docs/modules/extensions/pages/block-macro-processor.adoc
@@ -0,0 +1,48 @@
+= Block Macro Processor Extension Example
+:navtitle: Block Macro Processor
+
+Purpose::
+Create a block macro named `gist` for embedding a gist.
+
+== sample-with-gist-macro.adoc
+
+```
+.My Gist
+gist::123456[]
+```
+
+== GistBlockMacro
+
+```ruby
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+class GistBlockMacro < Asciidoctor::Extensions::BlockMacroProcessor
+  use_dsl
+
+  named :gist
+
+  def process parent, target, attrs
+    title_html = (attrs.has_key? 'title') ?
+        %(<div class="title">#{attrs['title']}</div>\n) : nil
+
+    html = %(<div class="openblock gist">
+#{title_html}<div class="content">
+<script src="https://gist.github.com/#{target}.js"></script>
+</div>
+</div>)
+
+    create_pass_block parent, html, attrs, subs: nil
+  end
+end
+```
+
+== Usage
+
+```ruby
+Asciidoctor::Extensions.register do
+  block_macro GistBlockMacro if document.basebackend? 'html'
+end
+
+Asciidoctor.convert_file 'sample-with-gist.adoc', :safe => :safe
+```
diff --git a/docs/modules/extensions/pages/block-processor.adoc b/docs/modules/extensions/pages/block-processor.adoc
new file mode 100644
index 00000000..d228642e
--- /dev/null
+++ b/docs/modules/extensions/pages/block-processor.adoc
@@ -0,0 +1,45 @@
+= Block Processor Extension Example
+:navtitle: Block Processor
+
+Purpose::
+Register a custom block style named `shout` that uppercases all the words and converts periods to exclamation points.
+
+== sample-with-shout-block.adoc
+
+```
+[shout]
+The time is now. Get a move on.
+```
+
+== ShoutBlock
+
+```ruby
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+class ShoutBlock < Asciidoctor::Extensions::BlockProcessor
+  PeriodRx = /\.(?= |$)/
+
+  use_dsl
+
+  named :shout
+  on_context :paragraph
+  name_positional_attributes 'vol'
+  parse_content_as :simple
+
+  def process parent, reader, attrs
+    volume = ((attrs.delete 'vol') || 1).to_i
+    create_paragraph parent, (reader.lines.map {|l| l.upcase.gsub PeriodRx, '!' * volume }), attrs
+  end
+end
+```
+
+== Usage
+
+```ruby
+Asciidoctor::Extensions.register do
+  block ShoutBlock
+end
+
+Asciidoctor.convert_file 'sample-with-shout-block.adoc', :safe => :safe
+```
diff --git a/docs/modules/extensions/pages/compound-block-processor.adoc b/docs/modules/extensions/pages/compound-block-processor.adoc
new file mode 100644
index 00000000..32dea0e4
--- /dev/null
+++ b/docs/modules/extensions/pages/compound-block-processor.adoc
@@ -0,0 +1,56 @@
+= Compound Block Processor Example
+:navtitle: Compound Block Processor
+
+Purpose::
+Register a custom block named `collapsible` that transforms a listing block into a compound block composed of the following:
+
+* an example block with the collapsible option enabled
+* the original listing block
+* the listing block is promoted to a source block if a language is specified using the second positional attribute.
+
+.sample-with-collapsible-block.adoc
+[source]
+....
+.Show JSON
+[collapsible,json]
+----
+{
+   "foo": "bar"
+}
+----
+....
+
+.collapsible-block.rb
+[source,ruby]
+----
+class CollapsibleBlock < Asciidoctor::Extensions::BlockProcessor
+  enable_dsl
+  on_context :listing
+  positional_attributes 'language'
+
+  def process parent, reader, attrs
+    lang = attrs.delete 'language'
+    attrs['title'] ||= 'Show Listing'
+    example = create_example_block parent, [], attrs, content_model: :compound
+    example.set_option 'collapsible'
+    listing = create_listing_block example, reader.readlines, nil
+    if lang
+      listing.style = 'source'
+      listing.set_attr 'language', lang
+      listing.commit_subs
+    end
+    example << listing
+    example
+  end
+end
+
+Asciidoctor::Extensions.register do
+  block CollapsibleBlock, :collapsible
+end
+----
+
+.Usage
+ $ asciidoctor -r ./collapsible-block.rb sample-with-collapsible-block.adoc
+
+NOTE: This extension mimics the builtin `collapsible` option on the example block, but consolidates it to a single block.
+The purpose of this extension is to show how to assemble a compound block in an extension.
diff --git a/docs/modules/extensions/pages/docinfo-processor.adoc b/docs/modules/extensions/pages/docinfo-processor.adoc
new file mode 100644
index 00000000..d5510c1a
--- /dev/null
+++ b/docs/modules/extensions/pages/docinfo-processor.adoc
@@ -0,0 +1,36 @@
+= Docinfo Processor Extension Example
+:navtitle: Docinfo Processor
+
+Purpose::
+Appends the Google Analytics tracking code to the bottom of an HTML document.
+
+== GoogleAnalyticsDocinfoProcessor
+
+```ruby
+class GoogleAnalyticsDocinfoProcessor < Asciidoctor::Extensions::DocinfoProcessor
+  use_dsl
+  at_location :footer
+  def process document
+    return unless (ga_account_id = document.attr 'google-analytics-account')
+    %(<script>
+(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+ga('create','#{ga_account_id}','auto');
+ga('send','pageview');
+</script>)
+  end
+end
+```
+
+== Usage
+
+```ruby
+Asciidoctor::Extensions.register do
+  docinfo_processor GoogleAnalyticsDocinfoProcessor
+end
+
+Asciidoctor.convert_file 'sample.adoc', :safe => :safe,
+    :attributes => 'UA-ABCXYZ123'
+```
diff --git a/docs/modules/extensions/pages/include-processor.adoc b/docs/modules/extensions/pages/include-processor.adoc
new file mode 100644
index 00000000..8dbdd8e0
--- /dev/null
+++ b/docs/modules/extensions/pages/include-processor.adoc
@@ -0,0 +1,49 @@
+= Include Processor Extension Example
+:navtitle: Include Processor
+
+Purpose::
+Include a file from a URI.
+
+TIP: Asciidoctor supports including content from a URI out of the box if you set the `allow-uri-read` attribute (not available if the safe mode is `secure`).
+
+== sample-with-uri-include.adoc
+
+```
+:source-highlighter: coderay
+
+.Gemfile
+[source,ruby]
+----
+\include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/Gemfile[]
+----
+```
+
+== UriIncludeProcessor
+
+```ruby
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+require 'open-uri'
+
+class UriIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
+  def handles? target
+    (target.start_with? 'http://') or (target.start_with? 'https://')
+  end
+
+  def process doc, reader, target, attributes
+    content = (open target).readlines
+    reader.push_include content, target, target, 1, attributes
+    reader
+  end
+end
+```
+
+== Usage
+
+```ruby
+Asciidoctor::Extensions.register do
+  include_processor UriIncludeProcessor
+end
+
+Asciidoctor.convert_file 'sample-with-uri-include.adoc', :safe => :safe
+```
diff --git a/docs/modules/extensions/pages/index.adoc b/docs/modules/extensions/pages/index.adoc
new file mode 100644
index 00000000..33b35755
--- /dev/null
+++ b/docs/modules/extensions/pages/index.adoc
@@ -0,0 +1,51 @@
+= Extensions
+:url-exten-lab: https://github.com/asciidoctor/asciidoctor-extensions-lab
+
+Extensions are central to the success of AsciiDoc because they open up the language to new use cases.
+Asciidoctor provides an extension API that offers a superset of extension points.
+As a result, extensions in Asciidoctor are easy to write, powerful, and simple to distribute.
+
+Asciidoctor also allows extensions to be written using the full power of a programming language (whether it be Ruby, Java, Groovy or JavaScript).
+You don't have to shave yaks to get the functionality you want, and you can distribute the extension using defacto-standard packaging mechanisms like RubyGems or JARs.
+
+== Available extension points
+
+Asciidoctor provides the following extension points:
+
+Preprocessor::
+Processes the raw source lines before they are passed to the parser.
+See xref:preprocessor.adoc[].
+
+Tree processor::
+Processes the [.class]#Asciidoctor::Document# (AST) once parsing is complete.
+See xref:tree-processor.adoc[].
+
+Postprocessor::
+Processes the output after the document has been converted, but before it's written to disk.
+See xref:postprocessor.adoc[].
+
+Docinfo Processor::
+Adds additional content to the header or footer regions of the generated document.
+See xref:docinfo-processor.adoc[].
+
+Block processor::
+Processes a block of content marked with a custom block style (i.e., `[custom]`). (similar to an AsciiDoc filter)
+See xref:block-processor.adoc[].
+
+Compound block processor::
+Register a custom block named `collapsible` that transforms a listing block into a compound block.
+See xref:compound-block-processor.adoc[].
+
+Block macro processor::
+Registers a custom block macro and processes it (e.g., `gist::12345[]`).
+See xref:block-macro-processor.adoc[].
+
+Inline macro processor::
+Registers a custom inline macro and processes it (e.g., `btn:[Save]`).
+See xref:inline-macro-processor.adoc[].
+
+Include processor::
+Processes the `include::<filename>[]` directive.
+See xref:include-processor.adoc[].
+
+There are additional extension examples in the {url-exten-lab}[Asciidoctor extensions lab^].
diff --git a/docs/modules/extensions/pages/inline-macro-processor.adoc b/docs/modules/extensions/pages/inline-macro-processor.adoc
new file mode 100644
index 00000000..b8d88b0e
--- /dev/null
+++ b/docs/modules/extensions/pages/inline-macro-processor.adoc
@@ -0,0 +1,48 @@
+= Inline Macro Processor Extension Example
+:navtitle: Inline Macro Processor
+
+Purpose::
+Create an inline macro named `man` that links to a manpage.
+
+== sample-with-man-link.adoc
+
+```
+See man:gittutorial[7] to get started.
+```
+
+== ManpageInlineMacro
+
+```ruby
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+class ManInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+  use_dsl
+
+  named :man
+  name_positional_attributes 'volnum'
+
+  def process parent, target, attrs
+    text = manname = target
+    suffix = ''
+    target = %(#{manname}.html)
+    suffix = if (volnum = attrs['volnum'])
+      "(#{volnum})"
+    else
+      nil
+    end
+    parent.document.register :links, target
+    %(#{(create_anchor parent, text, type: :link, target: target).convert}#{suffix})
+  end
+end
+```
+
+== Usage
+
+```ruby
+Asciidoctor::Extensions.register do
+  inline_macro ManInlineMacro
+end
+
+Asciidoctor.convert_file 'sample-with-man-link.adoc', :safe => :safe
+```
diff --git a/docs/modules/extensions/pages/postprocessor.adoc b/docs/modules/extensions/pages/postprocessor.adoc
new file mode 100644
index 00000000..712706ea
--- /dev/null
+++ b/docs/modules/extensions/pages/postprocessor.adoc
@@ -0,0 +1,33 @@
+= Postprocessor Extension Example
+:navtitle: Postprocessor
+
+Purpose::
+Insert copyright text in the footer.
+
+== CopyrightFooterPostprocessor
+
+```ruby
+class CopyrightFooterPostprocessor < Asciidoctor::Extensions::Postprocessor
+  def process document, output
+    content = (document.attr 'copyright') || 'Copyright Acme, Inc.'
+    if document.basebackend? 'html'
+      replacement = %(<div id="footer-text">\\1<br>\n#{content}\n</div>)
+      output = output.sub(/<div id="footer-text">(.*?)<\/div>/m, replacement)
+    elsif document.basebackend? 'docbook'
+      replacement = %(<simpara>#{content}</simpara>\n\\1)
+      output = output.sub(/(<\/(?:article|book)>)/, replacement)
+    end
+    output
+  end
+end
+```
+
+== Usage
+
+```
+Asciidoctor::Extensions.register do
+  postprocessor CopyrightFooterPostprocessor
+end
+
+Asciidoctor.convert_file 'sample-with-copyright-footer.adoc', :safe => :safe
+```
diff --git a/docs/modules/extensions/pages/preprocessor.adoc b/docs/modules/extensions/pages/preprocessor.adoc
new file mode 100644
index 00000000..c1e5a406
--- /dev/null
+++ b/docs/modules/extensions/pages/preprocessor.adoc
@@ -0,0 +1,66 @@
+= Preprocessor Extension Example
+:navtitle: Preprocessor
+
+Purpose::
+Skim off front matter from the top of the document that gets used by site generators like Jekyll and Awestruct.
+
+== sample-with-front-matter.adoc
+
+```
+---
+tags: [announcement, website]
+---
+= Document Title
+
+content
+
+[subs="attributes,specialcharacters"]
+.Captured front matter
+....
+---
+{front-matter}
+---
+....
+```
+
+== FrontMatterPreprocessor
+
+```ruby
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+class FrontMatterPreprocessor < Asciidoctor::Extensions::Preprocessor
+  def process document, reader
+    lines = reader.lines # get raw lines
+    return reader if lines.empty?
+    front_matter = []
+    if lines.first.chomp == '---'
+      original_lines = lines.dup
+      lines.shift
+      while !lines.empty? && lines.first.chomp != '---'
+        front_matter << lines.shift
+      end
+
+      if (first = lines.first).nil? || first.chomp != '---'
+        lines = original_lines
+      else
+        lines.shift
+        document.attributes['front-matter'] = front_matter.join.chomp
+        # advance the reader by the number of lines taken
+        (front_matter.length + 2).times { reader.advance }
+      end
+    end
+    reader
+  end
+end
+```
+
+== Usage
+
+```ruby
+Asciidoctor::Extensions.register do
+  preprocessor FrontMatterPreprocessor
+end
+
+Asciidoctor.convert_file 'sample-with-front-matter.adoc', :safe => :safe
+```
diff --git a/docs/modules/extensions/pages/register.adoc b/docs/modules/extensions/pages/register.adoc
new file mode 100644
index 00000000..7e076ba1
--- /dev/null
+++ b/docs/modules/extensions/pages/register.adoc
@@ -0,0 +1,25 @@
+= Register Extensions
+
+== Register one or more extensions
+
+These extensions are registered per document using a callback that feels like a DSL:
+
+```ruby
+Asciidoctor::Extensions.register do |document|
+  preprocessor FrontMatterPreprocessor
+  tree_processor ShellSessionTreeProcessor
+  postprocessor CopyrightFooterPostprocessor
+  docinfo_processor TrackingCodeDocinfoProcessor if document.basebackend? 'html'
+  block ShoutBlock
+  block_macro GistBlockMacro if document.basebackend? 'html'
+  inline_macro ManInlineMacro
+  include_processor UriIncludeProcessor
+end
+```
+
+CAUTION: Extension classes must be defined outside of the register block.
+Once an extension class is registered, it is frozen, preventing further modification.
+If you define an extension class inside the register block, it will result in an error on subsequent invocations.
+
+You can register more than one processor of each type, though you can only have one processor per custom block or macro.
+Each registered class is instantiated when the [.class]#Asciidoctor::Document# is created.
diff --git a/docs/modules/extensions/pages/tree-processor.adoc b/docs/modules/extensions/pages/tree-processor.adoc
new file mode 100644
index 00000000..050737ed
--- /dev/null
+++ b/docs/modules/extensions/pages/tree-processor.adoc
@@ -0,0 +1,83 @@
+= Tree Processor Extension Example
+:navtitle: Tree Processor
+
+Purpose::
+Detect literal blocks that contain shell commands, strip the prompt character and style the command using CSS in such a way that the prompt character cannot be selected (as seen on help.github.com).
+
+== sample-with-shell-session.adoc
+
+```
+ $ echo "Hello, World!"
+ > Hello, World!
+
+ $ gem install asciidoctor
+```
+
+== ShellSessionTreeProcessor
+
+```ruby
+class ShellSessionTreeProcessor < Asciidoctor::Extensions::TreeProcessor
+  def process document
+    return unless document.blocks?
+    process_blocks document
+    nil
+  end
+
+  def process_blocks node
+    node.blocks.each_with_index do |block, i|
+      if block.context == :literal &&
+          (((first_line = block.lines.first).start_with? '$ ') ||
+            (first_line.start_with? '> '))
+        node.blocks[i] = convert_to_terminal_listing block
+      else
+        process_blocks block if block.blocks?
+      end
+    end
+  end
+
+  def convert_to_terminal_listing block
+    attrs = block.attributes
+    attrs['role'] = 'terminal'
+    prompt_attr = (attrs.has_key? 'prompt') ?
+        %( data-prompt="#{block.sub_specialchars attrs['prompt']}") : nil
+    lines = block.lines.map do |line|
+      line = block.sub_specialchars line.chomp
+      if line.start_with? '$ '
+        %(<span class="command"#{prompt_attr}>#{line[2..-1]}</span>)
+      elsif line.start_with? '&gt; '
+        %(<span class="output">#{line[5..-1]}</span>)
+      else
+        line
+      end
+    end
+    create_listing_block block.document, lines * EOL, attrs, subs: nil
+  end
+end
+```
+
+== Usage
+
+```ruby
+Asciidoctor::Extensions.register do
+  tree_processor ShellSessionTreeProcessor
+end
+
+Asciidoctor.convert_file 'sample-with-shell-session.adoc', :safe => :safe
+```
+
+////
+In the example below the TreeProcessor examines the block contents looking for the `// (*)` suffix and rewrites the line so that Asciidoctor formats it appropriately.
+
+[source,java]
+----
+protected void configure(HttpSecurity http) throws Exception {
+    http
+        .authorizeRequests()
+            .antMatchers("/resources/**").permitAll() // (*)
+            .anyRequest().authenticated()
+            .and()
+        .formLogin()
+            .loginPage("/login")
+            .permitAll();
+----
+////
diff --git a/docs/modules/get-started/nav.adoc b/docs/modules/get-started/nav.adoc
new file mode 100644
index 00000000..31f850ee
--- /dev/null
+++ b/docs/modules/get-started/nav.adoc
@@ -0,0 +1 @@
+* xref:index.adoc[]
diff --git a/docs/modules/get-started/pages/index.adoc b/docs/modules/get-started/pages/index.adoc
new file mode 100644
index 00000000..89b0bee1
--- /dev/null
+++ b/docs/modules/get-started/pages/index.adoc
@@ -0,0 +1,50 @@
+= Convert Your First AsciiDoc File
+:navtitle: Convert Your First File
+
+Assumptions:
+
+- [x] You've installed Asciidoctor.
+- [x] You've confirmed that the Asciidoctor command line interface (CLI) is available on your PATH.
+
+On this page, you'll learn how to run Asciidoctor on an AsciiDoc document and convert it to HTML.
+
+== Generate HTML using the default converter
+
+Let's generate HTML 5 using Asciidoctor's default converter and stylesheet from an AsciiDoc document.
+If you want to follow along with the examples, #download the _my-sample.adoc_ file# or use your own AsciiDoc document.
+
+. Open a terminal and switch (`cd`) into the directory where your AsciiDoc document is saved.
+
+ $ cd directory-name
+
+. Call Asciidoctor with the `asciidoctor` command, followed by file name of the AsciiDoc document.
+Since HTML 5 is Asciidoctor's default output, we don't need to specify a converter.
++
+--
+ $ asciidoctor my-sample.adoc
+
+As long as the document didn't contain any syntax errors, you won't see any messages printed to your terminal.
+--
+
+. Type `ls` to list the files in the directory.
++
+--
+ $ ls
+ my-sample.adoc  my-sample.html
+
+You should see a new file named [.path]_my-sample.html_.
+Asciidoctor derives the name of the output file from the name of the input document.
+--
+
+. Open [.path]_my-sample.html_ in your web browser.
+The converted document should look like the example below.
++
+====
+#fix ex#
+//image::mysample.png[]
+====
++
+The document's text, titles, and link is styled by the default Asciidoctor stylesheet, which is embedded in the HTML output.
+As a result, you could save [.path]_my-sample.html_ to any computer and it will look the same.
+
+TIP: Most of the examples in the general documentation use the CLI, but there are usually corresponding API examples under Working with the API.
diff --git a/docs/modules/html-backend/examples/mysample-data-uri.adoc b/docs/modules/html-backend/examples/mysample-data-uri.adoc
new file mode 100644
index 00000000..ec32d03e
--- /dev/null
+++ b/docs/modules/html-backend/examples/mysample-data-uri.adoc
@@ -0,0 +1,17 @@
+= My First Experience with the Dangers of Documentation
+:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger
+:imagesdir: myimages
+:data-uri:
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+[.left.text-center]
+image::wolpertinger.jpg[Wolpertinger]
+
+You may not be familiar with these {url-wolpertinger}[ravenous beasts],
+but, trust me, they'll eat your shorts and suck the loops from your code.
diff --git a/docs/modules/html-backend/examples/mysample-link.adoc b/docs/modules/html-backend/examples/mysample-link.adoc
new file mode 100644
index 00000000..e24aeea9
--- /dev/null
+++ b/docs/modules/html-backend/examples/mysample-link.adoc
@@ -0,0 +1,13 @@
+= My First Experience with the Dangers of Documentation
+:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger
+:linkcss:
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+You may not be familiar with these {url-wolpertinger}[ravenous beasts],
+but, trust me, they'll eat your shorts and suck the loops from your code.
diff --git a/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc b/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc
new file mode 100644
index 00000000..bb56b9e2
--- /dev/null
+++ b/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc
@@ -0,0 +1,15 @@
+= My First Experience with the Dangers of Documentation
+:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger
+:stylesdir: mystylesheets/
+:stylesheet: mystyles.css
+:linkcss:
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+You may not be familiar with these {url-wolpertinger}[ravenous beasts],
+but, trust me, they'll eat your shorts and suck the loops from your code.
diff --git a/docs/modules/html-backend/examples/mysample-stylesdir.adoc b/docs/modules/html-backend/examples/mysample-stylesdir.adoc
new file mode 100644
index 00000000..452e7f5c
--- /dev/null
+++ b/docs/modules/html-backend/examples/mysample-stylesdir.adoc
@@ -0,0 +1,14 @@
+= My First Experience with the Dangers of Documentation
+:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger
+:stylesdir: mystylesheets/
+:stylesheet: mystyles.css
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+You may not be familiar with these {url-wolpertinger}[ravenous beasts],
+but, trust me, they'll eat your shorts and suck the loops from your code.
diff --git a/docs/modules/html-backend/examples/mysample-stylesheet.adoc b/docs/modules/html-backend/examples/mysample-stylesheet.adoc
new file mode 100644
index 00000000..b1cc475c
--- /dev/null
+++ b/docs/modules/html-backend/examples/mysample-stylesheet.adoc
@@ -0,0 +1,13 @@
+= My First Experience with the Dangers of Documentation
+:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger
+:stylesheet: mystyles.css
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+You may not be familiar with these {url-wolpertinger}[ravenous beasts],
+but, trust me, they'll eat your shorts and suck the loops from your code.
diff --git a/docs/modules/html-backend/examples/mysample.adoc b/docs/modules/html-backend/examples/mysample.adoc
new file mode 100644
index 00000000..0a00ca64
--- /dev/null
+++ b/docs/modules/html-backend/examples/mysample.adoc
@@ -0,0 +1,12 @@
+= My First Experience with the Dangers of Documentation
+:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+You may not be familiar with these {url-wolpertinger}[ravenous beasts],
+but, trust me, they'll eat your shorts and suck the loops from your code.
diff --git a/docs/modules/html-backend/examples/wrap.adoc b/docs/modules/html-backend/examples/wrap.adoc
new file mode 100644
index 00000000..3f877d7d
--- /dev/null
+++ b/docs/modules/html-backend/examples/wrap.adoc
@@ -0,0 +1,17 @@
+// tag::nowrap[]
+[source%nowrap,java]
+----
+public class ApplicationConfigurationProvider extends HttpConfigurationProvider
+{
+   @Override
+   public Configuration getConfiguration(ServletContext context)
+   {
+      return ConfigurationBuilder.begin()
+               .addRule()
+               .when(Direction.isInbound().and(Path.matches("/{path}")))
+               .perform(Log.message(Level.INFO, "Client requested path: {path}"))
+               .where("path").matches(".*");
+   }
+}
+----
+// end::nowrap[]
diff --git a/docs/modules/html-backend/nav.adoc b/docs/modules/html-backend/nav.adoc
new file mode 100644
index 00000000..aa1054cb
--- /dev/null
+++ b/docs/modules/html-backend/nav.adoc
@@ -0,0 +1,9 @@
+* xref:index.adoc[]
+** xref:manage-stylesheets.adoc[]
+** xref:apply-code-stylesheets.adoc[]
+** xref:apply-stylesheet.adoc[]
+** xref:favicon.adoc[]
+** xref:manage-images.adoc[]
+** xref:favicon.adoc[]
+** xref:verbatim-line-wrap.adoc[]
+** xref:skip-front-matter.adoc[]
diff --git a/docs/modules/html-backend/pages/apply-code-stylesheets.adoc b/docs/modules/html-backend/pages/apply-code-stylesheets.adoc
new file mode 100644
index 00000000..42be39cb
--- /dev/null
+++ b/docs/modules/html-backend/pages/apply-code-stylesheets.adoc
@@ -0,0 +1,27 @@
+= Apply CodeRay or Pygments Stylesheets
+// um anchor: hl-css
+// html-code-styles.adoc, included in convert-documents and the user-manual.
+
+Asciidoctor can embed the stylesheet for the CodeRay or Pygments syntax highlighters.
+
+== Requirements
+
+First, make sure the appropriate library is installed on your system.
+See xref:integrations:rouge.adoc[], xref:integrations:coderay.adoc[], or xref:integrations:pygments.adoc[] for installation instructions.
+Next, set the xref:asciidoc:verbatim:source-highlighter.adoc[source-highlighter attribute] and assign it the value that corresponds to the library you installed.
+
+[#coderay]
+== CodeRay
+
+If the `source-highlighter` attribute is `coderay` and the `coderay-css` attribute is `class`, the CodeRay stylesheet is:
+
+* _embedded_ by default
+* _copied_ to the file [.path]_asciidoctor-coderay.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set
+
+[#pygments]
+== Pygments
+
+If the `source-highlighter` attribute is `pygments` and the `pygments-css` attribute is `class`, the Pygments stylesheet is:
+
+* _embedded_ by default
+* _copied_ to the file [.path]_asciidoctor-pygments.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set
diff --git a/docs/modules/html-backend/pages/apply-stylesheet.adoc b/docs/modules/html-backend/pages/apply-stylesheet.adoc
new file mode 100644
index 00000000..e645e664
--- /dev/null
+++ b/docs/modules/html-backend/pages/apply-stylesheet.adoc
@@ -0,0 +1,97 @@
+= Apply a Custom Stylesheet
+////
+apply-theme.adoc, included in:
+- user-manual
+- produce-custom-themes-using-asciidoctor-stylesheet-factory
+////
+
+A custom stylesheet can be stored in the same directory as your document or in a separate directory.
+Like the default stylesheet, you can have the output document link to your custom stylesheet or embed it.
+
+If the stylesheet is in the same directory as your document, you can apply it when converting your document to HTML from the CLI.
+
+ $ asciidoctor -a stylesheet=my-styles.css my-sample.adoc
+
+. Save your custom stylesheet in the same directory as [.path]_my-sample.adoc_
+. Call the `asciidoctor` processor
+. Set `-a` (`--attribute`) and `stylesheet`
+. Assign the stylesheet file's name to the `stylesheet` attribute
+. Enter your document file's name.
+
+Alternatively, let's set the `stylesheet` attribute in the header of [.path]_my-sample.adoc_.
+
+[source,asciidoc]
+----
+include::example$mysample-stylesheet.adoc[]
+----
+
+====
+#fix ex#
+//image::mysample-stylesheet.png[]
+====
+
+When your document and the stylesheet are stored in different directories, you need to tell Asciidoctor where to look for the stylesheet in relation to your document.
+Asciidoctor uses the relative or absolute path you assign to the `stylesdir` attribute to find the stylesheet.
+Let's move [.path]_my-styles.css_ into [.path]_my-documents/my-stylesheets_.
+Our AsciiDoc document, [.path]_my-sample.adoc_, is saved in the [.path]_my-documents_ directory.
+
+[source,asciidoc]
+----
+include::example$mysample-stylesdir.adoc[]
+----
+
+After processing [.path]_my-sample.adoc_, its HTML output ([.path]_my-sample.html_), which includes the embedded [.path]_my-styles.css_ stylesheet, is created in the [.path]_my-documents_ directory.
+
+====
+#fix ex#
+//image::mysample-stylesdir-dir.png[]
+====
+
+You can also set `stylesdir` in the CLI.
+
+ $ asciidoctor -a stylesdir=my-stylesheets/ -a stylesheet=my-styles.css my-sample.adoc
+
+If you don't want to embed the [.path]_my-styles.css_ stylesheet into your HTML output, make sure to set `linkcss`.
+
+[source,asciidoc]
+----
+include::example$mysample-stylesdir-link.adoc[]
+----
+
+After your document is converted, notice that a copy of [.path]_my-styles.css_ was not created in the [.path]_my-documents_ directory.
+Unlike when you link to the default Asciidoctor stylesheet, any custom stylesheets you link to are not copied to the directory where your output is saved.
+
+[#style-nested]
+.Stylesheets and processing multiple nested documents
+****
+When you are xref:cli:process-multiple-files.adoc[running Asciidoctor once across a nested set of documents], it's currently not possible to specify a single relative path for the `stylesdir` attribute that would work for all of the documents.
+This is because the relative depth of the stylesheet's location differs for the documents in the subdirectories.
+One way to solve this problem is to maintain the path to `stylesdir` in each document.
+
+Let's say you have three AsciiDoc documents saved in the following directory structure:
+
+....
+/my-documents
+  a.adoc
+  b.adoc
+  /my-nested-documents
+    c.adoc
+  /my-stylesheets
+....
+
+For [.path]_a.adoc_ and [.path]_b.adoc_, set `stylesdir` to:
+
+[source,asciidoc]
+----
+:stylesdir: my-stylesheets
+----
+
+For [.path]_c.adoc_, set `stylesdir` to:
+
+[source,asciidoc]
+----
+:stylesdir: ../my-stylesheets
+----
+
+If you're serving your documents from a webserver, you can solve this problem by providing an absolute path to the stylesheet.
+****
diff --git a/docs/modules/html-backend/pages/favicon.adoc b/docs/modules/html-backend/pages/favicon.adoc
new file mode 100644
index 00000000..34a8f15d
--- /dev/null
+++ b/docs/modules/html-backend/pages/favicon.adoc
@@ -0,0 +1,48 @@
+= Add a Favicon
+
+When using Asciidoctor to generate a standalone HTML document (i.e., the `header_footer` option is `true`), you can instruct the processor to include a link to a favicon by setting the favicon attribute in the document header.
+
+[source,asciidoc]
+----
+= Document Title
+:favicon:
+----
+
+By default, the processor will add a link reference of type "icon" that refers to a file named _favicon.ico_ (relative to the HTML document):
+
+[source,html]
+----
+<link rel="icon" type="image/x-icon" href="favicon.ico">
+----
+
+This reference gets added inside the HTML `<head>` tag (which explains why this feature is not available when generating an embeddable HTML document).
+
+To modify the name or location of the icon file, simply assign a value to the favicon attribute:
+
+[source,asciidoc]
+----
+= Document Title
+:favicon: ./images/favicon/favicon.png
+----
+
+This will now produce the following HTML tag:
+
+[source,html]
+----
+<link rel="icon" type="image/png" href="./images/favicon/favicon.png">
+----
+
+Notice the mimetype is automatically set based on the file extension of the image.
+
+The value of the `iconsdir` attribute is not prepend to the favicon path as it is with icons in the content.
+If you want this directory to be included in the favicon path, you must reference it explicitly:
+
+[source,asciidoc]
+----
+:favicon: {iconsdir}/favicon.png
+----
+
+TIP: If you're converting a set of AsciiDoc files in multiple directories for the purpose of making a website, and the favicon is located in a shared location, you'll likely want to use a forward slash (`/`) at the beginning of the favicon path.
+
+If you're looking for more control over how the favicon is declared, you should use a xref:ROOT:docinfo.adoc#head[head docinfo file].
+Keep in mind that if you add an icon link in a head docinfo file and also set the favicon attribute, you'll end up with two icon links in the generated HTML document.
diff --git a/docs/modules/html-backend/pages/index.adoc b/docs/modules/html-backend/pages/index.adoc
new file mode 100644
index 00000000..5c562bdb
--- /dev/null
+++ b/docs/modules/html-backend/pages/index.adoc
@@ -0,0 +1,81 @@
+= Generate HTML from AsciiDoc
+:navtitle: Generate HTML
+
+== HTML 5 converter
+
+Asciidoctor's default output format is HTML.
+
+`html5`:: HTML 5 markup styled with CSS3.
+
+== Generate HTML using the html5 converter
+
+In this section, we'll create a sample document, then process and convert it with Asciidoctor's `html5` converter.
+
+. Create an AsciiDoc file like the one below
+. Save the file as [.path]_my-sample.adoc_
+
+[source,asciidoc]
+----
+include::example$mysample.adoc[]
+----
+
+To convert [.path]_my-sample.adoc_ to HTML from the command line:
+
+. Open a console
+. Switch to the directory that contains the [.path]_my-sample.adoc_ document
+. Call the Asciidoctor processor with the `asciidoctor` command, followed by the name of the document you want to convert
+
+//^
+
+ $ asciidoctor my-sample.adoc
+
+Remember, Asciidoctor's default converter is html5, so it isn't necessary to specify it with the `-b` command.
+
+You won't see any messages printed to the console.
+If you type `ls` or view the directory in a file manager, there is a new file named [.path]_my-sample.html_.
+
+ $ ls
+ my-sample.adoc  my-sample.html
+
+Asciidoctor derives the name of the output document from the name of the input document.
+
+Open [.path]_my-sample.html_ in your web browser.
+Your document should look like the image below.
+
+====
+#fix ex#
+//image::mysample.png[]
+====
+
+The document's text, titles, and link is styled by the default Asciidoctor stylesheet, which is embedded in the HTML output.
+As a result, you could save [.path]_my-sample.html_ to any computer and it will look the same.
+
+[#xhtml]
+== Generate XHTML
+
+To convert AsciiDoc to XHTML, set the backend to `xhtml5`.
+
+.Produce XHTML using the built-in HTML converter
+[source,console]
+----
+asciidoctor -b xhtml5 document.adoc
+----
+
+To produce XHTML instead of HTML when using converter templates, set the `htmlsyntax` attribute to `xml` in addition to the backend option:
+
+.Produce XHTML using custom templates
+[source,console]
+----
+asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml document.adoc
+----
+
+.Black Box Decoded: XHTML and htmlsyntax
+****
+XHTML output is a special mode of the built-in HTML5 converter.
+It is activated by prefixing the backend value with `x` (e.g., `xhtml` or `xhtml5`).
+This hint implicitly assigns the `htmlsyntax` attribute to the value `xml`, which normally has the value `html`.
+
+For all other converters, the `htmlsyntax` attribute is not set explicitly.
+If you want a converter template that's written in Slim or Haml to output XHTML instead of the default HTML, you simply need to set the `htmlsyntax` attribute to `xml` explicitly.
+Asciidoctor will pass on this preference to the Slim or Haml template engine by setting the `:format` option to `:html5`.
+****
diff --git a/docs/modules/html-backend/pages/manage-images.adoc b/docs/modules/html-backend/pages/manage-images.adoc
new file mode 100644
index 00000000..38b69aae
--- /dev/null
+++ b/docs/modules/html-backend/pages/manage-images.adoc
@@ -0,0 +1,24 @@
+= Manage Images
+
+Images are not embedded in the HTML output by default.
+If you have image references in your document, you'll have to save the image files in the same directory as your converted document.
+
+As an alternative, you can embed the images directly into the document by setting the `data-uri` document attribute.
+
+ $ asciidoctor -a data-uri my-sample.adoc
+
+[source,asciidoc]
+----
+include::example$mysample-data-uri.adoc[]
+----
+
+====
+#fix ex#
+//image::mysample-data-uri.png[]
+====
+
+If the target of one or more images in the document is a URI, you must also set the `allow-uri-read` attribute securely and run Asciidoctor in `SECURE` mode or less.
+
+ $ asciidoctor -a data-uri -a allow-uri-read my-sample.adoc
+
+The same is true when converting the document to PDF using Asciidoctor PDF, even if the `allow-uri-read` attribute is not set (since the behavior is implied).
diff --git a/docs/modules/html-backend/pages/manage-stylesheets.adoc b/docs/modules/html-backend/pages/manage-stylesheets.adoc
new file mode 100644
index 00000000..aa6042b3
--- /dev/null
+++ b/docs/modules/html-backend/pages/manage-stylesheets.adoc
@@ -0,0 +1,46 @@
+= Manage Stylesheets
+
+== What is the default stylesheet?
+
+Asciidoctor comes bundled with a stylesheet, named [.path]_asciidoctor.css_.
+It uses this stylesheet for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes.
+This stylesheet is applied by default unless you tell Asciidoctor to use another stylesheet.
+See xref:html-backend:apply-stylesheet.adoc[] to learn about the default and custom stylesheet options.
+
+== Embed a stylesheet
+
+When you generate a document with the `html5` backend, the [.path]_asciidoctor.css_ stylesheet is embedded into the HTML output by default when the safe mode is less than `SECURE`.
+If your stylesheet is being linked to when you expect it to be embedded, lower the safe mode (`safe` is the recommend value).
+
+== Link to a stylesheet
+
+You can link to the stylesheet instead of embedding it.
+This is the mandatory behavior when the safe mode is `SECURE`.
+
+To have your document link to the stylesheet, set the `linkcss` attribute in the document's header.
+
+[source,asciidoc]
+----
+include::example$mysample-link.adoc[]
+----
+
+You can also set `linkcss` with the CLI.
+
+ $ asciidoctor -a linkcss my-sample.adoc
+
+Now, when you view the directory, you should see the file [.path]_asciidoctor.css_ in addition to [.path]_my-sample.adoc_ and [.path]_my-sample.html_.
+The `linkcss` attribute automatically copies [.path]_asciidoctor.css_ to the output directory.
+Additionally, you can inspect [.path]_my-sample.html_ in your browser and see `<link rel="stylesheet" href="./asciidoctor.css">` inside the `<head>` tags.
+
+====
+#fix ex#
+//image::mysample-link.png[]
+====
+
+== Don't apply a stylesheet
+
+If you don't want any styles applied to the HTML output of your document, unset the `stylesheet` attribute.
+
+ $ asciidoctor -a stylesheet! my-sample.adoc
+
+One of Asciidoctor's strengths is the ease in which you can swap the default stylesheet for your own xref:apply-stylesheet.adoc[custom stylesheet].
diff --git a/docs/modules/html-backend/pages/skip-front-matter.adoc b/docs/modules/html-backend/pages/skip-front-matter.adoc
new file mode 100644
index 00000000..0eb065d5
--- /dev/null
+++ b/docs/modules/html-backend/pages/skip-front-matter.adoc
@@ -0,0 +1,30 @@
+= Skip Front Matter
+
+== Front matter for static site generators
+
+Many static site generators (i.e., Jekyll, Middleman) rely on [.term]*front matter* added to the top of the document to determine how to convert the content.
+Front matter typically starts on the first line of a file and is bounded by block delimiters (e.g., `+---+`).
+
+Here's an example of a document that contains front matter:
+
+[source,asciidoc]
+----
+---  <.>
+layout: default <.>
+---  <.>
+= Document Title
+
+content
+----
+<.> Front matter opening delimiter
+<.> Front matter data
+<.> Front matter closing delimiter
+
+The static site generator removes these lines before passing the document to the AsciiDoc processor to be converted.
+Outside of the tool, however, these extra lines can throw off the processor.
+
+== skip-front-matter option
+
+If the `skip-front-matter` option is set via the API or CLI (e.g., `-a skip-front-matter`), Asciidoctor will recognize the front matter and consume it before parsing the document.
+Asciidoctor stores the content it removes in the `front-matter` attribute to make it available for integrations.
+Asciidoctor also removes front matter when reading xref:asciidoc:directives:include.adoc[include files].
diff --git a/docs/modules/html-backend/pages/verbatim-line-wrap.adoc b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc
new file mode 100644
index 00000000..f38b7daa
--- /dev/null
+++ b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc
@@ -0,0 +1,40 @@
+= Verbatim Block Line Wrapping
+
+The default Asciidoctor stylesheet wraps long lines in verbatim blocks by applying the CSS `white-space: pre-wrap` and `word-wrap: break-word`.
+The lines are wrapped at word boundaries, similar to how most text editors wrap lines.
+This prevents horizontal scrolling which some users considered a greater readability problem than line wrapping.
+
+However, this behavior is configurable because there are times when you don't want the lines in listing and literal blocks to wrap.
+
+== Prevent line wrapping
+
+There are two ways to prevent lines from wrapping so that horizontal scrolling is used instead:
+
+* `nowrap` block option
+* unset the `prewrap` document attribute (on by default)
+
+You can use the `nowrap` option on literal or listing blocks to prevent lines from being wrapped in the HTML.
+
+// FIXME this section is creating broken AsciiDoc!!
+.Listing block with nowrap option syntax
+....
+include::example$wrap.adoc[tag=nowrap]
+....
+
+When the nowrap option is used, the `nowrap` class is added to the `<pre>` element.
+This class changes the CSS to `white-space: pre` and `word-wrap: normal`.
+
+.Result: Listing block with nowrap option applied
+include::example$wrap.adoc[tag=nowrap]
+
+To prevent lines from wrapping globally, unset the `prewrap` attribute on the document.
+
+.Disable prewrap globally (thus, enabling nowrap)
+[source]
+----
+:prewrap!:
+----
+
+When the prewrap attribute is unset, the `nowrap` class is added to any `<pre>` elements.
+
+Now, you can use the line wrapping strategy that works best for you and your readers.
diff --git a/docs/modules/install/nav.adoc b/docs/modules/install/nav.adoc
new file mode 100644
index 00000000..afd431e0
--- /dev/null
+++ b/docs/modules/install/nav.adoc
@@ -0,0 +1,6 @@
+* xref:index.adoc[]
+** xref:supported-platforms.adoc[]
+** xref:gem.adoc[]
+** xref:linux.adoc[]
+** xref:macos.adoc[]
+** xref:windows.adoc[]
diff --git a/docs/modules/install/pages/gem.adoc b/docs/modules/install/pages/gem.adoc
new file mode 100644
index 00000000..af8b116f
--- /dev/null
+++ b/docs/modules/install/pages/gem.adoc
@@ -0,0 +1,67 @@
+= Install Using Ruby Tools
+
+[#gem-install]
+== gem install
+
+Before installing Asciidoctor using `gem install`, you should set up {url-rvm}[RVM^] to install Ruby in your home directory (i.e., user space).
+Then, you can safely use the `gem` command to install or update the Asciidoctor gem, or any other gem for that matter.
+When using RVM, gems are installed in a location isolated from the system.
+
+Once you've installed Ruby using RVM, and you have activated it using `rvm use {ruby-short}`, open a terminal and type:
+
+ $ gem install asciidoctor
+
+include::partial$success.adoc[]
+
+[#pre-release]
+=== Install a pre-release version
+
+To install a pre-release version of Asciidoctor (e.g., a release candidate), open a terminal and type:
+
+ $ gem install asciidoctor --pre
+
+== Bundler
+
+. Create a Gemfile in the root folder of your project (or the current directory)
+. Add the `asciidoctor` gem to your Gemfile as follows:
++
+[source,subs=attributes+]
+----
+source 'https://rubygems.org'
+gem 'asciidoctor'
+# or specify the version explicitly
+# gem 'asciidoctor', '{release-version}'
+----
+
+. Save the Gemfile
+. Open a terminal and install the gem using:
+
+ $ bundle
+
+To upgrade the gem, specify the new version in the Gemfile and run `bundle` again.
+Using `bundle update` (without specifying a gem) is *not* recommended as it will also update other gems, which may not be the desired result.
+
+== Upgrade using gem update
+
+[CAUTION]
+====
+You're advised against using the `gem update` command to update a gem managed by the package manager.
+Doing so puts the system into an inconsistent state as the package manager can no longer track the files (which get installed under [.path]_/usr/local_).
+Simply put, system gems should only be managed by the package manager.
+
+If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, you should use {url-rvm}[RVM^] to install Ruby in your home directory (i.e., user space).
+Then, you can safely use the `gem` command to install or update the Asciidoctor gem.
+When using RVM, gems are installed in a location isolated from the system.
+====
+
+You can upgrade Asciidoctor using the gem `update` command:
+
+ $ gem update asciidoctor
+
+[TIP]
+====
+If you accidentally use `gem install` instead of `gem update`, then you'll end up with both versions installed.
+To remove the older version, use the following `gem` command:
+
+ $ gem cleanup asciidoctor
+====
diff --git a/docs/modules/install/pages/index.adoc b/docs/modules/install/pages/index.adoc
new file mode 100644
index 00000000..bdc1c57d
--- /dev/null
+++ b/docs/modules/install/pages/index.adoc
@@ -0,0 +1,17 @@
+= Install Asciidoctor
+
+To simplify installation, Asciidoctor is packaged and distributed as a RubyGem (aka gem) to {url-rubygem}/asciidoctor[RubyGems.org^].
+It's also distributed as a package for popular Linux distributions and macOS.
+In addition to running on Ruby, Asciidoctor can be executed on a JVM using {url-asciidoctorj}[AsciidoctorJ^] or in any JavaScript environment (including the browser) using xref:asciidoctor.js::index.adoc[Asciidoctor.js].
+
+== Installation methods
+
+Asciidoctor can be installed using:
+
+* package managers for popular Linux distributions,
+* Homebrew for macOS,
+* the `gem install` command (recommended for Windows users or if you'll be installing additional gems),
+* the Asciidoctor Docker image, or
+* Bundler.
+
+The benefit of using your operating system's package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine.
diff --git a/docs/modules/install/pages/linux.adoc b/docs/modules/install/pages/linux.adoc
new file mode 100644
index 00000000..a2b605f6
--- /dev/null
+++ b/docs/modules/install/pages/linux.adoc
@@ -0,0 +1,84 @@
+= Install Using a Linux Package Manager
+:url-alpine: https://pkgs.alpinelinux.org/packages?name=asciidoctor
+:url-arch: https://www.archlinux.org/packages/?name=asciidoctor
+:url-debian: https://packages.debian.org/sid/asciidoctor
+:url-fedora: https://apps.fedoraproject.org/packages/rubygem-asciidoctor
+:url-suse: https://software.opensuse.org/package/rubygem-asciidoctor
+:url-ubuntu: https://packages.ubuntu.com/search?keywords=asciidoctor
+
+The benefit of using your operating system's package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine.
+
+== Linux packages
+
+The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor.
+Consult the package repository for your distribution to find out which version is packaged per distribution release.
+
+* {url-alpine}[Alpine Linux (asciidoctor)]
+* {url-arch}[Arch Linux (asciidoctor)]
+* {url-debian}[Debian (asciidoctor)]
+* {url-fedora}[Fedora (asciidoctor)]
+* {url-suse}[OpenSUSE (rubygem-asciidoctor)]
+* {url-ubuntu}[Ubuntu (asciidoctor)]
+
+If you want to use a version of Asciidoctor that is newer than what is available via your package manager, see xref:gem.adoc[].
+
+== APT
+
+On Debian and Debian-based distributions such as Ubuntu, use APT to install Asciidoctor.
+To install the package, open a terminal and type:
+
+ $ sudo apt-get install -y asciidoctor
+
+include::partial$success.adoc[]
+
+== DNF
+
+On RPM-based Linux distributions, such as Fedora, CentOS, and RHEL, use the DNF package manager to install Asciidoctor.
+To install the package, open a terminal and type:
+
+ $ sudo dnf install -y asciidoctor
+
+include::partial$success.adoc[]
+
+== apk (Alpine Linux)
+
+To install the gem on Alpine Linux, open a terminal and type:
+
+ $ sudo apk add asciidoctor
+
+include::partial$success.adoc[]
+
+== pacman (Arch Linux)
+
+To install the gem on Arch-based distributions, open a terminal and type:
+
+ $ sudo pacman -S asciidoctor
+
+include::partial$success.adoc[]
+
+[#upgrade]
+== Upgrading on Linux
+
+Some Linux distributions may not have the latest stable version of Asciidoctor packaged immediately after a release of a new gem.
+If you need to upgrade to the latest version immediately, use xref:gem.adoc[gem install] instead of the package manager.
+
+TIP: Your Linux system may be configured to automatically update packages, in which case the latest Asciidoctor package will be installed as soon as it becomes available.
+No further action is required by you.
+
+=== APT
+
+On Debian and Debian-based distributions, update the Asciidoctor package using:
+
+ $ sudo apt-get upgrade -y asciidoctor
+
+=== DNF
+
+On Fedora and other RPM-based distributions, you can update the package using:
+
+ $ sudo dnf update -y asciidoctor
+
+=== apk (Alpine Linux)
+
+On Alpine Linux, update the Asciidoctor package using:
+
+ $ sudo apk add -u asciidoctor
diff --git a/docs/modules/install/pages/macos.adoc b/docs/modules/install/pages/macos.adoc
new file mode 100644
index 00000000..25a71919
--- /dev/null
+++ b/docs/modules/install/pages/macos.adoc
@@ -0,0 +1,23 @@
+= Install on macOS
+:url-homebrew: https://brew.sh/
+
+== Install with Homebrew
+
+You can use Homebrew, the macOS package manager, to install Asciidoctor.
+If you don't have Homebrew on your computer, complete the installation instructions at {url-homebrew}[brew.sh^] first.
+
+Once Homebrew is installed, you're ready to install the `asciidoctor` gem.
+Open a terminal and type:
+
+ $ brew install asciidoctor
+
+Homebrew installs the `asciidoctor` gem into an exclusive prefix that's independent of system gems.
+
+include::partial$success.adoc[]
+
+== Upgrade with Homebrew
+
+To upgrade the gem, open a terminal and type:
+
+ $ brew update
+ $ brew upgrade asciidoctor
diff --git a/docs/modules/install/pages/supported-platforms.adoc b/docs/modules/install/pages/supported-platforms.adoc
new file mode 100644
index 00000000..789a01d4
--- /dev/null
+++ b/docs/modules/install/pages/supported-platforms.adoc
@@ -0,0 +1,45 @@
+= Supported Platforms
+
+Asciidoctor operates on Linux, macOS and Windows and requires one of the supported Ruby implementations listed in the next section.
+
+== Ruby runtimes
+
+Asciidoctor requires one of the following implementations of {url-ruby}[Ruby^].
+
+[%autowidth]
+|===
+|Supported Runtime |Supported Versions
+
+|Ruby
+|&#8805; 2.3
+
+|JRuby
+|&#8805; 9.1
+
+|TruffleRuby
+|&#8805; 20.2
+|===
+
+== Operating systems
+
+[%autowidth]
+|===
+|Supported OS |Supported Versions
+
+|Ubuntu
+|18.04 LTS
+
+|Fedora
+|&#8805; 31
+
+|macOS
+|High Sierra +
+Mojave +
+Catalina
+
+|Microsoft
+|Windows 10 +
+Windows Server 2019
+|===
+
+Note that while the community tests Asciidoctor on a variety of Linux distributions, it's only officially tested on Ubuntu and Fedora.
diff --git a/docs/modules/install/pages/windows.adoc b/docs/modules/install/pages/windows.adoc
new file mode 100644
index 00000000..ae25d23e
--- /dev/null
+++ b/docs/modules/install/pages/windows.adoc
@@ -0,0 +1,18 @@
+= Install on Windows
+
+To install Asciidoctor on Windows, you can use Chocolatey or Rubyinstaller.
+
+== Chocolatey
+
+When you already use https://chocolatey.org[chocolatey^] on your machine, you can use:
+
+[source]
+----
+choco install ruby
+----
+
+Then follow the xref:gem.adoc[gem installation instructions].
+
+== Rubyinstaller
+
+Or you use the https://rubyinstaller.org/downloads/[Rubyinstaller^], download the package for your Windows Version and after the installation, then follow the xref:gem.adoc[gem installation instructions].
diff --git a/docs/modules/install/partials/success.adoc b/docs/modules/install/partials/success.adoc
new file mode 100644
index 00000000..8ad68700
--- /dev/null
+++ b/docs/modules/install/partials/success.adoc
@@ -0,0 +1,12 @@
+If the gem installed successfully, its xref:cli:index.adoc[command line interface (CLI)] will be available on your PATH.
+To confirm that Asciidoctor is available, execute:
+
+ $ asciidoctor --version
+
+You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.
+
+[.output,subs=attributes+]
+....
+Asciidoctor {release-version} [https://asciidoctor.org]
+Runtime Environment ({ruby-description}) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
+....
diff --git a/docs/modules/integrations/nav.adoc b/docs/modules/integrations/nav.adoc
new file mode 100644
index 00000000..b6d8da60
--- /dev/null
+++ b/docs/modules/integrations/nav.adoc
@@ -0,0 +1,9 @@
+* Integrations
+** xref:syntax-highlighters.adoc[]
+*** xref:rouge.adoc[]
+*** xref:coderay.adoc[]
+*** xref:highlightjs.adoc[]
+*** xref:pygments.adoc[]
+** xref:stem.adoc[]
+*** xref:mathjax.adoc[]
+*** xref:asciimath-gem.adoc[]
diff --git a/docs/modules/integrations/pages/asciimath-gem.adoc b/docs/modules/integrations/pages/asciimath-gem.adoc
new file mode 100644
index 00000000..5d9e82d7
--- /dev/null
+++ b/docs/modules/integrations/pages/asciimath-gem.adoc
@@ -0,0 +1,39 @@
+= AsciiMath RubyGem
+:url-asciimath-repo: https://github.com/asciidoctor/AsciiMath
+
+Asciidoctor's built-in DocBook backend and MathJax aren't compatible, so Asciidoctor must explicitly convert xref:asciidoc:stem:stem.adoc[stem expressions] into something the DocBook toolchain can understand.
+Enter the {url-rubygem}/asciimath[AsciiMath RubyGem^].
+AsciiMath converts AsciiMath stem expressions in an AsciiDoc document to MathML and outputs them in a format that DocBook accepts.
+
+TIP: For more information, see the {url-asciimath-repo}[AsciiMath RubyGem repository^].
+
+== Install asciimath gem
+
+To enable AsciiMath support when converting to DocBook, you need to install the asciimath gem:
+
+ $ gem install asciimath
+
+== Activate asciimath stem expressions
+
+To activate AsciiMath, set the `stem` attribute in the document's header and assign it the value `asciimath`. (or by passing the attribute to the command line or API).
+
+.Set the stem attribute
+[source,asciidoc]
+----
+= Document Title
+:stem: asciimath
+----
+
+To learn how to create inline and block AsciiMath equations, see xref:asciidoc:stem:stem.adoc[].
+
+=== Using AsciiMath with the DocBook toolchain
+
+If you're generating a PDF from the DocBook output, the MathML produced by the asciimath gem needs to be interpreted and drawn into the PDF.
+In the DocBook toolchain, this is handled by JEuclid.
+
+Fortunately, the toolchain is already configured to use the JEuclid integration.
+When the DocBook toolchain generates the PDF, the JEuclid FOP plugin processes any MathML found in the DocBook file, including the expressions transformed from AsciiMath to MathML by the asciimath gem.
+As a result, AsciiMath stem expressions in the AsciiDoc file will render as expected in the generated PDF.
+
+There's no equivalent gem for converting STEM expressions written in LaTeX to MathML.
+Instead, you can convert the DocBook to PDF using the dblatex pipeline, which supports LaTeX expressions.
diff --git a/docs/modules/integrations/pages/coderay.adoc b/docs/modules/integrations/pages/coderay.adoc
new file mode 100644
index 00000000..7a590b8a
--- /dev/null
+++ b/docs/modules/integrations/pages/coderay.adoc
@@ -0,0 +1,107 @@
+= CodeRay
+:url-coderay: http://coderay.rubychan.de/
+:url-coderay-gem: https://rubygems.org/gems/coderay
+
+{url-coderay}[CodeRay^] is an encoding-aware, syntax highlighter that supports the languages listed below.
+
+[%autowidth,cols="3*",grid=none,frame=none]
+|===
+| C
+| C++
+| Clojure
+
+| CSS
+| Delphi
+| diff
+
+| ERB
+| Go
+| Groovy
+
+| HAML
+| HTML
+| Java
+
+| JavaScript
+| JSON
+| Lua
+
+| PHP
+| Python
+| Ruby
+
+| Sass
+| SQL
+| Taskpaper
+
+| XML
+| YAML
+|
+|===
+
+== Install CodeRay
+
+To use CodeRay with Asciidoctor, you need the {url-coderay-gem}[coderay RubyGem^].
+You can use one of the following methods to install CodeRay.
+
+Install using gem (all systems)::
++
+ $ gem install coderay
+
+Install using apt-get (Debian-based systems)::
++
+ $ sudo apt-get install coderay
+
+Install using dnf (Fedora-based systems)::
++
+ $ sudo dnf install rubygem-coderay
+
+== Activate CodeRay
+
+Once you've installed the RubyGem, assign the `coderay` value to the `source-highlighter` attribute in the document header to activate it.
+
+[source]
+----
+:source-highlighter: coderay
+----
+
+== CodeRay attributes
+
+You can further customize the source block output with additional CodeRay attributes.
+
+coderay-css::
+Controls what method is used for applying CSS to the tokens.
+Can be `class` or `style`.
+Default: `class`.
+
+coderay-linenums-mode::
+Controls how line numbers are laid out.
+Can be `table` or `inline`.
+If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines.
+Default: `table`.
+
+.Customizing a source block with CodeRay line numbers
+[source]
+....
+:source-highlighter: coderay
+:coderay-linenums-mode: inline
+
+[source,ruby,linenums]
+----
+ORDERED_LIST_KEYWORDS = {
+  'loweralpha' => 'a',
+  'lowerroman' => 'i',
+  'upperalpha' => 'A',
+  'upperroman' => 'I'
+   #'lowergreek' => 'a'
+   #'arabic'     => '1'
+   #'decimal'    => '1'
+}
+----
+....
+
+See the xref:html-backend:apply-code-stylesheets.adoc#coderay[CodeRay stylesheet section] to learn about the `coderay-css` attribute.
+
+////
+Note: I'm not getting this to work. Need to come back and do some quality assurance.
+////
diff --git a/docs/modules/integrations/pages/highlightjs.adoc b/docs/modules/integrations/pages/highlightjs.adoc
new file mode 100644
index 00000000..17372031
--- /dev/null
+++ b/docs/modules/integrations/pages/highlightjs.adoc
@@ -0,0 +1,42 @@
+= Highlight.js
+:url-highlightjs: https://highlightjs.org/
+:url-highlightjs-lang: https://highlightjs.org/download/
+:url-highlightjs-cdn: https://cdnjs.com/libraries/highlight.js
+
+{url-highlightjs}[Highlight.js^] is a popular client-side syntax highlighter that supports a broad range of {url-highlightjs-lang}[languages^].
+
+== Activate highlight.js
+
+To activate highlight.js, add the following attribute entry to the header of your AsciiDoc file:
+
+[source]
+----
+:source-highlighter: highlight.js
+----
+
+By default, Asciidoctor will link to the highlight.js library and stylesheet hosted on {url-highlightjs-cdn}[cdnjs^].
+The version of the highlight.js library Asciidoctor loads from the CDN only includes support for languages in the common language bundle (apache, bash, coffeescript, cpp, cs, css, diff, http, ini, java, javascript, json, makefile, markdown, nginx, objectivec, perl, php, properties, python, ruby, shell, sql, xml, and yaml).
+
+== Load support for additional languages
+
+To load additional languages supported by highlight.js, list them in the value of the `highlightjs-languages` document attribute (separated by commas):
+
+[source]
+----
+:source-highlighter: highlight.js
+:highlightjs-languages: rust, swift
+----
+
+== Using a custom highlight.js library
+
+If you'd rather use a personal copy of highlight.js instead of the one hosted on the CDN, follow these steps:
+
+. Create your custom bundle on the {url-highlightjs-lang}[download page^].
+. Download and unpack the zip into a folder called [.path]_highlight_ adjacent to your AsciiDoc file (or in the output directory, if different)
+. Rename [.path]_highlight/highlight.pack.js_ to [.path]_highlight/highlight.min.js_
+. Rename [.path]_highlight/styles/github.css_ to [.path]_highlight/styles/github.min.css_
+** Replace `github` with the name of the `highlightjs-theme` you are using, if different.
+. Add the attribute entry `:highlightjsdir: highlight` to the header of your AsciiDoc file.
+** Alternatively, you can pass the `-a highlightjsdir=highlight` flag when invoking the Asciidoctor CLI.
+
+The output file will use your personal copy of the highlight.js library and stylesheet instead of the one hosted on cdnjs.
diff --git a/docs/modules/integrations/pages/mathjax.adoc b/docs/modules/integrations/pages/mathjax.adoc
new file mode 100644
index 00000000..b27c7928
--- /dev/null
+++ b/docs/modules/integrations/pages/mathjax.adoc
@@ -0,0 +1,7 @@
+= MathJax
+:url-mathjax: https://www.mathjax.org
+:url-asciimath: https://docs.mathjax.org/en/latest/input/asciimath.html
+:url-latexmath: https://docs.mathjax.org/en/latest/input/tex/index.html
+
+{url-mathjax}[MathJax^] is a JavaScript library for displaying Science, Technology, Engineering and Math (STEM) expressions in the browser.
+The Asciidoctor HTML backend relies on MathJax to parse and render {url-asciimath}[AsciiMath^] and {url-latexmath}[TeX and LaTeX^] math notation.
diff --git a/docs/modules/integrations/pages/pygments.adoc b/docs/modules/integrations/pages/pygments.adoc
new file mode 100644
index 00000000..9456955b
--- /dev/null
+++ b/docs/modules/integrations/pages/pygments.adoc
@@ -0,0 +1,156 @@
+= Pygments
+:url-pygments: https://pygments.org
+:url-pygments-lang: https://pygments.org/languages/
+:url-python: https://www.python.org
+:url-pygments-gem: https://rubygems.org/gems/pygments.rb
+
+{url-pygments}[Pygments^] is a popular syntax highlighter that supports a broad range of {url-pygments-lang}[programming and template languages^].
+
+== Install Pygments
+
+In order to use Pygments with Asciidoctor, you need {url-python}[Python 2^] and the {url-pygments-gem}[pygments.rb gem^].
+The pygments.rb gem manages calls to Pygments, which is an external program that runs using Python.
+
+TIP: You do not need to install Pygments itself.
+It comes bundled with the pygments.rb gem.
+
+IMPORTANT: You must have Python 2 installed to use pygments.rb.
+Python 3 is not compatible with the pygments.rb gem.
+Check that you have a `python2` (Linux), `python` (macOS), or `py -2` (Windows) executable on your PATH.
+(On macOS, verify that the `python` executable uses Python 2 by running `python -V`).
+
+.Installing Python and the pygments.rb gem via the CLI (cross platform)
+[source,console]
+....
+$ "`\which apt-get || \which dnf || \which yum || \which brew`" install python # <.>
+$ gem install pygments.rb # <.>
+....
+<.> Install Python using your package manager
+<.> Install the pygments.rb gem
+
+== Activate Pygments
+
+Once you've installed these libraries, assign `pygments` to the `source-highlighter` attribute in your document's header.
+
+[source]
+----
+:source-highlighter: pygments
+----
+
+== Pygments attributes
+
+You can further customize the source block output with additional Pygments attributes.
+
+pygments-style::
+Sets the name of the color theme Pygments uses.
+To see the list of available style names, see <<listing-pygments-style-names>>.
+Default: `pastie`.
+
+pygments-css::
+Controls what method is used for applying CSS to the tokens.
+Can be `class` (CSS classes) or `style` (inline styles).
+See the xref:html-backend:apply-code-stylesheets.adoc#pygments[Pygments stylesheet section] to learn more about how the value `class` is handled.
+Default: `class`.
+
+pygments-linenums-mode::
+Controls how line numbers are arranged when line numbers are enabled on the source block.
+Can be `table` or `inline`.
+If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines.
+Default: `table`.
+
+.Customizing a source block with Pygments attributes
+[source]
+....
+:source-highlighter: pygments
+:pygments-style: manni
+:pygments-linenums-mode: inline
+
+[source,ruby,linenums]
+----
+ORDERED_LIST_KEYWORDS = {
+  'loweralpha' => 'a',
+  'lowerroman' => 'i',
+  'upperalpha' => 'A',
+  'upperroman' => 'I'
+   #'lowergreek' => 'a'
+   #'arabic'     => '1'
+   #'decimal'    => '1'
+}
+----
+....
+
+////
+.Result: Source block using inline line numbers and the manni theme
+====
+image::custom-pygments.png[Line numbers and a custom Pygments theme for a source block.]
+====
+////
+
+[#listing-pygments-style-names]
+=== Available Pygments style names
+
+To list the available Pygments styles, run the following command in a terminal:
+
+ $ $(dirname $(gem which pygments.rb))/../vendor/pygments-main/pygmentize -L styles
+
+The pygments.rb gem uses a bundled version of Pygments (often ahead of the latest release).
+This command ensures that you are invoking the `pygmentize` command from the Pygments used by that gem.
+
+== Pygments timeout
+
+Since Pygments is an external program, the call to that command is managed by a timeout to safe-guard against a hanging process.
+By default, this timeout is 8 seconds.
+If you discover that the call is failing to complete within this timeout period, you can increase the timeout (in seconds) by setting the `MENTOS_TIMEOUT` environment variable.
+
+ export MENTOS_TIMEOUT=30
+
+Now the call to Pygments will be allocated up to 30 seconds to complete.
+
+== Using a custom Pygments installation
+
+If you already have Pygments installed on your system, you want to use your own fork, or you want to customize how Pygments is configured, you can get Asciidoctor to use a custom version of Pygments instead of the one bundled with the pygments.rb gem.
+
+First, install your own version of Pygments.
+You can do this, for instance, by cloning the upstream Pygments repository:
+
+ $ hg clone https://bitbucket.org/birkenfeld/pygments-main pygments
+
+Find the directory that contains the file [.path]_pygmentize_ or the [.path]_Makefile_.
+That's your Pygments installation path.
+Make note of it.
+
+Next, create a script to run _before_ invoking Asciidoctor for the first time.
+Let's call it [.path]_pygments_init.rb_.
+Populate the script with the following content:
+
+.pygments_init.rb
+[source,ruby]
+----
+require 'pygments'
+
+# use a custom Pygments installation (directory that contains pygmentize)
+Pygments.start '/path/to/pygments'
+
+# example of registering a missing or additional lexer
+#Pygments::Lexer.create name: 'Turtle', aliases: ['turtle'],
+#    filenames: ['*.ttl'], mimetypes: ['text/turtle', 'application/x-turtle']
+----
+
+TIP: You could enhance this script to read the Pygments installation path from an environment variable (or configuration file).
+
+Now just require this script before your invoke Asciidoctor the first time.
+When using the `asciidoctor` command, pass the script using the `-r` flag:
+
+ $ asciidoctor -r ./pygments_init.rb document.adoc
+
+When using the Asciidoctor API, require the script using `require` or `require_relative`:
+
+[source,ruby]
+----
+require 'asciidoctor'
+require_relative './pygments_init.rb'
+
+Asciidoctor.convert_file 'document.adoc', safe: :safe
+----
+
+Now Asciidoctor is using your custom installation of Pygments instead of the one bundled with the pygments.rb gem.
diff --git a/docs/modules/integrations/pages/rouge.adoc b/docs/modules/integrations/pages/rouge.adoc
new file mode 100644
index 00000000..b6022864
--- /dev/null
+++ b/docs/modules/integrations/pages/rouge.adoc
@@ -0,0 +1,70 @@
+= Rouge
+:url-rouge: http://rouge.jneen.net
+:url-rouge-gem: https://rubygems.org/gems/rouge
+:url-rouge-repo: https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes
+
+{url-rouge}[Rouge^] is an extendable code highlighter written in Ruby that supports a vast array of languages.
+
+== Install Rouge
+
+To use Rouge with Asciidoctor, you need the {url-rouge-gem}[rouge RubyGem^].
+You can use one of the following methods to install Rouge.
+
+Install using `gem` (all systems)::
++
+ $ gem install rouge
+
+Install using `apt-get` (Debian-based systems)::
++
+ $ sudo apt-get install rouge
+
+Install using `dnf` (Fedora-based systems)::
++
+ $ sudo dnf install rubygem-rouge
+
+== Assign rouge to source-highlighter
+
+Once you've installed the RubyGem, assign the `rouge` value to the `source-highlighter` attribute in the document header to activate it.
+
+[source]
+----
+:source-highlighter: rouge
+----
+
+== Rouge attributes
+
+You can further customize the source block output with additional Rouge attributes.
+
+rouge-css::
+Controls what method is used for applying CSS to the tokens.
+Can be `class` or `style`.
+Default: `class`.
+
+[.line-through]#rouge-linenums-mode# (not currently implemented)::
+Controls how line numbers are laid out.
+Can be `table` or `inline`.
+If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines.
+Default: `table`.
+
+rouge-style::
+Controls the color theme used to for highlighting.
+You can find the list of themes in the {url-rouge-repo}[Rouge code repository^].
+
+.Customizing a source block with Rouge line numbers
+[source]
+....
+:source-highlighter: rouge
+
+[source,ruby,linenums]
+----
+ORDERED_LIST_KEYWORDS = {
+  'loweralpha' => 'a',
+  'lowerroman' => 'i',
+  'upperalpha' => 'A',
+  'upperroman' => 'I'
+   #'lowergreek' => 'a'
+   #'arabic'     => '1'
+   #'decimal'    => '1'
+}
+----
+....
diff --git a/docs/modules/integrations/pages/stem.adoc b/docs/modules/integrations/pages/stem.adoc
new file mode 100644
index 00000000..809dfa16
--- /dev/null
+++ b/docs/modules/integrations/pages/stem.adoc
@@ -0,0 +1,15 @@
+= Supported STEM Libraries
+// Stem equations and formulas
+
+[%autowidth]
+|===
+|Integration |Supported Versions |Backends
+
+|MathJax
+|2.7.9
+|HTML
+
+|AsciiMath
+|2.0.x
+|Docbook
+|===
diff --git a/docs/modules/integrations/pages/syntax-highlighters.adoc b/docs/modules/integrations/pages/syntax-highlighters.adoc
new file mode 100644
index 00000000..a8354393
--- /dev/null
+++ b/docs/modules/integrations/pages/syntax-highlighters.adoc
@@ -0,0 +1,26 @@
+= Supported Syntax Highlighters
+
+[%autowidth]
+|===
+|Feature |Supported Integration |Supported Versions
+
+|Client-side syntax highlighting for source code blocks
+|Highlight.js
+|9.18.3
+
+.3+|Server-side syntax highlighting for source code blocks
+|CodeRay
+|1.1.2
+
+|Pygments
+|2.2.0
+
+|Rouge
+|3.1.1
+|===
+
+////
+|Inline, admonition or callout font-based icons
+|Font Awesome
+|4.7
+////
diff --git a/docs/modules/manpage-backend/examples/manpage.adoc b/docs/modules/manpage-backend/examples/manpage.adoc
new file mode 100644
index 00000000..c865d610
--- /dev/null
+++ b/docs/modules/manpage-backend/examples/manpage.adoc
@@ -0,0 +1,42 @@
+= eve(1)
+Andrew Stanton
+v1.0.0
+:doctype: manpage
+:manmanual: EVE
+:mansource: EVE
+:man-linkstyle: pass:[blue R < >]
+
+== Name
+
+eve - analyzes an image to determine if it's a picture of a life form
+
+== Synopsis
+
+*eve* [_OPTION_]... _FILE_...
+
+== Options
+
+*-o, --out-file*=_OUT_FILE_::
+  Write result to file _OUT_FILE_.
+
+*-c, --capture*::
+  Capture specimen if it's a picture of a life form.
+
+== Exit status
+
+*0*::
+  Success.
+  Image is a picture of a life form.
+
+*1*::
+  Failure.
+  Image is not a picture of a life form.
+
+== Resources
+
+*Project web site:* https://eve.example.org
+
+== Copying
+
+Copyright (C) 2008 {author}. +
+Free use of this software is granted under the terms of the MIT License.
diff --git a/docs/modules/manpage-backend/nav.adoc b/docs/modules/manpage-backend/nav.adoc
new file mode 100644
index 00000000..31f850ee
--- /dev/null
+++ b/docs/modules/manpage-backend/nav.adoc
@@ -0,0 +1 @@
+* xref:index.adoc[]
diff --git a/docs/modules/manpage-backend/pages/index.adoc b/docs/modules/manpage-backend/pages/index.adoc
new file mode 100644
index 00000000..31386990
--- /dev/null
+++ b/docs/modules/manpage-backend/pages/index.adoc
@@ -0,0 +1,116 @@
+= Generate Man Pages from AsciiDoc
+:navtitle: Generate Man Pages
+:url-man7: https://man7.org/linux/man-pages/man7/roff.7.html
+:url-docbook-refmisc: https://tdg.docbook.org/tdg/5.0/refmiscinfo.html
+:url-manpage-raw: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/man/asciidoctor.adoc
+
+== Manual page converter
+
+Asciidoctor's built-in man page converter generates {url-man7}[roff-formatted^] manual pages from AsciiDoc documents.
+
+== What is a manual page?
+
+A manual page, often abbreviated to man page, is a form of software documentation found on Unix-based operating systems.
+The formalized structure of its content allows the `man` command to present the man page as a formatted document in a terminal pager.
+
+== Generate a man page with the manpage converter
+
+Before running Asciidoctor, make sure your source document adheres to the <<man-page-doctype,manpage doctype structure>> and has the doctype attribute set to `manpage`.
+
+To generate a man page, run:
+
+ $ asciidoctor -b manpage source.adoc
+
+The manpage converter sets the output file name to `progname.1`, where `progname` is the name of the command and `1` is the volume number, as defined by the doctitle of the source document.
+
+When converting to the man page format, Asciidoctor uppercases the titles of all level-0 and level-1 sections.
+This saves you from having to type section titles in all uppercase.
+It also makes the document portable to other output formats since this style is only needed in the man page output to align with conventions.
+
+CAUTION: If you're using Ruby 2.4 or greater, Asciidoctor will uppercase any letter in the title that is recognized by the Unicode specification as having an uppercase equivalent (which includes non-Latin letters).
+Prior to Ruby 2.4, Ruby could only uppercase Latin letters.
+
+Asciidoctor can also produce HTML and PDF versions similar to the `manpage` output for viewing in other contexts.
+To see the man page in HTML, run:
+
+ $ asciidoctor source.adoc
+
+Here is an example man page composed in AsciiDoc for the `eve` command:
+
+[source,asciidoc]
+----
+include::example$manpage.adoc[]
+----
+
+== Man page doctype
+
+The `manpage` doctype has the following required parts:
+
+Document Header::
+A manpage document header is mandatory.
+The title line contains the man page name followed immediately by the manual section number in round brackets.
+The title name should not contain white space.
+The manual section number is a single digit optionally followed by a single character.
+
+The NAME Section::
+The first manpage section is mandatory, must be titled "`NAME`" and must contain a single paragraph (usually a single line) consisting of a list of one or more comma-separated command name(s) separated from the command purpose by a dash character.
+The dash must have at least one white space character on either side.
+
+The SYNOPSIS Section::
+The second manpage section is mandatory and must be titled "`SYNOPSIS`".
+
+Subsequent sections are optional, but typical sections include "`SEE ALSO`", "`BUGS REPORTS`", "`AUTHORS`" and "`COPYRIGHT`".
+
+== Man page attributes
+
+Several built-in document attributes only affect man pages.
+These attributes must be set in the document header.
+
+[cols="<15,<30,<30"]
+.Built-in document attributes specific to the manpage doctype
+|===
+|Attribute name |Description |Value (as parsed from example above)
+
+|mantitle
+|Alternative way to set the man page name.
+|ASCIIDOCTOR(1)
+
+|manvolnum
+|Manual section number.
+|1
+
+|manname
+|Alternative way to set the command name.
+|asciidoctor
+
+|manpurpose
+|Alternative way to set the command purpose.
+|converts AsciiDoc source files
+
+|man-linkstyle
+|Style the links in the manpage output.
+A valid link format sequence.
+// Needs a reference to this.
+|blue R <>
+
+|mansource
+|The source to which the manpage pertains.
+When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^] attribute and appears in the footer.
+|Asciidoctor
+
+|manversion
+|The version of the man page.
+Defaults to revnumber if not specified.
+When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^] attribute and appears in the footer.
+Not used by Asciidoctor.
+|1.5.4
+
+|manmanual
+|Manual name.
+When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^] attribute and appears in the footer.
+|Asciidoctor Manual
+|===
+
+Refer to {url-manpage-raw}[the AsciiDoc source of the Asciidoctor man page^] to see a complete example.
+The man page for Asciidoctor is produced using the `manpage` converter.
+The man pages for git are also produced from AsciiDoc documents, so you can use those as another example to follow.
diff --git a/docs/modules/migrate/examples/convert.groovy b/docs/modules/migrate/examples/convert.groovy
new file mode 100644
index 00000000..6dba705c
--- /dev/null
+++ b/docs/modules/migrate/examples/convert.groovy
@@ -0,0 +1,43 @@
+// This script is provided by melix.
+// The source can be found at https://gist.github.com/melix/6020336
+
+@Grab('net.sourceforge.htmlcleaner:htmlcleaner:2.4')
+import org.htmlcleaner.*
+
+def src = new File('html').toPath()
+def dst = new File('asciidoc').toPath()
+
+def cleaner = new HtmlCleaner()
+def props = cleaner.properties
+props.translateSpecialEntities = false
+def serializer = new SimpleHtmlSerializer(props)
+
+src.toFile().eachFileRecurse { f ->
+    def relative = src.relativize(f.toPath())
+    def target = dst.resolve(relative)
+    if (f.isDirectory()) {
+        target.toFile().mkdir()
+    } else if (f.name.endsWith('.html')) {
+        def tmpHtml = File.createTempFile('clean', 'html')
+        println "Converting $relative"
+        def result = cleaner.clean(f)
+        result.traverse({ tagNode, htmlNode ->
+                tagNode?.attributes?.remove 'class'
+                if ('td' == tagNode?.name || 'th'==tagNode?.name) {
+                    tagNode.name='td'
+                    String txt = tagNode.text
+                    tagNode.removeAllChildren()
+                    tagNode.insertChild(0, new ContentNode(txt))
+                }
+
+            true
+        } as TagNodeVisitor)
+        serializer.writeToFile(
+                result, tmpHtml.absolutePath, "utf-8"
+        )
+        "pandoc -f html -t asciidoc -R -S --normalize -s $tmpHtml -o ${target}.adoc".execute().waitFor()
+        tmpHtml.delete()
+    }/* else {
+        "cp html/$relative $target".execute()
+    }*/
+}
diff --git a/docs/modules/migrate/nav.adoc b/docs/modules/migrate/nav.adoc
new file mode 100644
index 00000000..6df6ade3
--- /dev/null
+++ b/docs/modules/migrate/nav.adoc
@@ -0,0 +1,7 @@
+* Migration Guides
+** xref:upgrade.adoc[]
+** xref:asciidoc-python.adoc[]
+** xref:docbook-xml.adoc[]
+** xref:markdown.adoc[]
+** xref:confluence-xhtml.adoc[]
+** xref:ms-word.adoc[]
diff --git a/docs/modules/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc
new file mode 100644
index 00000000..c18e26c4
--- /dev/null
+++ b/docs/modules/migrate/pages/asciidoc-python.adoc
@@ -0,0 +1,368 @@
+= Migrate from AsciiDoc.py to Asciidoctor
+:navtitle: Migrate from AsciiDoc.py
+:url-diagram: {url-org}/asciidoctor-diagram
+:url-tests: {url-org}/asciidoctor/tree/master/test
+:url-doctest: {url-org}/asciidoctor-doctest
+:url-manpage: {url-project}/man/asciidoctor
+//:uri-diffs: {uri-home}/docs/asciidoc-asciidoctor-diffs/
+// um anchor: migrating-from-asciidoc-python
+
+In order to take advantage of the new features and syntax in Asciidoctor, you'll
+need to migrate legacy AsciiDoc documents written for AsciiDoc Python (AsciiDoc.py) to the AsciiDoc syntax supported by Asciidoctor.
+
+NOTE: This documentation specifically covers migration from AsciiDoc.py 8 to the latest stable version of Asciidoctor.
+
+== Processor call
+
+The Asciidoctor processor is a drop-in replacement for AsciiDoc.py.
+For most documents, you can simply replace the call to AsciiDoc.py (`asciidoc`) with the equivalent call to Asciidoctor (`asciidoctor`).
+
+ $ asciidoctor document.adoc
+
+// $ asciidoctor -a compat-mode document.adoc
+
+You can also run Asciidoctor on the JVM using AsciidoctorJ or with JavaScript using xref:asciidoctor.js::index.adoc[Asciidoctor.js].
+
+== Default HTML backend
+
+AsciiDoc.py used XHTML 1.1 as its default output.
+Asciidoctor's default output is HTML 5 (the `html5` converter).
+
+== Themes
+
+AsciiDoc.py provided a theming mechanism that encapsulated CSS, JavaScript, and images.
+The `--theme` option activated one of these themes, which was resolved from your home directory.
+In Asciidoctor, you control the theme using CSS stylesheets, which you specify using `-a stylesheet=<stylesheet>`.
+
+If you require more advanced theming, you can inject additional resources using a xref:ROOT:docinfo.adoc[docinfo file] or a xref:extensions:postprocessor.adoc[postprocessor extension].
+
+[#migrate-stylesheet]
+=== Default HTML stylesheet
+
+The AsciiDoc.py and Asciidoctor stylesheets look quite different, but they are compatible (for the most part) since the formatting is based on the same HTML structure and CSS classes.
+If you prefer the AsciiDoc.py stylesheet, you can use it by copying it from the AsciiDoc.py [.path]_stylesheets_ directory and instructing Asciidoctor to apply it using:
+
+ $ asciidoctor -a stylesheet=asciidoc.css document.adoc
+
+Keep in mind that the default stylesheet in Asciidoctor is just that, a default.
+If you don't like its appearance, you can customize it.
+
+IMPORTANT: Unlike AsciiDoc.py, Asciidoctor loads some resources from a CDN.
+It's possible to configure Asciidoctor to load all resources from local files.
+For instance, you can unset the `webfonts` attribute so that the generated HTML does not use fonts from Google Fonts.
+There are similar attributes to control how additional resources are resolved.
+
+== Updated and deprecated AsciiDoc syntax
+
+*If a feature or attribute isn't mentioned in the following tables, than it works in Asciidoctor just like it worked in AsciiDoc.py.*
+
+=== Inline formatting
+
+[cols="15,20,30,15"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|_italic text_
+|pass:['italic text']
+|pass:[_italic text_]
+|Allowed with `compat-mode`
+
+|`monospace text`
+|pass:[+monospace text+]
+|pass:[`monospace text`]
+|Allowed with `compat-mode`
+
+|`+literal monospace text+`
+|pass:[`literal monospace text`]
+|pass:[`+literal monospace text+`]
+|Allowed with `compat-mode`
+
+|Curved "`double quotes`"
+|pass:[``double quotes'']
+|pass:["`double quotes`"], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8220;)
+|
+
+|Curved '`single quotes`'
+|pass:[`single quotes']
+|pass:['`single quotes`'], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8217;)
+|
+
+|Sizes, lines, and colors
+|`big`, `small`, `underline`, `overline`, `line-through`, colors
+|user-specified `+[.<role-name>]+` and associated formatting in stylesheet
+|See xref:asciidoc:text:custom-inline-styles.adoc[custom text styles]
+|===
+
+=== Table of contents
+
+[cols="15,20,30,15"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Scrollable, left margin ToC
+|`toc2`
+|`+:toc: left+`
+|
+
+|ToC location
+|`toc-placement` and `toc-position`
+|`+:toc: <value>+`
+|
+
+|User-specified ToC location
+|`+:toc-placement: manual+`
+|`+:toc: macro+`
+|
+|===
+
+=== Document header
+
+[cols="15,20,15,35"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Implicit document title attribute
+|First content line at document top is set as title
+|pass:[= Title]
+|Allowed with `compat-mode`
+
+|Two-line style document title
+|pass:[= Title] +
+pass:[=====]
+|pass:[= Title]
+|Asciidoctor accepts the two-line heading style to set the document title.
+But 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.
+|===
+
+.Sections
+[cols="15,20,30,15"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Underlined titles
+|Underline length must match title length +/- 2 characters.
+|pass:[== Level 1 section title] +
+pass:[=== Level 2 section title] +
+pass:[==== Level 3 section title] +
+pass:[===== Level 4 section title] +
+|See xref:asciidoc:sections:titles-and-levels.adoc[section levels and titles]
+
+|Section numbers
+|`numbered`
+|`sectnums`
+|
+|===
+
+=== Tables
+
+[cols="15,20,20,20"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|AsciiDoc table cell
+|`a{vbar}` or `asciidoc{vbar}`
+|`a{vbar}` only
+|
+
+|Table cell separator
+|A Python regular expression.
+|One or more literal characters or \t for tab.
+|
+
+|Horizontal and vertical alignment for tables cells
+|`halign`, `valign`
+|Column and cell specifiers
+|See xref:asciidoc:tables:align-by-column.adoc[align column content] or xref:asciidoc:tables:align-by-cell.adoc[cell content].
+
+|Make tables full page width in DocBook
+|`options="pgwide"`
+|_not implemented_
+|
+|===
+
+=== Blocks
+
+[cols="15,20,30,15"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Block delimiters
+|Delimiter lines do not have to match in length.
+|The length of start and end delimiter lines must match exactly.
+|
+|===
+
+.General
+[cols="15,20,30,15"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|+ifeval::[ ]+
+|Evaluates any Python expression.
+|Evaluates simple logical expressions testing the value of attributes.
+|See xref:asciidoc:directives:ifeval.adoc[ifeval directive]
+
+|Provide name of current document
+|`infile`
+|_not implemented_
+|
+
+|Provide directory of current document
+|`indir`
+|_not implemented_
+|
+
+|Substitute (`+`)
+|`replacements2`
+|Renamed to `post_replacements`
+|See xref:asciidoc:subs:post-replacements.adoc[]
+
+|Suppress inline substitutions and retain block indents when importing large blocks of plain text
+|`plaintext`
+|_not implemented_
+|Closest Asciidoctor equivalent is a xref:asciidoc:pass:pass-block.adoc[passthrough block] or a listing block with an indent attribute.
+
+|Turn single line comments into DocBook `<remark>` elements
+|`showcomments`
+|_not implemented_
+a|If you want to send remarks to the output, use an extension, or:
+
+----
+ ifdef::showcomments+basebackend-docbook[]
+ ++++
+ <remark>Your comment here</remark>
+ ++++
+ endif::[]
+----
+
+|Apply special formatting to named text.
+|`specialwords`
+|_not implemented_
+|
+
+|Replace tabs with spaces in all text, using a default tab size of 8
+|`tabsize` (in-document and include directive)
+|in-document only
+|Asciidoctor only replaces tabs with spaces in verbatim content blocks (listing, literal, etc.), and the attribute has no default.
+In other words, tabs are not expanded in verbatim content blocks unless this attribute is set on the block or the document.
+For all other text, Asciidoctor tabs are fixed at 4 spaces by the CSS.
+See xref:asciidoc:directives:include-with-indent.adoc[normalize block indentation] for more detail.
+|===
+
+== Mathematical expressions
+
+AsciiDoc.py and Asciidoctor can convert embedded LaTeX and AsciiMath expressions (e.g., `pass:[asciimath:[expression]]`, `pass:[latexmath:[expression]]`, etc.).
+In Asciidoctor, you'll need to activate STEM support first using the xref:asciidoc:stem:stem.adoc[stem attribute].
+
+== Configuration files
+
+Asciidoctor does not use [.path]_.conf_ files or filters, so `--conf-file`, `--dump-conf`, and `--filter` are not applicable.
+Instead, Asciidoctor provides an xref:extensions:register.adoc[extension API] that replaces the configuration-based extension and filter mechanisms in AsciiDoc.py.
+
+=== Internationalization
+
+AsciiDoc.py had built-in [.path]_.conf_ files that translated built-in labels.
+In Asciidoctor, you must define the translations for these labels explicitly.
+See xref:ROOT:language-support.adoc[language support] for details.
+
+[#migrate-extensions]
+== AsciiDoc.py extensions
+
+The extension mechanism is completely different in Asciidoctor, but the most of the standard extensions have been re-implemented, so they should work with minor changes.
+
+[cols="<20,<80"]
+|===
+|AsciiDoc.py |Asciidoctor
+
+|source
+a|
+* You can choose from a number of xref:asciidoc:verbatim:source-highlighter.adoc#built-in-values[source highlighters].
+* Source highlighter values are built-in.
+* `src_numbered`, `src_tab`, `args` are not implemented directly, but check the highlighter you are using for what features it has and how to configure them.
+
+|music
+|Not implemented.
+
+|`[latex]` block macro
+|Use a xref:asciidoc:stem:stem.adoc#stem-bl[stem block].
+
+|graphviz
+|Use {url-diagram}[Asciidoctor Diagram^].
+|===
+
+=== Custom extensions
+
+AsciiDoc.py custom extensions are Python commands, so they don't work with Asciidoctor.
+Depending on the Asciidoctor processor you choose, you can re-write your xref:extensions:register.adoc[extensions in Ruby, Java, or JavaScript].
+
+== Doctest
+
+AsciiDoc.py `--doctest` ran its unit tests.
+See the {url-tests}[test suite^] for how to run the Asciidoctor unit tests.
+Asciidoctor also has a {url-doctest}[doctest tool^] which you can use when creating custom HTML or XML-based converters.
+
+== Help Topics
+
+In both AsciiDoc.py and Asciidoctor, the `--help` CLI option shows the command usage by default.
+It can also show a syntax crib sheet using `--help syntax` or the man page using `--help manpage`.
+
+In AsciiDoc.py, the `--help manpage` option emits a plaintext version of the man page.
+Asciidoctor, on the other hand, outputs the formatted man page.
+To view it, you need to pipe the result to the `man` command as follows:
+
+ $ asciidoctor --help manpage | man /dev/stdin
+
+or
+
+ $ asciidoctor --help manpage | man -l -
+
+If you want to view the plaintext version with Asciidoctor, you can route the output through the `col` command as follows:
+
+ $ asciidoctor --help manpage | man -l - | col -bx
+
+Alternately, you can view the manpage for Asciidoctor online at {url-manpage}[asciidoctor(1)].
+
+////
+This content needs to be move to the specific subject docs pages if applicable
+
+== Features Introduced by Asciidoctor
+
+=== New Syntax
+
+Asciidoctor has shorthand for id, role, style and options.
+The following longhand syntax in AsciiDoc.py:
+
+[source]
+----
+[[id]]
+[style,role="role",options="option1,option2"]
+----
+
+can be written using the shorthand supported by Asciidoctor:
+
+[source]
+----
+[style#id.role%option1%option2]
+----
+
+The longhand forms still work, but you should use the new forms for future compatibility, convenience and readability.
+
+=== Enhancements
+
+There are lots of new features and improvements Asciidoctor.
+These are some of the more interesting ones when migrating:
+
+* xref:directives:include-lines-and-tags.adoc[Partial includes]
+* xref:attributes:safe-modes.adoc[Additional safe modes]
+* xref:macros:icons.adoc[Icon-based fonts and inline icons]
+* {url-diagram}[Asciidoctor Diagram^]
+
+A detailed list of the improvements is shown in #Differences between Asciidoctor and AsciiDoc.py#.
+
+This is the compat mode summary which needs a page.
+
+These changes are not backward-compatible, but if you set the `compat-mode` attribute, Asciidoctor will accept the AsciiDoc.py syntax.
+For the long term, you should update to the Asciidoctor syntax.
+Consult the {uri-migrate}[Migration Guide] to get the full details and learn how to migrate smoothly.
+////
diff --git a/docs/modules/migrate/pages/confluence-xhtml.adoc b/docs/modules/migrate/pages/confluence-xhtml.adoc
new file mode 100644
index 00000000..744cf0f1
--- /dev/null
+++ b/docs/modules/migrate/pages/confluence-xhtml.adoc
@@ -0,0 +1,29 @@
+= Migrate from Confluence XHTML to Asciidoctor
+:navtitle: Migrate from Confluence XHTML
+:url-pandoc: https://pandoc.org
+
+You can convert Atlassian Confluence XHTML pages to Asciidoctor using this Groovy script.
+
+The script calls {url-pandoc}[Pandoc^] to convert single or multiple HTML files exported from Confluence to AsciiDoc files.
+You'll need Pandoc installed before running this script.
+If you have trouble running this script, you can use the Pandoc command referenced inside the script to convert XHTML files to AsciiDoc manually.
+
+.convert.groovy
+[source,groovy]
+----
+include::example$convert.groovy[]
+----
+
+This script was created by Cédric Champeau (https://gist.github.com/melix[melix]).
+You can find the source of this script hosted at this https://gist.github.com/melix/6020336[gist].
+
+The script is designed to be run locally on HTML files or directories containing HTML files exported from Confluence.
+
+== Usage
+
+. Save the script contents to a `convert.groovy` file in a working directory.
+. Make the file executable according to your specific OS requirements.
+. Place individual files, or a directory containing files into the working directory.
+. Run `groovy convert filename.html` to convert a single file.
+. Confirm the output file meets requirements
+. Recurse through a directory by using this command pattern: `groovy convert directory/*.html`
diff --git a/docs/modules/migrate/pages/docbook-xml.adoc b/docs/modules/migrate/pages/docbook-xml.adoc
new file mode 100644
index 00000000..06cb5a96
--- /dev/null
+++ b/docs/modules/migrate/pages/docbook-xml.adoc
@@ -0,0 +1,19 @@
+= Migrate from DocBook XML to Asciidoctor
+:navtitle: Migrate from DocBook XML
+:url-docbookrx: https://github.com/opendevise/docbookrx
+// docbookrx.adoc, included in user-manual: Convert DocBook XML to AsciiDoc
+
+One of the things Asciidoctor excels at is converting AsciiDoc source into valid and well-formed DocBook XML content.
+
+What if you're in the position where you need to go the other way: migrate all your legacy DocBook XML content to AsciiDoc?
+The prescription (℞) you need to get rid of your DocBook pains could be {url-docbookrx}[DocBookRx^].
+
+DocBookRx is an early version of a DocBook to AsciiDoc converter written in Ruby.
+This converter is far from perfect at the moment, but it improves with each document it converts.
+
+The plan is to evolve it into a robust library for performing this conversion in a reliable way.
+You can read more about this initiative in the {url-docbookrx}/blob/master/README.adoc[README^].
+
+The best thing about this tool is all the active users who are putting it through its paces.
+The more advanced the DocBook XML this tool tackles, and the more feedback we receive, the better the tool will become.
+Use it today to escape from XML hell!
diff --git a/docs/modules/migrate/pages/markdown.adoc b/docs/modules/migrate/pages/markdown.adoc
new file mode 100644
index 00000000..eab57dc3
--- /dev/null
+++ b/docs/modules/migrate/pages/markdown.adoc
@@ -0,0 +1,6 @@
+= Migrate from Markdown to Asciidoctor
+:navtitle: Migrate from Markdown
+
+Asciidoctor recognizes a fair amount of Markdown syntax, thus allowing you to migrate from Markdown to AsciiDoc gradually.
+See #asciidoc-syntax-quick-reference/markdown-compatibility,Markdown Compatibility# to learn what syntax is shared.
+The syntax you must change is listed in #asciidoc-vs-markdown#.
diff --git a/docs/modules/migrate/pages/ms-word.adoc b/docs/modules/migrate/pages/ms-word.adoc
new file mode 100644
index 00000000..aea595c6
--- /dev/null
+++ b/docs/modules/migrate/pages/ms-word.adoc
@@ -0,0 +1,196 @@
+= Migrate from MS Word to Asciidoctor
+:navtitle: Migrate from MS Word
+:description: This document presents various tools and strategies for migrating from MS Word to AsciiDoc.
+:url-pandoc: https://pandoc.org
+:url-google-asciidoc: https://chrome.google.com/webstore/detail/asciidoc-processor/eghlmnhjljbjodpeehjjcgfcjegcfbhk/
+:url-google-asciidoc-source:  https://github.com/Mogztter/asciidoc-googledocs-addon/
+// from migrating-from-msword.adoc
+
+== Pandoc
+
+{url-pandoc}[Pandoc^] is a swiss army knife for converting one markup format to another.
+It does an admirable job converting simple docx files to AsciiDoc.
+
+NOTE: Generally, we don't like to recommend pandoc because it doesn't create AsciiDoc the way we prefer.
+However, in this case, it's a good choice.
+
+To perform the conversion from MS Word docx to AsciiDoc, you need to perform the following command:
+
+ $ pandoc --from=docx --to=asciidoc --wrap=none --atx-headers \
+     --extract-media=extracted-media input.docx > output.adoc
+
+Then, edit the output file to tidy it up.
+
+The conversions you can expect are shown in the following table (tested using MS Word 2010 and 2013 + Pandoc 2.0 and 2.5 (Windows)):
+
+.Pandoc MS Word to AsciiDoc conversions
+|===
+|MS Word Feature |Conversion
+
+|Headings (using MS Word Heading styles 1-5)
+|Yes
+
+|Tables
+|Yes. +
+Merged cells are unmerged.
+Column widths are ignored.
+
+|Unordered and ordered lists
+|Yes
+
+|Footnotes
+|Yes
+
+|Figure and table captions
+|Normal paragraph
+
+|Other MS Word styled paragraphs
+|Normal paragraph
+
+|Embedded images
+|Yes
+
+|Character formatting (bold, underline and italic)
+|Yes
+
+|URL links
+|No - see <<remove-refs,how to remove hyperlinks>> to fix it
+
+|email links
+|Yes
+
+|Document automation (fields, auto-generated figure and table numbers)
+|Ignored
+
+|Internal references (e.g., "`See Figure 3`")
+|Plain text
+
+|Drawing canvas
+|Ignored
+
+|Text boxes
+|Ignored
+
+|Linked (not embedded) images
+|Ignored
+
+|Vector graphics (MS Word "`insert shape`")
+|Ignored
+|===
+
+== Optimizing for Pandoc
+
+The basic usage documented above is fine for one-off imports.
+If you have a lot to do, it's worth while cleaning the input document first, and automating the post-conversion tidy up.
+
+. Clean up the MS Word document:
+// Title pages are usually easier to recreate manually
+** Remove non-essential material (title pages, headers and footers, table of contents etc.); it is usually easiest to copy just the body text into a new blank document
+// Technically not necessary as pandoc ignores them by default, but it simplifies the document, which is a good thing in principle
+** Switch off tracking and accept all changes
+// Important - pandoc recognizes the style name to define headings
+** Ensure you have used Heading styles for headings
+//** Remove automatic heading numbering (this limitation may be removed in the next release of pandoc)
+// So you can turn them back into captions just with a .
+** Ensure table titles are immediately *above* their table
+// So you can turn them back into captions just with a .
+** Ensure figure titles are immediately *above* their figure
+// linked images are ignored (according to my testing)
+** Ensure images are inserted as embedded files, not as links
+// canvases are ignored (according to my testing)
+** Remove canvases and put any images they contained into the main flow as paragraph images (this limitation may be removed in the next release of pandoc)
+// results of SEQ formulas are ignored (MS Word inserts them to generate figure and table numbers)
+** [[remove-refs]]Remove hyperlinks and replace all internal references and auto-generated sequence numbers with their literal values (kbd:[Ctrl+A], kbd:[Ctrl+Shift+F9])
+// No - this will turn manually applied list formatting back to plain text. Fine if you have used a list style though.
+// * Remove all non style-based formatting (kbd:[Ctrl+A], kbd:[Ctrl+space], kbd:[Ctrl+Q])
+// text boxes are ignored (according to my testing)
+** Remove text boxes and put their text into the main flow
+// Back to plain text.
+// Not sure about this - they don't show properly in PSPad, but look fine when converted to HTML.
+** Replace special characters: smart quotes with simple quotes, non-breaking hyphens with normal hyphens.
+** Remove all character formatting (kbd:[Ctrl+A], kbd:[Ctrl+B], kbd:[Ctrl+B], kbd:[Ctrl+I], kbd:[Ctrl+I], kbd:[Ctrl+U], kbd:[Ctrl+U])
+// pandoc just treats them as plain text as passes them through.
+** Optional: insert ids and cross references using AsciiDoc notation
+(You might find it easier doing it now rather than in the AsciiDoc document later.)
+// Not sure if it is significant, but pandoc seems to be designed against this spec, rather than the normal docx.
+** Save as "`Strict Open-xml document (docx)``"
+. Convert using pandoc as shown above.
+. Check that the output document looks OK, and that all images have been extracted.
++
+[NOTE]
+====
+If for some reason pandoc is not extracting images, you can always extract them by using unzip tool.
+Docx is just a zip file with a docx file extension.
+Embedded images are located in [.path}_word/media_ directory.
+
+ $ unzip input.docx -d input-docx
+   ls input-docx/word/media/
+
+====
+
+. Fix up the output, preferably with an editor that can do regular expressions:
+// tocs and cross refs introduce dozens of these. They are just noise.
+** Delete automatic ids (those beginning with underscores)
+// Style issue - pandoc seems to extend the line to cover the longest row
+** Replace long table delimiters with short ones.
+// Style issue
+** Insert line-breaks to get to 1 sentence per paragraph.
+// can do this with a regexp, but is depends on exactly what format you used for them
+** Re-insert images and turn caption paragraphs back into Asciidoctor captions.
+// can do this with a regexp, but is depends on exactly what format you used for them
+** Replace the hard cross references with AsciiDoc references.
+// checked vertical merge, assume h merge same
+** Fix tables - merged cells will have unmerged, column widths need putting back.
+. Try to convert it, and fix any errors that come up.
+// pandoc supposedly only uses UTF-8, and the xml file is windows encoded, but I haven't found any problems so far.
+// You definitely do get encoding errors if you go via HTML.
+
+The following are POSIX shell one-liners to automate some of these steps (adjust the regexps to match your particular document):
+
+* Delete automatically inserted ids
+
+ $ perl -W -pe  's!\[\[_.*]]!!g' -i output.adoc
+
+* Shorten table delimiters
+
+ $ perl -W -pe  's!\|==*!|====!g' -i output.adoc
+
+* 1 sentence per line.
+Be careful not to match lists.
+It will get confused by abbreviations, but there is no way around that.
+
+ $ perl -W -pe 's!(\w\w+)\.\s+(\w)!$1.\n$2!g' -i output.adoc
+
+* Replace figure captions with id and title
+
+ $ perl -W -pe 's!^Figure (\d+)\s?(.*)![[fig-$1]]\n.$2\n!g' -i output.adoc
+
+* Replace references to figures with asciidoc xref
+
+ $ perl -W -pe 's!Figure (\d+)!<<fig-$1>>!g' -i output.adoc
+
+== Google Docs
+
+Google Docs can already upload and edit MS Word docx files.
+Using the {url-google-asciidoc}[AsciiDoc Processor add-on^] by https://github.com/Mogztter[Guillaume Grossetie], you can copy and paste part or all of the document from Google Docs as AsciiDoc text.
+The features that it can handle seem to be substantially fewer than pandoc but expect further development.
+The source for the add-on can be found in {url-google-asciidoc-source}[its repository^].
+
+== Plain text
+
+This method is only useful for very small files or if the other methods are not available.
+
+It keeps the text, and _fixes_ fields like auto-numbered lists and cross references.
+
+It loses tables (converted to plain paragraphs), images, symbols, form fields, and textboxes.
+
+In MS Word, use "Save as > Plain text", then when the File Conversion dialog appears, set:
+
+* Other encoding: UTF-8
+* Do not insert line breaks
+* Allow character substitution
+
+Save the file then apply AsciiDoc markup manually.
+
+Experiment with the encoding.
+Try UTF-8 first, but if you get problems you can always revert to US-ASCII.
diff --git a/docs/modules/migrate/pages/upgrade.adoc b/docs/modules/migrate/pages/upgrade.adoc
new file mode 100644
index 00000000..9ad2d9fa
--- /dev/null
+++ b/docs/modules/migrate/pages/upgrade.adoc
@@ -0,0 +1,158 @@
+= Upgrade from Asciidoctor 1.5.x to 2.0
+//Syntax, Attributes, and Commands: What's Changed?
+
+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 Python, see xref:asciidoc-python.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="15,20,20,5,20"]
+|===
+|Feature |Deprecated |New |As of Version |Notes
+
+|_italic text_
+|pass:['italic text']
+|pass:[_italic text_]
+|1.5.0
+|Allowed with `compat-mode`
+
+|`monospace text`
+|pass:[+monospace text+]
+|pass:[`monospace text`]
+|1.5.0
+|Allowed with `compat-mode`
+
+|`+literal monospace text+`
+|pass:[`literal monospace text`]
+|pass:[`+literal monospace text+`]
+|1.5.0
+|Allowed with `compat-mode`
+
+|Curved "`double quotes`"
+|pass:[``double quotes'']
+|pass:["`double quotes`"], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8220;)
+|1.5.0
+|
+
+|Curved '`single quotes`'
+|pass:[`single quotes']
+|pass:['`single quotes`'], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8217;)
+|1.5.0
+|
+|===
+
+=== Table of contents
+
+[cols="15,20,20,5,20"]
+|===
+|Feature |Deprecated |New |As of Version |Notes
+
+|Scrollable, left margin TOC
+|`toc2`
+|`+:toc: left+`
+|1.5.0
+|
+
+|TOC location
+|`toc-placement` and `toc-position`
+|`+:toc: <value>+`
+|1.5.0
+|
+
+|User-specified TOC location
+|`+:toc-placement: manual+`
+|`+:toc: macro+`
+|1.5.0
+|
+
+|===
+
+=== Document header
+
+[cols="15,20,15,5,25"]
+|===
+|Feature |Deprecated |New |As of Version |Notes
+
+|Setext (i.e., two-line style) document title
+l|Title
+=====
+l|= 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.
+|===
+
+=== API
+
+[cols="15,20,20,5,20"]
+|===
+|Feature |Deprecated |New |As of Version |Notes
+
+|render class method
+|+.render(input, options = {}) ⇒ Object+
+|+.convert(input, options = {}) ⇒ Object+
+|1.5.7
+|
+|===
+
+== 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*.
+////
diff --git a/docs/modules/tooling/nav.adoc b/docs/modules/tooling/nav.adoc
new file mode 100644
index 00000000..31f850ee
--- /dev/null
+++ b/docs/modules/tooling/nav.adoc
@@ -0,0 +1 @@
+* xref:index.adoc[]
diff --git a/docs/modules/tooling/pages/index.adoc b/docs/modules/tooling/pages/index.adoc
new file mode 100644
index 00000000..2b573a82
--- /dev/null
+++ b/docs/modules/tooling/pages/index.adoc
@@ -0,0 +1,74 @@
+= AsciiDoc Tooling
+:url-chrome-extension: https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia
+:url-firefox-addon: https://addons.mozilla.org/en/firefox/addon/asciidoctorjs-live-preview
+:url-opera-extension: https://addons.opera.com/en/extensions/details/asciidoctorjs-live-preview/
+:url-asciidocfx: https://www.asciidocfx.com
+:url-asciidocfx-docs: https://www.asciidocfx.com/#truehow-to-install-asciidocfx
+:url-eclipse-marketplace: https://marketplace.eclipse.org/content/asciidoctor-editor
+:url-eclipse-plugin-github: https://github.com/de-jcup/eclipse-asciidoctor-editor
+:url-intellij-plugin: https://plugins.jetbrains.com/plugin/7391-asciidoc
+
+Since AsciiDoc syntax is just plain text, you can write an AsciiDoc document using any text editor.
+You don't need complex word processing programs like Microsoft Word or Google Docs.
+In fact, you shouldn't use these programs because they add cruft to your document that you can't see that makes conversion tedious.
+
+Here's an overview of the different ways to preview and edit your AsciiDoc documents.
+
+== Web browser add-ons (preview only)
+
+All you need to preview an AsciiDoc document in a web browser is to install the {url-chrome-extension}[Chrome extension^], the {url-firefox-addon}[Firefox add-on^] or the {url-opera-extension}[Opera extension^].
+Then you can see the AsciiDoc file rendered as HTML just by visiting it!
+
+== IDEs and text editors
+
+The following IDEs and text editors support the AsciiDoc syntax and provide document preview rendering with Asciidoctor.
+
+=== AsciiDocFX
+
+{url-asciidocfx}[AsciiDoc FX^] is an editor and terminal emulator written with JavaFX 8.
+See its documentation for {url-asciidocfx-docs}[download and installation instructions^].
+
+=== Atom
+
+Install https://atom.io/[Atom^].
+Then from the Atom editor menus, navigate to menu:Atom[Preferences].
+From there, open the menu:Packages[] tab and install:
+
+https://atom.io/packages/asciidoc-preview[AsciiDoc Preview^] :: enables live preview
+https://atom.io/packages/language-asciidoc[AsciiDoc Language^] :: enables syntax highlighting (AsciiDoc language support)
+https://atom.io/packages/asciidoc-image-helper[AsciiDoc Image Helper^] :: provides the ability to paste images from the clipboard
+https://atom.io/packages/autocomplete-asciidoc[AsciiDoc Autocomplete^] :: automatically completes AsciiDoc language items
+https://atom.io/packages/asciidoc-assistant[AsciiDoc Assistant^] :: Installs useful components to Atom for editing AsciiDoc files (including the above packages)
+
+=== Brackets
+
+Install http://brackets.io/[Brackets^].
+Then from the Brackets file menu, open the extension manager.
+Browse available extensions and install `AsciiDoc Preview`.
+
+More information:
+
+* https://github.com/asciidoctor/brackets-asciidoc-preview[AsciiDoc Preview for Brackets^]
+
+=== Eclipse
+
+Install the open source plugin `AsciiDoctor Editor` from the {url-eclipse-marketplace}[Eclipse Marketplace^] or visit the
+{url-eclipse-plugin-github}[project repository^].
+
+=== IntelliJ IDEA
+
+Install the community plugin {url-intellij-plugin}[AsciiDoc^].
+
+=== Visual Studio Code
+
+Visual Studio Code provides rich language support for AsciiDoc and a live preview as you type.
+
+. Install https://code.visualstudio.com/[Visual Studio Code^].
+. Launch Visual Studio Code and open the Quick Open dialog by pressing kbd:[Ctrl,P].
+. Type the following command to locate and install the AsciiDoc extension (by João Pinto):
++
+ ext install asciidoctor.asciidoctor-vscode
+
+More information:
+
+* https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[AsciiDoc extension for Visual Studio Code^]