From c3c7ddbda681cc8f44832b0549bb623d3eace748 Mon Sep 17 00:00:00 2001
From: Sarah White <graphitefriction@gmail.com>
Date: Wed, 18 Nov 2020 15:53:10 -0700
Subject: rearchitect modules and filenames and drop asciidoctor folder under
 docs

---
 docs/modules/ROOT/nav-converters.adoc              |   1 +
 docs/modules/ROOT/nav-docinfo.adoc                 |   3 +
 docs/modules/ROOT/nav-errors.adoc                  |   1 +
 docs/modules/ROOT/nav-lang.adoc                    |   1 +
 docs/modules/ROOT/nav-safe-modes.adoc              |   2 +
 docs/modules/ROOT/nav-top.adoc                     |   2 +
 .../ROOT/pages/attributes-and-safe-modes.adoc      |  46 +++
 docs/modules/ROOT/pages/converters.adoc            | 103 ++++++
 docs/modules/ROOT/pages/docinfo.adoc               | 255 +++++++++++++
 docs/modules/ROOT/pages/errors-and-warnings.adoc   | 262 ++++++++++++++
 docs/modules/ROOT/pages/features.adoc              |  67 ++++
 docs/modules/ROOT/pages/index.adoc                 |  97 +++++
 docs/modules/ROOT/pages/language-support.adoc      | 159 ++++++++
 docs/modules/ROOT/pages/safe-modes.adoc            |  83 +++++
 docs/modules/ROOT/pages/whats-new.adoc             | 403 +++++++++++++++++++++
 docs/modules/api/nav.adoc                          |   6 +
 docs/modules/api/pages/convert-strings.adoc        |  89 +++++
 docs/modules/api/pages/generate-html-toc.adoc      |  33 ++
 docs/modules/api/pages/index.adoc                  |  50 +++
 docs/modules/api/pages/load-templates.adoc         |  24 ++
 docs/modules/api/pages/options.adoc                | 165 +++++++++
 docs/modules/api/pages/set-safe-mode.adoc          |  18 +
 docs/modules/cli/nav.adoc                          |   6 +
 docs/modules/cli/pages/index.adoc                  |  32 ++
 docs/modules/cli/pages/io-piping.adoc              |  45 +++
 docs/modules/cli/pages/options.adoc                | 138 +++++++
 docs/modules/cli/pages/output-file.adoc            |  39 ++
 docs/modules/cli/pages/process-multiple-files.adoc |  48 +++
 docs/modules/cli/pages/set-safe-mode.adoc          |  19 +
 docs/modules/docbook-backend/nav.adoc              |   1 +
 docs/modules/docbook-backend/pages/index.adoc      |  82 +++++
 docs/modules/extensions/nav.adoc                   |  11 +
 .../extensions/pages/block-macro-processor.adoc    |  48 +++
 docs/modules/extensions/pages/block-processor.adoc |  45 +++
 .../extensions/pages/compound-block-processor.adoc |  56 +++
 .../extensions/pages/docinfo-processor.adoc        |  36 ++
 .../extensions/pages/include-processor.adoc        |  49 +++
 docs/modules/extensions/pages/index.adoc           |  51 +++
 .../extensions/pages/inline-macro-processor.adoc   |  48 +++
 docs/modules/extensions/pages/postprocessor.adoc   |  33 ++
 docs/modules/extensions/pages/preprocessor.adoc    |  66 ++++
 docs/modules/extensions/pages/register.adoc        |  25 ++
 docs/modules/extensions/pages/tree-processor.adoc  |  83 +++++
 docs/modules/get-started/nav.adoc                  |   1 +
 docs/modules/get-started/pages/index.adoc          |  50 +++
 .../html-backend/examples/mysample-data-uri.adoc   |  17 +
 .../html-backend/examples/mysample-link.adoc       |  13 +
 .../examples/mysample-stylesdir-link.adoc          |  15 +
 .../html-backend/examples/mysample-stylesdir.adoc  |  14 +
 .../html-backend/examples/mysample-stylesheet.adoc |  13 +
 docs/modules/html-backend/examples/mysample.adoc   |  12 +
 docs/modules/html-backend/examples/wrap.adoc       |  17 +
 docs/modules/html-backend/nav.adoc                 |   9 +
 .../html-backend/pages/apply-code-stylesheets.adoc |  27 ++
 .../html-backend/pages/apply-stylesheet.adoc       |  97 +++++
 docs/modules/html-backend/pages/favicon.adoc       |  48 +++
 docs/modules/html-backend/pages/index.adoc         |  81 +++++
 docs/modules/html-backend/pages/manage-images.adoc |  24 ++
 .../html-backend/pages/manage-stylesheets.adoc     |  46 +++
 .../html-backend/pages/skip-front-matter.adoc      |  30 ++
 .../html-backend/pages/verbatim-line-wrap.adoc     |  40 ++
 docs/modules/install/nav.adoc                      |   6 +
 docs/modules/install/pages/gem.adoc                |  67 ++++
 docs/modules/install/pages/index.adoc              |  17 +
 docs/modules/install/pages/linux.adoc              |  84 +++++
 docs/modules/install/pages/macos.adoc              |  23 ++
 .../modules/install/pages/supported-platforms.adoc |  45 +++
 docs/modules/install/pages/windows.adoc            |  18 +
 docs/modules/install/partials/success.adoc         |  12 +
 docs/modules/integrations/nav.adoc                 |   9 +
 docs/modules/integrations/pages/asciimath-gem.adoc |  39 ++
 docs/modules/integrations/pages/coderay.adoc       | 107 ++++++
 docs/modules/integrations/pages/highlightjs.adoc   |  42 +++
 docs/modules/integrations/pages/mathjax.adoc       |   7 +
 docs/modules/integrations/pages/pygments.adoc      | 156 ++++++++
 docs/modules/integrations/pages/rouge.adoc         |  70 ++++
 docs/modules/integrations/pages/stem.adoc          |  15 +
 .../integrations/pages/syntax-highlighters.adoc    |  26 ++
 docs/modules/manpage-backend/examples/manpage.adoc |  42 +++
 docs/modules/manpage-backend/nav.adoc              |   1 +
 docs/modules/manpage-backend/pages/index.adoc      | 116 ++++++
 docs/modules/migrate/examples/convert.groovy       |  43 +++
 docs/modules/migrate/nav.adoc                      |   7 +
 docs/modules/migrate/pages/asciidoc-python.adoc    | 368 +++++++++++++++++++
 docs/modules/migrate/pages/confluence-xhtml.adoc   |  29 ++
 docs/modules/migrate/pages/docbook-xml.adoc        |  19 +
 docs/modules/migrate/pages/markdown.adoc           |   6 +
 docs/modules/migrate/pages/ms-word.adoc            | 196 ++++++++++
 docs/modules/migrate/pages/upgrade.adoc            | 158 ++++++++
 docs/modules/tooling/nav.adoc                      |   1 +
 docs/modules/tooling/pages/index.adoc              |  74 ++++
 91 files changed, 5188 insertions(+)
 create mode 100644 docs/modules/ROOT/nav-converters.adoc
 create mode 100644 docs/modules/ROOT/nav-docinfo.adoc
 create mode 100644 docs/modules/ROOT/nav-errors.adoc
 create mode 100644 docs/modules/ROOT/nav-lang.adoc
 create mode 100644 docs/modules/ROOT/nav-safe-modes.adoc
 create mode 100644 docs/modules/ROOT/nav-top.adoc
 create mode 100644 docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
 create mode 100644 docs/modules/ROOT/pages/converters.adoc
 create mode 100644 docs/modules/ROOT/pages/docinfo.adoc
 create mode 100644 docs/modules/ROOT/pages/errors-and-warnings.adoc
 create mode 100644 docs/modules/ROOT/pages/features.adoc
 create mode 100644 docs/modules/ROOT/pages/index.adoc
 create mode 100644 docs/modules/ROOT/pages/language-support.adoc
 create mode 100644 docs/modules/ROOT/pages/safe-modes.adoc
 create mode 100644 docs/modules/ROOT/pages/whats-new.adoc
 create mode 100644 docs/modules/api/nav.adoc
 create mode 100644 docs/modules/api/pages/convert-strings.adoc
 create mode 100644 docs/modules/api/pages/generate-html-toc.adoc
 create mode 100644 docs/modules/api/pages/index.adoc
 create mode 100644 docs/modules/api/pages/load-templates.adoc
 create mode 100644 docs/modules/api/pages/options.adoc
 create mode 100644 docs/modules/api/pages/set-safe-mode.adoc
 create mode 100644 docs/modules/cli/nav.adoc
 create mode 100644 docs/modules/cli/pages/index.adoc
 create mode 100644 docs/modules/cli/pages/io-piping.adoc
 create mode 100644 docs/modules/cli/pages/options.adoc
 create mode 100644 docs/modules/cli/pages/output-file.adoc
 create mode 100644 docs/modules/cli/pages/process-multiple-files.adoc
 create mode 100644 docs/modules/cli/pages/set-safe-mode.adoc
 create mode 100644 docs/modules/docbook-backend/nav.adoc
 create mode 100644 docs/modules/docbook-backend/pages/index.adoc
 create mode 100644 docs/modules/extensions/nav.adoc
 create mode 100644 docs/modules/extensions/pages/block-macro-processor.adoc
 create mode 100644 docs/modules/extensions/pages/block-processor.adoc
 create mode 100644 docs/modules/extensions/pages/compound-block-processor.adoc
 create mode 100644 docs/modules/extensions/pages/docinfo-processor.adoc
 create mode 100644 docs/modules/extensions/pages/include-processor.adoc
 create mode 100644 docs/modules/extensions/pages/index.adoc
 create mode 100644 docs/modules/extensions/pages/inline-macro-processor.adoc
 create mode 100644 docs/modules/extensions/pages/postprocessor.adoc
 create mode 100644 docs/modules/extensions/pages/preprocessor.adoc
 create mode 100644 docs/modules/extensions/pages/register.adoc
 create mode 100644 docs/modules/extensions/pages/tree-processor.adoc
 create mode 100644 docs/modules/get-started/nav.adoc
 create mode 100644 docs/modules/get-started/pages/index.adoc
 create mode 100644 docs/modules/html-backend/examples/mysample-data-uri.adoc
 create mode 100644 docs/modules/html-backend/examples/mysample-link.adoc
 create mode 100644 docs/modules/html-backend/examples/mysample-stylesdir-link.adoc
 create mode 100644 docs/modules/html-backend/examples/mysample-stylesdir.adoc
 create mode 100644 docs/modules/html-backend/examples/mysample-stylesheet.adoc
 create mode 100644 docs/modules/html-backend/examples/mysample.adoc
 create mode 100644 docs/modules/html-backend/examples/wrap.adoc
 create mode 100644 docs/modules/html-backend/nav.adoc
 create mode 100644 docs/modules/html-backend/pages/apply-code-stylesheets.adoc
 create mode 100644 docs/modules/html-backend/pages/apply-stylesheet.adoc
 create mode 100644 docs/modules/html-backend/pages/favicon.adoc
 create mode 100644 docs/modules/html-backend/pages/index.adoc
 create mode 100644 docs/modules/html-backend/pages/manage-images.adoc
 create mode 100644 docs/modules/html-backend/pages/manage-stylesheets.adoc
 create mode 100644 docs/modules/html-backend/pages/skip-front-matter.adoc
 create mode 100644 docs/modules/html-backend/pages/verbatim-line-wrap.adoc
 create mode 100644 docs/modules/install/nav.adoc
 create mode 100644 docs/modules/install/pages/gem.adoc
 create mode 100644 docs/modules/install/pages/index.adoc
 create mode 100644 docs/modules/install/pages/linux.adoc
 create mode 100644 docs/modules/install/pages/macos.adoc
 create mode 100644 docs/modules/install/pages/supported-platforms.adoc
 create mode 100644 docs/modules/install/pages/windows.adoc
 create mode 100644 docs/modules/install/partials/success.adoc
 create mode 100644 docs/modules/integrations/nav.adoc
 create mode 100644 docs/modules/integrations/pages/asciimath-gem.adoc
 create mode 100644 docs/modules/integrations/pages/coderay.adoc
 create mode 100644 docs/modules/integrations/pages/highlightjs.adoc
 create mode 100644 docs/modules/integrations/pages/mathjax.adoc
 create mode 100644 docs/modules/integrations/pages/pygments.adoc
 create mode 100644 docs/modules/integrations/pages/rouge.adoc
 create mode 100644 docs/modules/integrations/pages/stem.adoc
 create mode 100644 docs/modules/integrations/pages/syntax-highlighters.adoc
 create mode 100644 docs/modules/manpage-backend/examples/manpage.adoc
 create mode 100644 docs/modules/manpage-backend/nav.adoc
 create mode 100644 docs/modules/manpage-backend/pages/index.adoc
 create mode 100644 docs/modules/migrate/examples/convert.groovy
 create mode 100644 docs/modules/migrate/nav.adoc
 create mode 100644 docs/modules/migrate/pages/asciidoc-python.adoc
 create mode 100644 docs/modules/migrate/pages/confluence-xhtml.adoc
 create mode 100644 docs/modules/migrate/pages/docbook-xml.adoc
 create mode 100644 docs/modules/migrate/pages/markdown.adoc
 create mode 100644 docs/modules/migrate/pages/ms-word.adoc
 create mode 100644 docs/modules/migrate/pages/upgrade.adoc
 create mode 100644 docs/modules/tooling/nav.adoc
 create mode 100644 docs/modules/tooling/pages/index.adoc

(limited to 'docs/modules')

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^]
-- 
cgit v1.2.3


From 46647208b1fb2f3ae3926843c99737662152780e Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Thu, 19 Nov 2020 01:12:37 -0700
Subject: update title of install parent page and rename some install pages

---
 docs/modules/install/nav.adoc                   |  4 +-
 docs/modules/install/pages/gem.adoc             | 67 --------------------
 docs/modules/install/pages/index.adoc           |  4 +-
 docs/modules/install/pages/linux-packaging.adoc | 84 +++++++++++++++++++++++++
 docs/modules/install/pages/linux.adoc           | 84 -------------------------
 docs/modules/install/pages/ruby-packaging.adoc  | 67 ++++++++++++++++++++
 docs/modules/install/pages/windows.adoc         |  4 +-
 7 files changed, 158 insertions(+), 156 deletions(-)
 delete mode 100644 docs/modules/install/pages/gem.adoc
 create mode 100644 docs/modules/install/pages/linux-packaging.adoc
 delete mode 100644 docs/modules/install/pages/linux.adoc
 create mode 100644 docs/modules/install/pages/ruby-packaging.adoc

(limited to 'docs/modules')

diff --git a/docs/modules/install/nav.adoc b/docs/modules/install/nav.adoc
index afd431e0..6908b431 100644
--- a/docs/modules/install/nav.adoc
+++ b/docs/modules/install/nav.adoc
@@ -1,6 +1,6 @@
 * xref:index.adoc[]
 ** xref:supported-platforms.adoc[]
-** xref:gem.adoc[]
-** xref:linux.adoc[]
+** xref:ruby-packaging.adoc[]
+** xref:linux-packaging.adoc[]
 ** xref:macos.adoc[]
 ** xref:windows.adoc[]
diff --git a/docs/modules/install/pages/gem.adoc b/docs/modules/install/pages/gem.adoc
deleted file mode 100644
index af8b116f..00000000
--- a/docs/modules/install/pages/gem.adoc
+++ /dev/null
@@ -1,67 +0,0 @@
-= 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
index bdc1c57d..67ecc0b0 100644
--- a/docs/modules/install/pages/index.adoc
+++ b/docs/modules/install/pages/index.adoc
@@ -1,4 +1,4 @@
-= Install Asciidoctor
+= Install and Update
 
 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.
@@ -15,3 +15,5 @@ Asciidoctor can be installed using:
 * 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.
+
+You should use the same method to update Asciidoctor as you use to install it.
diff --git a/docs/modules/install/pages/linux-packaging.adoc b/docs/modules/install/pages/linux-packaging.adoc
new file mode 100644
index 00000000..5df8c1f0
--- /dev/null
+++ b/docs/modules/install/pages/linux-packaging.adoc
@@ -0,0 +1,84 @@
+= Install Using Linux Packaging
+: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.
+
+== Package versions
+
+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:ruby-packaging.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:ruby-packaging.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/linux.adoc b/docs/modules/install/pages/linux.adoc
deleted file mode 100644
index a2b605f6..00000000
--- a/docs/modules/install/pages/linux.adoc
+++ /dev/null
@@ -1,84 +0,0 @@
-= 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/ruby-packaging.adoc b/docs/modules/install/pages/ruby-packaging.adoc
new file mode 100644
index 00000000..ea9e0994
--- /dev/null
+++ b/docs/modules/install/pages/ruby-packaging.adoc
@@ -0,0 +1,67 @@
+= Install Using Ruby Packaging
+
+[#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/windows.adoc b/docs/modules/install/pages/windows.adoc
index ae25d23e..2248b0b1 100644
--- a/docs/modules/install/pages/windows.adoc
+++ b/docs/modules/install/pages/windows.adoc
@@ -11,8 +11,8 @@ When you already use https://chocolatey.org[chocolatey^] on your machine, you ca
 choco install ruby
 ----
 
-Then follow the xref:gem.adoc[gem installation instructions].
+Then follow the xref:ruby-packaging.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].
+Or you use the https://rubyinstaller.org/downloads/[Rubyinstaller^], download the package for your Windows Version and after the installation, then follow the xref:ruby-packaging.adoc[gem installation instructions].
-- 
cgit v1.2.3


From a313298c205b18b9e2c71926401f50146a3bccc5 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Thu, 19 Nov 2020 01:17:31 -0700
Subject: add :standalone option to Ruby API options; list :header_footer as
 deprecated alias

---
 docs/modules/ROOT/pages/attributes-and-safe-modes.adoc |  4 ++--
 docs/modules/api/pages/convert-strings.adoc            | 14 +++++++-------
 docs/modules/api/pages/load-templates.adoc             |  4 ++--
 docs/modules/api/pages/options.adoc                    | 11 +++++++----
 docs/modules/html-backend/pages/favicon.adoc           |  2 +-
 5 files changed, 19 insertions(+), 16 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc b/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
index 4d28d210..1d18c502 100644
--- a/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
+++ b/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
@@ -36,11 +36,11 @@ Example:
 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:
+I decided the following defaults for the standalone 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.
+The reason I think the standalone 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/api/pages/convert-strings.adoc b/docs/modules/api/pages/convert-strings.adoc
index 1f4a102a..6eec4faf 100644
--- a/docs/modules/api/pages/convert-strings.adoc
+++ b/docs/modules/api/pages/convert-strings.adoc
@@ -45,26 +45,26 @@ Here's what's included in an embedded document:
 == 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`.
+To convert from an AsciiDoc string to a standalone output document, you need to explicitly set the `standalone` option to `true`.
 
 [source,ruby]
 ----
-puts Asciidoctor.convert '*This* is Asciidoctor.', header_footer: true
+puts Asciidoctor.convert '*This* is Asciidoctor.', standalone: 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.
+When the input or output is a file, the `standalone` 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`.
+If you want to generate embedded output when starting with a file, set the `standalone` 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).
+When converting a string, the TOC is only included by default when using the `standalone` 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
@@ -81,9 +81,9 @@ In this mode, Asciidoctor will only process the first block (e.g., paragraph) in
 == 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`.
+Since embeddable DocBook isn't that useful, we also enable the standalone document (i.e., header and footer) by setting the `standalone` option to `true`.
 
 [source,ruby]
 ----
-puts Asciidoctor.convert '*This* is Asciidoctor.', header_footer: true, backend: 'docbook'
+puts Asciidoctor.convert '*This* is Asciidoctor.', standalone: true, backend: 'docbook'
 ----
diff --git a/docs/modules/api/pages/load-templates.adoc b/docs/modules/api/pages/load-templates.adoc
index 487ecd57..2f9a16f1 100644
--- a/docs/modules/api/pages/load-templates.adoc
+++ b/docs/modules/api/pages/load-templates.adoc
@@ -8,8 +8,8 @@ It will fallback to its default templates for everything else.
 
 [source,ruby]
 ----
-puts Asciidoctor.convert '*This* is Asciidoctor.', :header_footer => true,
-  :template_dir => 'templates'
+puts Asciidoctor.convert '*This* is Asciidoctor.',
+  standalone: true, template_dir: 'templates'
 ----
 
 The Document and Section templates should begin with `document` and `section`, respectively.
diff --git a/docs/modules/api/pages/options.adoc b/docs/modules/api/pages/options.adoc
index 5a498567..fe4fc0ac 100644
--- a/docs/modules/api/pages/options.adoc
+++ b/docs/modules/api/pages/options.adoc
@@ -74,10 +74,13 @@ Instead of providing a Ruby block containing extensions to register, this option
 |`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
+|:standalone
+|If true, generate a standalone output document (which includes the shell around the body content, such as the header and footer).
+When converting to a file, the default value is `true`.
+Otherwise, the default value is `false`.
+The deprecated alias for this option is `:header_footer`.
+Note that the default value for this option is opposite of the default value for the CLI.
+|_contingent_
 |_boolean_
 |`-s`, `--no-header-footer`
 
diff --git a/docs/modules/html-backend/pages/favicon.adoc b/docs/modules/html-backend/pages/favicon.adoc
index 34a8f15d..a6400aff 100644
--- a/docs/modules/html-backend/pages/favicon.adoc
+++ b/docs/modules/html-backend/pages/favicon.adoc
@@ -1,6 +1,6 @@
 = 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.
+When using Asciidoctor to generate a standalone HTML document (i.e., the `standalone` 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]
 ----
-- 
cgit v1.2.3


From a0861ee354c26ab4480835c5f03ff16e7016ce61 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Thu, 19 Nov 2020 04:11:42 -0700
Subject: rewrite features page in docs

---
 docs/modules/ROOT/images/source-vs-output.png | Bin 0 -> 153432 bytes
 docs/modules/ROOT/pages/features.adoc         | 212 ++++++++++++++++++--------
 docs/modules/ROOT/pages/index.adoc            |   4 +-
 3 files changed, 147 insertions(+), 69 deletions(-)
 create mode 100644 docs/modules/ROOT/images/source-vs-output.png

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/images/source-vs-output.png b/docs/modules/ROOT/images/source-vs-output.png
new file mode 100644
index 00000000..2f49193f
Binary files /dev/null and b/docs/modules/ROOT/images/source-vs-output.png differ
diff --git a/docs/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc
index f5ed7914..29d45840 100644
--- a/docs/modules/ROOT/pages/features.adoc
+++ b/docs/modules/ROOT/pages/features.adoc
@@ -1,67 +1,145 @@
-= 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.
-////
+= Features
+
+This page covers the features of Asciidoctor that make it a great choice for processing and publishing your AsciiDoc content.
+
+== Readily available with no dependencies
+
+Asciidoctor is written in Ruby, which means it must be run on a Ruby language runtime (including JRuby).
+But that's its only requirement.
+Asciidoctor is packaged and distributed as a RubyGem (aka gem) to the main package repository at https://rubygems.org[RubyGems.org^].
+What that means is that the gem can be installed on *any operating system* Ruby supports using Ruby's package management tools (gem or bundle).
+Asciidoctor itself has no dependencies.
+
+But what if you aren't familiar with Ruby or, for whatever reason, prefer not to install it?
+No problem!
+Thanks to {url-asciidoctorj}[AsciidoctorJ^] and xref:asciidoctor.js::index.adoc[Asciidoctor.js], you can run the same exact version of Asciidoctor on a Java Virtual Machine (JVM) or JavaScript runtime, respectively.
+That means you _don't_ need a Ruby runtime installed on your machine after all.
+(AsciidoctorJ uses JRuby internally, whereas Asciidoctor.js relies on a Ruby-like runtime written in JavaScript).
+
+Whether your working in Ruby, Java, or JavaScript, Asciidoctor is readily available for you to start using.
+(Only when you get into extended converters and extensions do you need to install dependencies).
+
+== Quick wins
+
+Asciidoctor provides a really nice out-of-the-box xref:html-backend:index.adoc[HTML experience], complete with a default stylesheet and built-in integrations like Font Awesome (for icons), Highlight.js (for source highlighting), and MathJax (for STEM processing).
+When you're just getting into using AsciiDoc for writing, Asciidoctor's HTML output should be sufficient for all of your publishing needs.
+
+The following before and after picture should give you an idea of what to expect:
+
+image::source-vs-output.png[AsciiDoc source vs HTML output]
+
+If you're looking for more advanced output, or you have an existing DocBook toolchain in place, you can instead xref:docbook-backend:index.adoc[convert to DocBook] and feed the result into that pipeline.
+Once you get more familiar with AsciiDoc and Asciidoctor, you can explore customizing the built-in converter using templates or using extended converters to produce other output formats such as PDF and EPUB 3.
+So there is plenty of room to grow.
+
+== Built-in and extended converters
+
+Asciidoctor provides converters for three output formats by default: xref:html-backend:index.adoc[HTML 5], xref:docbook-backend:index.adoc[DocBook 5], and xref:manpage-backend:index.adoc[manpage] (manual page).
+These converters are designed to cover a majority of users`' needs for basic preview and publishing.
+
+The *HTML* converter gives you a result you can publish the web straight away without any tweaking.
+The *DocBook* converter allows you to either leverage an existing publishing toolchain or migrate the content to a different authoring format (without the tool needing to know how to parse AsciiDoc).
+The *manpage* converter drastically lowers the barrier to making system help files.
+
+But it doesn't end there.
+The converter interface in Asciidoctor is an extension point.
+That means it can be used to create converters for any output format imaginable.
+And there's an ecosystem of additional converters already available in the Asciidoctor project.
+You can find converters for creating *PDF*, *EPUB 3*, *Reveal.js slides*, and more from AsciiDoc.
+Asciidoctor also provides advanced docinfo support for injecting colophon (such as content scripts) into the header and footer of the output file.
+
+A single input format, AsciiDoc, gains you a plethora of output formats.
+
+== Custom converter or templates
+
+While Asciidoctor provides a built-in converter for producing publish-ready HTML, *all the HTML that Asciidoctor generates can be changed.*
+There are two ways to modify the HTML that Asciidoctor produces: a custom converter or converter templates.
+
+If you're an experienced programmer, you may lean towards the *custom converter*.
+You can extend the built-in HTML converter and override the methods for that handles the conversion for any node in the document tree.
+
+If you're expertise is more on the technical writing side, you may find the *converter templates* to be more approachable.
+The templates can be written in any template language supported by the Tilt template abstraction library, such as ERB, Haml, or Slim.
+These templates augment the built-in converter by replacing the processing for a node in the document.
+You introduce one template for each type of node for which you want to control conversion.
+Templates allow you to apply logic around chunks of HTML (or HTML-like) markup.
+
+Just know that if the HTML that Asciidoctor produces isn't working for you, you can change it.
+
+== Syntax highlighting
+
+If you're writing technical documentation that presents snippets of source code or configuration, you can enhance the display of those source blocks using syntax highlighting (aka source highlighting).
+Syntax highlighting is the practice of colorizing (or otherwise emphasizing) keywords and syntax elements in a structured programming or configuration language.
+Here's an example to give you an idea:
+
+[source,ruby]
+----
+phrase = "I love AsciiDoc"
+puts phrase
+
+# now say it like you mean it
+5.times { puts %(#{phrase}!) }
+----
+
+Asciidoctor provides adapters for several popular syntax highlighters, including Rouge and Highlight.js.
+Aside from installing the library (if necessary), all you need to do is set an document attribute on your document and Asciidoctor will handle the rest.
+From there, you can configure the behavior of the syntax highlighter, such as changing the style/theme, enabling line numbers, and block highlighting select lines.
+
+== Multiple interfaces: CLI and API
+
+Asciidoctor offers two interfaces for processing AsciiDoc content: a commandline interface (CLI) and an application programming interface (API).
+
+The *CLI* is designed as a simple tool for non-programmers who want to convert AsciiDoc without having to write a program or for converting content in an automated environment such as CI.
+Many of the processing options are accessible from the CLI using option flags.
+When you're first starting out with Asciidoctor, you'll mostly likely interact with it via the CLI.
+Although the CLI itself does not require any programming, it can still load extension code that auguments processing.
+
+NOTE: If you're migrating from AsciiDoc.py, the `asciidoctor` CLI is a drop-in replacement for the `asciidoc` CLI.
+
+The *API* is designed for programmers who want to take their AsciiDoc processing further.
+Like with the CLI, you can use the API to convert documents.
+But it's not all about conversion to an output format.
+//Alternately, you can load the document just to inspect its contents.
+Asciidoctor parses and converts the source document in discrete steps.
+This makes conversion optional and gives programs the opportunity to extract, add, or replace content in the document by interacting with the document object model.
+//Developers can use the full power of the Ruby programming language to play with the content in the document.
+Or you may want to leverage the ability to convert to an embedded document for integrating with other applications, such as a static site generator.
+The API also provides an extension SPI that you can use to augment the processor, such as to introduce new syntax, mutate the parsed document before conversion, or tweak the output after conversion.
+
+TIP: The API is written in Ruby, but also accessible from JVM languages or JavaScript when using AsciidoctorJ or Asciidoctor.js, respectively.
+
+Both the CLI and API have the ability to process both AsciiDoc files and AsciiDoc source passed in as a string.
+
+== Impressive performance and strong security
+
+No coverage of Asciidoctor would be complete without mention of its speed.
+Asciidoctor is about as fast as any program that runs in Ruby can be.
+It can load, parse, and convert a 100K AsciiDoc document in about a tenth of a second (~ 1MB/s).
+That's more than 100x as fast as AsciiDoc.py, the original AsciiDoc implementation.
+
+Asciidoctor's speed is good news for developer productivity and good news for server-side applications that need to convert AsciiDoc markup.
+It also means that preview tools like the browser extension can present a preview of the AsciiDoc content in HTML in near real time.
+
+Asciidoctor also has the ability to run securely by offering several xref:safe-modes.adoc[security (aka safe) modes].
+By using one of these safe modes, you don't have to worry about the processor accessing sensitive files or even the file system in highly secure environments.
+In addition to its performance, these security levels make Asciidoctor well-suited for server-side deployments.
+
+== Access to an ecosystem of extensions and tools
+
+Installating Asciidoctor is just the beginning of your publishing experience.
+Asciidoctor gives you access to a {url-org}[healthy ecosystem of extensions and tools], ranging from converters, to extended syntax, to build plugins, to integrated writing and preview environments.
+
+One popular extension is {url-org}/asciidoctor-diagram[Asciidoctor Diagram].
+When loaded, Asciidoctor Diagram allows you to make diagrams from plain text (much like AsciiDoc does for writing).
+Asciidoctor Diagram does this by extending the syntax of AsciiDoc to recognize specially marked literal blocks.
+It takes the text inside those blocks, passes it through one of the diagramming tools it integrates with, and reinserts the image back into the document as it is being processed.
+The result is that the diagram source in the AsciiDoc document becomes an image in the generated output.
+
+One popular tool is the {url-org}/asciidoctor-browser-extension[browser extension].
+When this extension is installed, you can browse to an AsciiDoc file on your harddisk or on the web and the browser will show you the converted HTML *instead of* the AsciiDoc source.
+That means you can get the out-of-the-box HTML experience that Asciidoctor provides without even having to run a command or script.
+The extension running in the browser does everything for you.
+
+These are just two examples.
+There are plenty more possibilities to explore in the ever-growing Asciidoctor ecosystem.
+All the components of this ecosystem work together to achieve one goal, to make writing in AsciiDoc a rewording and productive experience.
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index 637ce9f3..2099f30c 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -15,7 +15,7 @@ If you're looking for the documentation for the AsciiDoc language itself, refer
 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.
+The asciidoctor gem can be installed on all major operating systems using Ruby packaging tools (gem or bundle).
 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^].
@@ -80,7 +80,7 @@ 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).
+Thanks to {url-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.
-- 
cgit v1.2.3


From 64ec52d2dacb0ff9c5e54ff47bc35f56a67b18ea Mon Sep 17 00:00:00 2001
From: Sarah White <graphitefriction@gmail.com>
Date: Thu, 19 Nov 2020 15:45:59 -0700
Subject: create integration modules; update stylesheet pages

---
 docs/modules/ROOT/nav-safe-modes.adoc              |   2 +-
 .../ROOT/pages/attributes-and-safe-modes.adoc      |  46 ------
 docs/modules/ROOT/pages/language-support.adoc      |  46 +++---
 docs/modules/ROOT/pages/reference-safe-mode.adoc   |  45 ++++++
 docs/modules/ROOT/pages/safe-modes.adoc            |   6 +-
 docs/modules/api/pages/set-safe-mode.adoc          |   5 +-
 docs/modules/cli/pages/process-multiple-files.adoc |   2 +-
 docs/modules/cli/pages/set-safe-mode.adoc          |   7 +-
 docs/modules/html-backend/nav.adoc                 |   4 +-
 .../html-backend/pages/apply-code-stylesheets.adoc |  27 ----
 .../html-backend/pages/apply-stylesheet.adoc       |  97 -------------
 .../html-backend/pages/custom-stylesheets.adoc     |  97 +++++++++++++
 docs/modules/html-backend/pages/index.adoc         |   2 +-
 .../html-backend/pages/manage-stylesheets.adoc     |  11 +-
 .../pages/source-highlighting-stylesheets.adoc     |  27 ++++
 docs/modules/integrations/nav.adoc                 |   9 --
 docs/modules/integrations/pages/asciimath-gem.adoc |  39 ------
 docs/modules/integrations/pages/coderay.adoc       | 107 --------------
 docs/modules/integrations/pages/highlightjs.adoc   |  42 ------
 docs/modules/integrations/pages/mathjax.adoc       |   7 -
 docs/modules/integrations/pages/pygments.adoc      | 156 ---------------------
 docs/modules/integrations/pages/rouge.adoc         |  70 ---------
 docs/modules/integrations/pages/stem.adoc          |  15 --
 .../integrations/pages/syntax-highlighters.adoc    |  26 ----
 docs/modules/manpage-backend/pages/index.adoc      |  35 ++---
 docs/modules/migrate/pages/asciidoc-python.adoc    |   2 +-
 docs/modules/source-highlighters/nav.adoc          |   5 +
 .../modules/source-highlighters/pages/coderay.adoc | 107 ++++++++++++++
 .../source-highlighters/pages/highlightjs.adoc     |  42 ++++++
 docs/modules/source-highlighters/pages/index.adoc  |  32 +++++
 .../source-highlighters/pages/pygments.adoc        | 156 +++++++++++++++++++++
 docs/modules/source-highlighters/pages/rouge.adoc  |  70 +++++++++
 docs/modules/stem/nav.adoc                         |   3 +
 docs/modules/stem/pages/asciimath-gem.adoc         |  39 ++++++
 docs/modules/stem/pages/index.adoc                 |  14 ++
 docs/modules/stem/pages/mathjax.adoc               |   7 +
 36 files changed, 708 insertions(+), 699 deletions(-)
 delete mode 100644 docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
 create mode 100644 docs/modules/ROOT/pages/reference-safe-mode.adoc
 delete mode 100644 docs/modules/html-backend/pages/apply-code-stylesheets.adoc
 delete mode 100644 docs/modules/html-backend/pages/apply-stylesheet.adoc
 create mode 100644 docs/modules/html-backend/pages/custom-stylesheets.adoc
 create mode 100644 docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc
 delete mode 100644 docs/modules/integrations/nav.adoc
 delete mode 100644 docs/modules/integrations/pages/asciimath-gem.adoc
 delete mode 100644 docs/modules/integrations/pages/coderay.adoc
 delete mode 100644 docs/modules/integrations/pages/highlightjs.adoc
 delete mode 100644 docs/modules/integrations/pages/mathjax.adoc
 delete mode 100644 docs/modules/integrations/pages/pygments.adoc
 delete mode 100644 docs/modules/integrations/pages/rouge.adoc
 delete mode 100644 docs/modules/integrations/pages/stem.adoc
 delete mode 100644 docs/modules/integrations/pages/syntax-highlighters.adoc
 create mode 100644 docs/modules/source-highlighters/nav.adoc
 create mode 100644 docs/modules/source-highlighters/pages/coderay.adoc
 create mode 100644 docs/modules/source-highlighters/pages/highlightjs.adoc
 create mode 100644 docs/modules/source-highlighters/pages/index.adoc
 create mode 100644 docs/modules/source-highlighters/pages/pygments.adoc
 create mode 100644 docs/modules/source-highlighters/pages/rouge.adoc
 create mode 100644 docs/modules/stem/nav.adoc
 create mode 100644 docs/modules/stem/pages/asciimath-gem.adoc
 create mode 100644 docs/modules/stem/pages/index.adoc
 create mode 100644 docs/modules/stem/pages/mathjax.adoc

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/nav-safe-modes.adoc b/docs/modules/ROOT/nav-safe-modes.adoc
index be07ed4d..2d362d52 100644
--- a/docs/modules/ROOT/nav-safe-modes.adoc
+++ b/docs/modules/ROOT/nav-safe-modes.adoc
@@ -1,2 +1,2 @@
 * xref:safe-modes.adoc[]
-** xref:attributes-and-safe-modes.adoc[]
+** xref:reference-safe-mode.adoc[]
diff --git a/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc b/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
deleted file mode 100644
index 1d18c502..00000000
--- a/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-= 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 standalone 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 standalone 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/language-support.adoc b/docs/modules/ROOT/pages/language-support.adoc
index 4af521ff..362411d0 100644
--- a/docs/modules/ROOT/pages/language-support.adoc
+++ b/docs/modules/ROOT/pages/language-support.adoc
@@ -39,85 +39,85 @@ If you're not using the DocBook toolchain for publishing, you must translate eac
 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]
+[%autowidth,cols="m,,"]
 |===
-|Attribute name |Used for |Default
+|Attribute |Default English Value |Notes
 
 |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
+|Applies only when `doctype` is `book`.
+PDF converter only.
 
 |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_
+|By default, listing blocks do not have captions.
+Specify `listing-caption` to turn on listing block captions.
 
 |manname-title
-|Label for the program name section in the man page.
 |NAME
+|Applies only when `doctype` is `manpage`.
 
 |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_
+|Applies only when `doctype` is `book`.
 
 |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.
+If you plan to support multiple languages, you'll want to define the attributes for each language inside a xref:asciidoc:directives:conditionals.adoc[conditional preprocessor directive].
 For example:
 
-[source]
+[source,asciidoc]
 ----
 \ifeval::["{lang}" == "de"]
 :caution-caption: Achtung
diff --git a/docs/modules/ROOT/pages/reference-safe-mode.adoc b/docs/modules/ROOT/pages/reference-safe-mode.adoc
new file mode 100644
index 00000000..8c5b47b2
--- /dev/null
+++ b/docs/modules/ROOT/pages/reference-safe-mode.adoc
@@ -0,0 +1,45 @@
+= Safe Mode Specific Content
+// anchor: set-safe-attrs
+
+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.
+
+== Referencing safe modes
+
+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 standalone 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 standalone 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/safe-modes.adoc b/docs/modules/ROOT/pages/safe-modes.adoc
index 3e06f836..c8ac7d8f 100644
--- a/docs/modules/ROOT/pages/safe-modes.adoc
+++ b/docs/modules/ROOT/pages/safe-modes.adoc
@@ -1,6 +1,6 @@
 = 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.
+Asciidoctor provides security levels that control the read and write access of attributes, include directives, macros, and scripts while a document is processing.
 Each level includes the restrictions enabled in the prior security level.
 
 == Safe mode levels
@@ -48,7 +48,7 @@ Additionally, it:
 * 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.
+xref:extensions:index.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`.
@@ -80,4 +80,4 @@ 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].
+You can also xref:reference-safe-mode.adoc[enable or disable content based on the current safe mode].
diff --git a/docs/modules/api/pages/set-safe-mode.adoc b/docs/modules/api/pages/set-safe-mode.adoc
index dcf13af6..8ff65b5d 100644
--- a/docs/modules/api/pages/set-safe-mode.adoc
+++ b/docs/modules/api/pages/set-safe-mode.adoc
@@ -3,6 +3,9 @@
 
 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.
+
+== Set :safe option
+
 The value must be set in the document constructor using the `:safe` option.
 
  result = Asciidoctor.convert_file('master.adoc', :safe => 'server')
@@ -15,4 +18,4 @@ 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].
+You can also set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and xref:ROOT:reference-safe-mode.adoc[enable or disable content based on the current safe mode].
diff --git a/docs/modules/cli/pages/process-multiple-files.adoc b/docs/modules/cli/pages/process-multiple-files.adoc
index 0d565b77..db6368e5 100644
--- a/docs/modules/cli/pages/process-multiple-files.adoc
+++ b/docs/modules/cli/pages/process-multiple-files.adoc
@@ -45,4 +45,4 @@ 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].
+CAUTION: To process multiple nested AsciiDoc files at once and apply a custom stylesheet, you'll need to xref:html-backend:custom-stylesheets.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
index 31110060..66db3565 100644
--- a/docs/modules/cli/pages/set-safe-mode.adoc
+++ b/docs/modules/cli/pages/set-safe-mode.adoc
@@ -1,7 +1,10 @@
 = Set the Safe Mode Using the CLI
-:navtitle: Set the Safe Mode
+:navtitle: Set Safe Mode
 
 When Asciidoctor is invoked via the CLI, the xref:ROOT:safe-modes.adoc[safe mode] is set to `UNSAFE` by default.
+
+== Assign safe mode level
+
 You can change the security level by executing one of the following commands:
 
 `-S`, `--safe-mode=SAFE_MODE`::
@@ -16,4 +19,4 @@ Provided for compatibility with the python AsciiDoc `safe` command.
 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].
+You can also set the xref:api:set-safe-mode.adoc[safe mode from the API] and xref:ROOT:reference-safe-mode.adoc[enable or disable content based on the current safe mode].
diff --git a/docs/modules/html-backend/nav.adoc b/docs/modules/html-backend/nav.adoc
index aa1054cb..396b226a 100644
--- a/docs/modules/html-backend/nav.adoc
+++ b/docs/modules/html-backend/nav.adoc
@@ -1,7 +1,7 @@
 * xref:index.adoc[]
 ** xref:manage-stylesheets.adoc[]
-** xref:apply-code-stylesheets.adoc[]
-** xref:apply-stylesheet.adoc[]
+** xref:source-highlighting-stylesheets.adoc[]
+** xref:custom-stylesheets.adoc[]
 ** xref:favicon.adoc[]
 ** xref:manage-images.adoc[]
 ** xref:favicon.adoc[]
diff --git a/docs/modules/html-backend/pages/apply-code-stylesheets.adoc b/docs/modules/html-backend/pages/apply-code-stylesheets.adoc
deleted file mode 100644
index 42be39cb..00000000
--- a/docs/modules/html-backend/pages/apply-code-stylesheets.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-= 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
deleted file mode 100644
index e645e664..00000000
--- a/docs/modules/html-backend/pages/apply-stylesheet.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-= 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/custom-stylesheets.adoc b/docs/modules/html-backend/pages/custom-stylesheets.adoc
new file mode 100644
index 00000000..1cc20d2a
--- /dev/null
+++ b/docs/modules/html-backend/pages/custom-stylesheets.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 xref:manage-stylesheets.adoc[default stylesheet], you can have the output document link to or embed your custom stylesheet.
+
+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/index.adoc b/docs/modules/html-backend/pages/index.adoc
index 5c562bdb..be3c9ec3 100644
--- a/docs/modules/html-backend/pages/index.adoc
+++ b/docs/modules/html-backend/pages/index.adoc
@@ -9,7 +9,7 @@ Asciidoctor's default output format is HTML.
 
 == 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.
+In this section, we'll create a sample document, then process and convert it with Asciidoctor's built-in HTML converter.
 
 . Create an AsciiDoc file like the one below
 . Save the file as [.path]_my-sample.adoc_
diff --git a/docs/modules/html-backend/pages/manage-stylesheets.adoc b/docs/modules/html-backend/pages/manage-stylesheets.adoc
index aa6042b3..781c736e 100644
--- a/docs/modules/html-backend/pages/manage-stylesheets.adoc
+++ b/docs/modules/html-backend/pages/manage-stylesheets.adoc
@@ -3,13 +3,12 @@
 == 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.
+The built-in HTML converter uses this stylesheet for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes.
+Asciidoctor applies this stylesheet by default unless you tell Asciidoctor to use another stylesheet.
 
 == 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`.
+When you generate a document using the built-in HTML converter, the [.path]_asciidoctor.css_ stylesheet is embedded into the HTML output by default when the xref:ROOT:safe-modes.adoc[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
@@ -37,10 +36,10 @@ Additionally, you can inspect [.path]_my-sample.html_ in your browser and see `<
 //image::mysample-link.png[]
 ====
 
-== Don't apply a stylesheet
+== Disable 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].
+One of Asciidoctor's strengths is the ease in which you can swap the default stylesheet for your own xref:custom-stylesheets.adoc[custom stylesheet].
diff --git a/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc b/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc
new file mode 100644
index 00000000..0b9ad08a
--- /dev/null
+++ b/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc
@@ -0,0 +1,27 @@
+= Embed a CodeRay or Pygments Stylesheet
+// 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:source-highlighters:rouge.adoc[], xref:source-highlighters:coderay.adoc[], or xref:source-highlighters: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/integrations/nav.adoc b/docs/modules/integrations/nav.adoc
deleted file mode 100644
index b6d8da60..00000000
--- a/docs/modules/integrations/nav.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-* 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
deleted file mode 100644
index 5d9e82d7..00000000
--- a/docs/modules/integrations/pages/asciimath-gem.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-= 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
deleted file mode 100644
index 7a590b8a..00000000
--- a/docs/modules/integrations/pages/coderay.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-= 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
deleted file mode 100644
index 17372031..00000000
--- a/docs/modules/integrations/pages/highlightjs.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-= 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
deleted file mode 100644
index b27c7928..00000000
--- a/docs/modules/integrations/pages/mathjax.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-= 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
deleted file mode 100644
index 9456955b..00000000
--- a/docs/modules/integrations/pages/pygments.adoc
+++ /dev/null
@@ -1,156 +0,0 @@
-= 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
deleted file mode 100644
index b6022864..00000000
--- a/docs/modules/integrations/pages/rouge.adoc
+++ /dev/null
@@ -1,70 +0,0 @@
-= 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
deleted file mode 100644
index 809dfa16..00000000
--- a/docs/modules/integrations/pages/stem.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-= 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
deleted file mode 100644
index a8354393..00000000
--- a/docs/modules/integrations/pages/syntax-highlighters.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-= 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/pages/index.adoc b/docs/modules/manpage-backend/pages/index.adoc
index 31386990..346fa25a 100644
--- a/docs/modules/manpage-backend/pages/index.adoc
+++ b/docs/modules/manpage-backend/pages/index.adoc
@@ -1,5 +1,5 @@
-= Generate Man Pages from AsciiDoc
-:navtitle: Generate Man Pages
+= Generate Manual Pages from AsciiDoc
+:navtitle: Generate Manual 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
@@ -11,11 +11,11 @@ Asciidoctor's built-in man page converter generates {url-man7}[roff-formatted^]
 == 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.
+The formalized structure of its content allows the `man` command to present the manual 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`.
+Before running Asciidoctor, make sure your source document adheres to the <<doctype,manpage doctype structure>> and the `doctype` attribute is assigned the value `manpage`.
 
 To generate a man page, run:
 
@@ -42,6 +42,7 @@ Here is an example man page composed in AsciiDoc for the `eve` command:
 include::example$manpage.adoc[]
 ----
 
+[#doctype]
 == Man page doctype
 
 The `manpage` doctype has the following required parts:
@@ -66,51 +67,51 @@ Subsequent sections are optional, but typical sections include "`SEE ALSO`", "`B
 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
+.Built-in manpage document attributes
+[%autowidth]
 |===
-|Attribute name |Description |Value (as parsed from example above)
+|Attribute |Description |Value (as parsed from example above)
 
-|mantitle
+|`mantitle`
 |Alternative way to set the man page name.
 |ASCIIDOCTOR(1)
 
-|manvolnum
+|`manvolnum`
 |Manual section number.
 |1
 
-|manname
+|`manname`
 |Alternative way to set the command name.
 |asciidoctor
 
-|manpurpose
+|`manpurpose`
 |Alternative way to set the command purpose.
 |converts AsciiDoc source files
 
-|man-linkstyle
+|`man-linkstyle`
 |Style the links in the manpage output.
 A valid link format sequence.
 // Needs a reference to this.
 |blue R <>
 
-|mansource
+|`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
+|`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
+|`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.
+The manual page for Asciidoctor is produced using the `manpage` converter.
+The manual 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/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc
index c18e26c4..56d4b608 100644
--- a/docs/modules/migrate/pages/asciidoc-python.adoc
+++ b/docs/modules/migrate/pages/asciidoc-python.adoc
@@ -294,7 +294,7 @@ a|
 === 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].
+Depending on the Asciidoctor processor you choose, you can re-write your xref:extensions:index.adoc[extensions in Ruby, Java, or JavaScript].
 
 == Doctest
 
diff --git a/docs/modules/source-highlighters/nav.adoc b/docs/modules/source-highlighters/nav.adoc
new file mode 100644
index 00000000..7464bc7e
--- /dev/null
+++ b/docs/modules/source-highlighters/nav.adoc
@@ -0,0 +1,5 @@
+* xref:index.adoc[]
+** xref:highlightjs.adoc[]
+** xref:rouge.adoc[]
+** xref:coderay.adoc[]
+** xref:pygments.adoc[]
diff --git a/docs/modules/source-highlighters/pages/coderay.adoc b/docs/modules/source-highlighters/pages/coderay.adoc
new file mode 100644
index 00000000..c7b035a9
--- /dev/null
+++ b/docs/modules/source-highlighters/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:source-highlighting-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/source-highlighters/pages/highlightjs.adoc b/docs/modules/source-highlighters/pages/highlightjs.adoc
new file mode 100644
index 00000000..17372031
--- /dev/null
+++ b/docs/modules/source-highlighters/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/source-highlighters/pages/index.adoc b/docs/modules/source-highlighters/pages/index.adoc
new file mode 100644
index 00000000..4312be25
--- /dev/null
+++ b/docs/modules/source-highlighters/pages/index.adoc
@@ -0,0 +1,32 @@
+= Source Highlighting
+
+[%autowidth]
+|===
+| |Syntax Highlighter |Supported Versions |Converters
+
+|Client-side highlighting for source code blocks
+
+|Highlight.js
+|9.18.3
+|HTML
+
+.3+|Server-side highlighting for source code blocks
+
+|CodeRay
+|1.1.2
+|HTML
+
+|Pygments
+|2.2.0
+|HTML
+
+|Rouge
+|3.1.1
+|HTML
+|===
+
+////
+|Inline, admonition or callout font-based icons
+|Font Awesome
+|4.7
+////
diff --git a/docs/modules/source-highlighters/pages/pygments.adoc b/docs/modules/source-highlighters/pages/pygments.adoc
new file mode 100644
index 00000000..a049b690
--- /dev/null
+++ b/docs/modules/source-highlighters/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:source-highlighting-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/source-highlighters/pages/rouge.adoc b/docs/modules/source-highlighters/pages/rouge.adoc
new file mode 100644
index 00000000..b6022864
--- /dev/null
+++ b/docs/modules/source-highlighters/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/stem/nav.adoc b/docs/modules/stem/nav.adoc
new file mode 100644
index 00000000..4f96cb52
--- /dev/null
+++ b/docs/modules/stem/nav.adoc
@@ -0,0 +1,3 @@
+* xref:index.adoc[]
+** xref:mathjax.adoc[]
+** xref:asciimath-gem.adoc[]
diff --git a/docs/modules/stem/pages/asciimath-gem.adoc b/docs/modules/stem/pages/asciimath-gem.adoc
new file mode 100644
index 00000000..5d9e82d7
--- /dev/null
+++ b/docs/modules/stem/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/stem/pages/index.adoc b/docs/modules/stem/pages/index.adoc
new file mode 100644
index 00000000..6ea72af6
--- /dev/null
+++ b/docs/modules/stem/pages/index.adoc
@@ -0,0 +1,14 @@
+= STEM Processing
+
+[%autowidth]
+|===
+|Integration |Supported Versions |Converters
+
+|MathJax
+|2.7.9
+|HTML
+
+|AsciiMath
+|2.0.x
+|Docbook
+|===
diff --git a/docs/modules/stem/pages/mathjax.adoc b/docs/modules/stem/pages/mathjax.adoc
new file mode 100644
index 00000000..b27c7928
--- /dev/null
+++ b/docs/modules/stem/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.
-- 
cgit v1.2.3


From 8353caab8b6fa93b9573a3c821176e85ab1d6c26 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Fri, 20 Nov 2020 02:42:04 -0700
Subject: clarify definition of Asciidoctor on docs start page; add link for
 migrating from AsciiDoc.py

---
 docs/modules/ROOT/pages/index.adoc | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index 2099f30c..bccb23e5 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -6,19 +6,25 @@ 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.
+Asciidoctor currently serves as the reference implementation for how to interpret the AsciiDoc language.
 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#.
+Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc into a document model and converting to output formats such as [.nowrap]#HTML 5#, [.nowrap]#DocBook 5#, manpage, PDF, and [.nowrap]#EPUB 3#.
+This Ruby library is often referred to as Asciidoctor core.
+That's because Asciidoctor is also the name of the family of projects that contribute extensions and tools for Asciidoctor.
+When we say Asciidoctor in this section of the documentation, we're specifically referring to Asciidoctor core.
 
 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 (gem or bundle).
 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^].
+Asciidoctor is open source software that is available under the terms of the MIT license and {url-org}[hosted on GitHub^].
+
+Asciidoctor is the successor to AsciiDoc Python (AsciiDoc.py).
+If you're still using AsciiDoc.py, follow xref:migrate:asciidoc-python.adoc[] to learn how to upgrade to Asciidoctor.
 
 == Basic usage
 
-- 
cgit v1.2.3


From b31306f6bab06f5acf8e5f1b55204e7f4092e973 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Fri, 20 Nov 2020 18:20:47 -0700
Subject: document the default stylesheet

---
 .../html-backend/images/default-stylesheet.png     | Bin 0 -> 104553 bytes
 docs/modules/html-backend/images/no-stylesheet.png | Bin 0 -> 75479 bytes
 docs/modules/html-backend/nav.adoc                 |   1 +
 .../html-backend/pages/default-stylesheet.adoc     | 188 +++++++++++++++++++++
 .../html-backend/pages/manage-stylesheets.adoc     |   3 +
 5 files changed, 192 insertions(+)
 create mode 100644 docs/modules/html-backend/images/default-stylesheet.png
 create mode 100644 docs/modules/html-backend/images/no-stylesheet.png
 create mode 100644 docs/modules/html-backend/pages/default-stylesheet.adoc

(limited to 'docs/modules')

diff --git a/docs/modules/html-backend/images/default-stylesheet.png b/docs/modules/html-backend/images/default-stylesheet.png
new file mode 100644
index 00000000..4584a510
Binary files /dev/null and b/docs/modules/html-backend/images/default-stylesheet.png differ
diff --git a/docs/modules/html-backend/images/no-stylesheet.png b/docs/modules/html-backend/images/no-stylesheet.png
new file mode 100644
index 00000000..77e880ad
Binary files /dev/null and b/docs/modules/html-backend/images/no-stylesheet.png differ
diff --git a/docs/modules/html-backend/nav.adoc b/docs/modules/html-backend/nav.adoc
index 396b226a..39e212c5 100644
--- a/docs/modules/html-backend/nav.adoc
+++ b/docs/modules/html-backend/nav.adoc
@@ -1,4 +1,5 @@
 * xref:index.adoc[]
+** xref:default-stylesheet.adoc[]
 ** xref:manage-stylesheets.adoc[]
 ** xref:source-highlighting-stylesheets.adoc[]
 ** xref:custom-stylesheets.adoc[]
diff --git a/docs/modules/html-backend/pages/default-stylesheet.adoc b/docs/modules/html-backend/pages/default-stylesheet.adoc
new file mode 100644
index 00000000..57a1737a
--- /dev/null
+++ b/docs/modules/html-backend/pages/default-stylesheet.adoc
@@ -0,0 +1,188 @@
+////
+.TODO
+* add more xrefs
+* screenshot showing it in action (we need a good example document for when we need to make these screenshots)
+* link to themes based on the default stylesheet
+////
+= Default Stylesheet
+
+When you use the HTML converter to generate a standalone HTML document, Asciidoctor includes a default stylesheet to make the HTML it produces look great right out of the box.
+This, in turn, gets you up and running quickly by giving you a result to preview or publish without having to do any additional work.
+
+Keep in mind that the default stylesheet that Asciidoctor provides is just that, _a default_.
+If you don't like its appearance, you can customize it or replace it with a different once.
+
+This page covers why the default is necessary, how to apply it, and how to build on it so you don't have to create a stylesheet from scratch.
+
+== Why provide a default?
+
+As previously stated, a default stylesheet is included to provide a nice out-of-the-box experience.
+But there's more to it.
+There are elements of AsciiDoc that require stylesheet support.
+
+One example is to honor *built-in roles*, such as `text-center`.
+In order for a role to take effect, it needs a companion CSS class in the stylesheet.
+To satisfy the expectations of a built-in role, a stylesheet is required.
+
+Another example is to implement *list marker styles*.
+AsciiDoc allows you to specify the marker for a list using a block style (e.g., `loweralpha`).
+However, HTML does not apply these markers by default.
+Rather, it's something that the stylesheet provides.
+
+The default stylesheet also applies *borders and shading to table cells* to support all combinations of the frame, grid, and stripes attributes.
+
+Yet another example is the *TOC position*.
+To position the TOC on the left or right requires help from the stylesheet to change the layout of the page so the TOC appears as a sidebar.
+It's the stylesheet that handles that task.
+
+In order for the AsciiDoc experience to be complete when generating HTML, a stylesheet is required.
+The default stylesheet not only completes this experience, but also serves as a reference for the styles a custom stylesheet must provide.
+
+=== Web fonts
+
+The default stylesheet ensures that the same fonts are selected across all platforms.
+
+By default, the browser relies on system fonts.
+But system fonts vary widely by platform, so users end up getting a very different experience.
+That's where web fonts come in.
+
+When the default stylesheet is used, the converter adds additional HTML to load open source fonts from Google Fonts.
+The default stylesheet, in turn, specifies a preference for these fonts.
+
+The web fonts used by the default stylesheet are as follows:
+
+Noto Serif:: body text (default)
+Open Sans:: headings
+Droid Sans Mono:: monospaced phrases and verbatim blocks
+
+Loading and preferring these web fonts ensures everyone sees the same result.
+
+== Usage
+
+When generating HTML, there's nothing special you need to do to apply the default stylesheet.
+Asciidoctor automatically embeds it in the `<head>` of the generated HTML when you run the `asciidoctor` command.
+
+ $ asciidoctor document.adoc
+
+Since no stylesheet is specified, Asciidoctor uses the stylesheet (located at [.path]_data/stylesheets/asciidoctor.css_ inside the installed gem).
+When you view the generated HTML file, [.path]_document.html_, you'll see styled HTML, as shown here:
+
+image::default-stylesheet.png[]
+
+When using the API, Asciidoctor links to the stylesheet by default instead of embedding it.
+Yet, it does not copy the stylesheet to the output directory (it needs to be placed there separately).
+If it's not already there, the browser will not be able to find the stylesheet.
+To solve this problem, set the safe mode to server or lower (e.g., server, safe, or unsafe) and Asciidoctor will embed the default stylesheet, like when using the `asciidoctor` command.
+
+[source,ruby]
+----
+require 'asciidoctor'
+
+Asciidoctor.convert_file 'document.adoc', safe: :safe
+----
+
+== Disable the default stylesheet
+
+If you don't want Asciidoctor to include the default stylesheet, unset the `stylesheet` attribute:
+
+ $ asciidoctor -a stylesheet! document.adoc
+
+When you view the generated HTML file, [.path]_document.html_, you'll see bare HTML without any styles applied, as shown here:
+
+image::no-stylesheet.png[]
+
+== Disable or modify the web fonts
+
+When the default stylesheet is used, the converter adds a `<link rel="stylesheet">` tag to load web fonts from Google Fonts.
+You can disable this link by unsetting the `webfonts` document attribute from the CLI, API, or document header.
+
+ $ asciidoctor -a webfonts! document.adoc
+
+With the web fonts absent, the browser will drop back to the fallback system fonts specified in the stylesheet.
+But this also provides an opportunity to use <<customize-docinfo,docinfo>> to load the web fonts from a different source.
+
+Rather than disabling the link, you can also use the `webfonts` attribute to change which fonts are loaded.
+When set, the value of the `webfonts` attribute is used as the value of the `family` query string parameter in the font-loader URL.
+
+Let's say you want to use Ubuntu Mono instead of Droid Sans Mono for monospaced text.
+You would set the `webfonts` attribute as follows:
+
+ $ asciidoctor \
+ -a webfonts="Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CUbuntu+Mono:400" \
+ document.adoc
+
+In this case, you would still need to use <<customize-docinfo,docinfo>> to instruct the stylesheet to use the new font.
+
+== Customize the default stylesheet
+
+What if the default stylesheet is not exactly to your liking, but you don't want to go off and create a custom stylesheet from scratch?
+Can you customize it?
+Indeed, you can.
+
+There are at least two ways to customize the default stylesheet.
+One way is to add auxiliary styles using docinfo.
+Another way is to create a custom stylesheet, but import the default stylesheet as a starting point.
+
+[#customize-docinfo]
+=== Auxiliary styles with docinfo
+
+Adding auxiliary styles is a great use case for xref:ROOT:docinfo.adoc[docinfo].
+The docinfo feature in AsciiDoc allows you to inject auxiliary content from a file into various places in the HTML output.
+In this case, we're interested in the "head" position, which injects content at the bottom of the `<head>` tag.
+
+Let's say you want to change the color of headings (and other heading-like titles) to match the color of paragraph text.
+Start by creating a file named [.path]_docinfo.html_ (head is the default location) and populate it with a `<style>` tag with the necessary styles.
+
+.docinfo.html
+[source,html]
+----
+<style>
+h1, h2, h3, h4, h5, h6, #toctitle,
+.sidebarblock > .content > .title {
+  color: rgba(0, 0, 0, 0.8);
+}
+</style>
+----
+
+Now tell Asciidoctor to look for and load the docinfo file using the `docinfo` attribute:
+
+ $ asciidoctor -a docinfo=shared document.adoc
+
+The `<style>` tag in your docinfo file will be inserted directly below the default stylesheet in the generated HTML.
+
+[#customize-extend]
+=== Extend the default stylesheet
+
+Instead of writing a custom stylesheet from scratch, you can import the default stylesheet and add overrides for any styles you want to change (leveraging the cascading nature of CSS).
+This is also a good way to use the default stylesheet, but load web fonts from a different CDN.
+
+Let's again change the color of headings (and other heading-like titles) to match the color of paragraph text.
+Start by creating a stylesheet named [.path]_my-asciidoctor.css_ and adding an `@import` declaration that references the default stylesheet and the web fonts it uses (which are not included in the source of the default stylesheet).
+We'll use a CDN to pull it directly out of the repository, but you can put it anywhere the browser can access it.
+Then add your overrides below those declarations.
+
+[source,css,subs=attributes+]
+----
+@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";
+@import "https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor@{page-component-version}/data/stylesheets/asciidoctor-default.css";
+
+h1, h2, h3, h4, h5, h6, #toctitle,
+.sidebarblock > .content > .title {
+  color: rgba(0, 0, 0, 0.8);
+}
+----
+
+Now tell Asciidoctor to use your custom stylesheet instead of the default one:
+
+ $ asciidoctor -a stylesheet=my-asciidoctor.css document.adoc
+
+Asciidoctor will embed the contents of your custom stylesheet instead of the default one.
+However, it will not embed the contents of the default stylesheet, so the browser is still going to go out and fetch it.
+
+== Are there different themes?
+
+The default stylesheet does not provide different themes.
+However, you can find stylesheets with different themes in the https://github.com/darshandsoni/asciidoctor-skins[Asciidoctor Skins^] project.
+These stylesheets take the approach of loading the default stylesheet (from a CDN), then overlaying additional styles to create a variety of themes.
+
+To learn more about managing and applying stylesheets, see xref:manage-stylesheets.adoc[].
diff --git a/docs/modules/html-backend/pages/manage-stylesheets.adoc b/docs/modules/html-backend/pages/manage-stylesheets.adoc
index 781c736e..68b12174 100644
--- a/docs/modules/html-backend/pages/manage-stylesheets.adoc
+++ b/docs/modules/html-backend/pages/manage-stylesheets.adoc
@@ -1,3 +1,6 @@
+// FIXME: This page needs to be revised now that there's a dedicated page for the default stylesheet.
+// We may want to merge it with the custom stylesheet page.
+// It also needs to cover copycss (disable or custom value)
 = Manage Stylesheets
 
 == What is the default stylesheet?
-- 
cgit v1.2.3


From 9cc3f9123ce44b61da58705f95d3c1a0e59199cc Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Sat, 21 Nov 2020 19:37:03 -0700
Subject: rewrite the pages that cover stylesheet modes and applying a custom
 stylesheet; reorder pages in nav

---
 docs/modules/cli/pages/process-multiple-files.adoc |   2 -
 docs/modules/html-backend/nav.adoc                 |  10 +-
 .../html-backend/pages/custom-stylesheet.adoc      | 206 +++++++++++++++++++++
 .../html-backend/pages/custom-stylesheets.adoc     |  97 ----------
 .../html-backend/pages/default-stylesheet.adoc     |  32 +---
 .../html-backend/pages/manage-stylesheets.adoc     |  48 -----
 .../html-backend/pages/stylesheet-modes.adoc       | 134 ++++++++++++++
 7 files changed, 355 insertions(+), 174 deletions(-)
 create mode 100644 docs/modules/html-backend/pages/custom-stylesheet.adoc
 delete mode 100644 docs/modules/html-backend/pages/custom-stylesheets.adoc
 delete mode 100644 docs/modules/html-backend/pages/manage-stylesheets.adoc
 create mode 100644 docs/modules/html-backend/pages/stylesheet-modes.adoc

(limited to 'docs/modules')

diff --git a/docs/modules/cli/pages/process-multiple-files.adoc b/docs/modules/cli/pages/process-multiple-files.adoc
index db6368e5..803f5bbe 100644
--- a/docs/modules/cli/pages/process-multiple-files.adoc
+++ b/docs/modules/cli/pages/process-multiple-files.adoc
@@ -44,5 +44,3 @@ For example, you can match AsciiDoc files in the current folder and in folders o
 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:custom-stylesheets.adoc#style-nested[manage the stylesheet's location].
diff --git a/docs/modules/html-backend/nav.adoc b/docs/modules/html-backend/nav.adoc
index 39e212c5..e887d6da 100644
--- a/docs/modules/html-backend/nav.adoc
+++ b/docs/modules/html-backend/nav.adoc
@@ -1,9 +1,9 @@
 * xref:index.adoc[]
-** xref:default-stylesheet.adoc[]
-** xref:manage-stylesheets.adoc[]
-** xref:source-highlighting-stylesheets.adoc[]
-** xref:custom-stylesheets.adoc[]
-** xref:favicon.adoc[]
+** Stylesheets
+*** xref:default-stylesheet.adoc[]
+*** xref:stylesheet-modes.adoc[]
+*** xref:custom-stylesheet.adoc[]
+*** xref:source-highlighting-stylesheets.adoc[]
 ** xref:manage-images.adoc[]
 ** xref:favicon.adoc[]
 ** xref:verbatim-line-wrap.adoc[]
diff --git a/docs/modules/html-backend/pages/custom-stylesheet.adoc b/docs/modules/html-backend/pages/custom-stylesheet.adoc
new file mode 100644
index 00000000..c3615dfe
--- /dev/null
+++ b/docs/modules/html-backend/pages/custom-stylesheet.adoc
@@ -0,0 +1,206 @@
+= Apply a Custom Stylesheet
+
+So far we've talked about different ways of using the default stylesheet.
+In place of the default stylesheet, you can instruct Asciidoctor to use a custom stylesheet of your choosing.
+On this page, you'll learn how to apply a custom stylesheet and, if necessary, how to get Asciidoctor to copy and link to that stylesheet into the correct location.
+You'll also learn about some of the limitations of this feature when processing multiple documents.
+
+== Specify the custom stylesheet
+
+Asciidoctor looks for the stylesheet file specified by the `stylesheet` document attribute.
+If the value of this attribute is empty (the default), Asciidoctor uses the default stylesheet.
+Otherwise, Asciidoctor assumes the value is the path of a custom stylesheet file relative to the source document.
+All the same behavior described in xref:stylesheet-modes.adoc[] still applies, except Asciidoctor uses the specified stylesheet instead of the default stylesheet.
+
+To begin, you must create a stylesheet file.
+For now, create this file adjacent to your AsciiDoc document.
+To keep it simple, we'll just define a basic stylesheet that changes all text to red.
+Create the file [.path]_my-stylesheet.css_ the directory with your AsciiDoc source files and populate it with the following contents:
+
+.my-stylesheet.css
+[source,css]
+----
+body {
+  color: #ff0000;
+}
+----
+
+Now let's use the `stylesheet` attribute to apply it.
+
+The `stylesheet` document attribute must be set by the end of the header to be effective.
+One way to do that is to set the attribute in the document header:
+
+[source]
+----
+= My First Experience with the Dangers of Documentation
+:stylesheet: my-stylesheet.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.
+----
+
+You can also set `stylesheet` using the API or CLI (shown here):
+
+ $ asciidoctor -a stylesheet=my-stylesheet.css document.adoc
+
+When you view the generated HTML file [.path]_document.html_ in your browser, you'll see that all the text is red.
+
+TIP: If you want to create a custom stylesheet by extending the default stylesheet, see xref:default-stylesheet.adoc#customize-extend[Extend the default stylesheet].
+
+As with the default stylesheet, you can set the `linkcss` document attribute and Asciidoctor will link to your stylesheet instead.
+(Note that it doesn't copy it in this case since it's already in the same folder as the output file).
+
+ $ asciidoctor -a stylesheet=my-stylesheet.css -a linkcss document.adoc
+
+You may not want to keep your stylesheet in the same directory as your AsciiDoc documents.
+Let's see how to tell Asciidoctor to look for it elsewhere.
+
+== Configure the styles directory
+
+When your stylesheet is in a directory below your AsciiDoc document, you need to tell Asciidoctor where to look to find the stylesheet.
+There are two equivalent ways to do so:
+
+* Specify the name of the stylesheet file using the `stylesheet` attribute and the directory where it's located using the `stylesdir` attribute
+* Include the directory where the stylesheet is located in the value of the `stylesheet` attribute (instead of using the `stylesdir` attribute)
+
+The value of the `stylesdir` attribute can end with a trailing directory separator (`/`), but it's not required.
+
+If the `linkcss` attribute is not set, the styles directory can be either relative or absolute.
+The situation gets trickier when `linkcss` is set, which we'll <<stylesdir-and-linkcss,get to later>>.
+
+Let's assume you want to put your stylesheet in the [.path]_my-styles_ folder relative to your AsciiDoc document(s).
+Go ahead and create that folder and move your custom stylesheet into it for this example.
+Now we need to tell Asciidoctor where it's located using `stylesdir`.
+
+The `stylesdir` document attribute must be set by the end of the header to be effective.
+One way to do that is to set the attribute in the document header:
+
+[source]
+----
+= My First Experience with the Dangers of Documentation
+:stylesheet: my-stylesheet.css
+:stylesdir: my-styles
+
+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.
+----
+
+You can also set `stylesdir` using the API or CLI (shown here):
+
+ $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css document.adoc
+
+Asciidoctor now looks for the stylesheet file [.path]_my-styles/my-stylesheet.css_ relative to the AsciiDoc document and embeds it into the HTML.
+
+You can achieve the same result by including the directory in the value of the `stylesheet` attribute:
+
+ $ asciidoctor -a stylesheet=my-styles/my-stylesheet.css document.adoc
+
+If you set the value of `stylesdir` to an absolute directory, then Asciidoctor would still locate the stylesheet and embed it into the HTML.
+But this can create problems if you've configured the converter to link to the stylesheet instead.
+Let's look at thoses problem and ways to work through them.
+
+[#stylesdir-and-linkcss]
+== Styles directory and linkcss
+
+Using `stylesdir` gets tricky when your linking to the stylesheet instead of embedding it.
+That's because we're now dealing with two different paths.
+One is the path where the stylesheet is located on disk (either absolute or relative to the document).
+The other is the path the browser uses to access the stylesheet.
+
+First, it's important to understand that Asciidoctor mirrors the `stylesdir` path in the link reference.
+Let's use the previous example to demonstrate.
+If you invoke Asciidoctor as follows:
+
+ $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css -a linkcss document.adoc
+
+Then when you inspect the HTML, you will see:
+
+[source,html]
+----
+<link rel="stylesheet" href="my-styles/asciidoctor.css">
+----
+
+Notice how the value of `stylesdir` ([.path]_my-styles_) is included in the referenced path.
+Asciidoctor will also preserve this directory if it needs to copy the stylesheet file.
+
+There are certain situations where this isn't going to work (at least not when publishing the file to the public internet).
+Let's consider one such case.
+We'll specify the location of `stylesdir` as an absolute path and generate the output file into a separate output directory.
+
+ $ asciidoctor -a stylesdir=`pwd`/my-styles -a stylesheet=my-stylesheet.css -a linkcss -D public document.adoc
+
+Asciidoctor generates the HTML file into the [.path]_public_ folder, but it _does not_ copy the stylesheet.
+Furthermore, it uses an absolute path in the link to the stylesheet:
+
+[source,html]
+----
+<link rel="stylesheet" href="/path/to/documents/my-styles/asciidoctor.css">
+----
+
+What we want is for Asciidoctor to copy the stylesheet to the output directory and link to it using a relative path.
+
+A similar problem comes up if you want to control the styles directory and stylesheet file referenced by the HTML independently of the location where they are taken.
+
+In brief, we need to be able to decouple the path where the stylesheet is read from the location where the stylesheet is published and referenced.
+That's where the `copycss` attribute comes back into play.
+
+[#copy-link-split]
+== Copy from one place, link to another
+
+For complex combinations that involve `stylesdir`, `linkcss`, and an explicit output directory, the meaning of `stylesdir` is too overloaded and needs to be reconciled.
+We can turn to the `copycss` attribute to clear this situation up.
+
+NOTE: This situation is unique to when `linkcss` is set.
+It's not a problem when the converter embeds the stylesheet since there is no secondary reference involved.
+
+The `copycss` attribute can accepts a value.
+Asciidoctor uses that value as an override for where to look for the stylesheet to read.
+The converter, on the other hand, does not use this value.
+That means we can use `stylesdir` and `stylesheet` to assemble the path relative to the output directory where Asciidoctor should write and link to the stylesheet independent of the location where it reads the file.
+
+Let's revisit the broken scenario from the previous section and use `copycss` to reconcile the problem:
+
+ $ asciidoctor -a stylesdir=css -a stylesheet=default.css \
+ -a copycss=`pwd`/my-styles/my-stylesheet.css -a linkcss -D public document.adoc
+
+Asciidoctor copies the stylesheet from the absolute path specified by the `copycss` attribute to the path [.path]_public/css/default.css_ and links to it using the path [.path]_css/default.css_.
+Notice that we even changed the name of the folder and stylesheet file in the output.
+That demonstrates that we have decoupled the path where the stylesheet is read from the location where the stylesheet is published and referenced.
+
+== Styles directory and nested documents when linking
+
+When xref:cli:process-multiple-files.adoc[invoking Asciidoctor on a nested set of documents], it's currently not possible to specify a single relative path for the `stylesdir` attribute that works 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-styles
+....
+
+For [.path]_a.adoc_ and [.path]_b.adoc_, set `stylesdir` to:
+
+[source]
+----
+:stylesdir: my-styles
+----
+
+For [.path]_c.adoc_, set `stylesdir` to:
+
+[source]
+----
+:stylesdir: ../my-styles
+----
+
+If you're serving your documents from a webserver, you can solve this problem by providing an absolute path to the stylesheet.
+You can also try to use the `copycss` per document to control where Asciidoctor looks for the stylesheet independent of where Asciidoctor copies it and the converter configured the HTML to reference it.
diff --git a/docs/modules/html-backend/pages/custom-stylesheets.adoc b/docs/modules/html-backend/pages/custom-stylesheets.adoc
deleted file mode 100644
index 1cc20d2a..00000000
--- a/docs/modules/html-backend/pages/custom-stylesheets.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-= 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 xref:manage-stylesheets.adoc[default stylesheet], you can have the output document link to or embed your custom stylesheet.
-
-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/default-stylesheet.adoc b/docs/modules/html-backend/pages/default-stylesheet.adoc
index 57a1737a..3b1616ad 100644
--- a/docs/modules/html-backend/pages/default-stylesheet.adoc
+++ b/docs/modules/html-backend/pages/default-stylesheet.adoc
@@ -1,19 +1,15 @@
-////
-.TODO
-* add more xrefs
-* screenshot showing it in action (we need a good example document for when we need to make these screenshots)
-* link to themes based on the default stylesheet
-////
 = Default Stylesheet
 
-When you use the HTML converter to generate a standalone HTML document, Asciidoctor includes a default stylesheet to make the HTML it produces look great right out of the box.
+When you use the HTML converter to generate a standalone HTML document, Asciidoctor includes a default stylesheet to ensure the HTML it produces look great right out of the box.
 This, in turn, gets you up and running quickly by giving you a result to preview or publish without having to do any additional work.
 
-Keep in mind that the default stylesheet that Asciidoctor provides is just that, _a default_.
-If you don't like its appearance, you can customize it or replace it with a different once.
-
 This page covers why the default is necessary, how to apply it, and how to build on it so you don't have to create a stylesheet from scratch.
 
+NOTE: The default stylesheet that Asciidoctor provides is just that, _a default_.
+If you don't like its appearance, you can customize it or replace it with a different once.
+Though, it's important to understand what purpose the stylesheet serves when doing so.
+
+// TODO: we probably need a page to defines what styles any stylesheet must provide to be fully compatible with AsciiDoc
 == Why provide a default?
 
 As previously stated, a default stylesheet is included to provide a nice out-of-the-box experience.
@@ -69,7 +65,7 @@ When you view the generated HTML file, [.path]_document.html_, you'll see styled
 
 image::default-stylesheet.png[]
 
-When using the API, Asciidoctor links to the stylesheet by default instead of embedding it.
+When using the API, Asciidoctor links to the stylesheet by default instead of embedding it (due to the safe mode).
 Yet, it does not copy the stylesheet to the output directory (it needs to be placed there separately).
 If it's not already there, the browser will not be able to find the stylesheet.
 To solve this problem, set the safe mode to server or lower (e.g., server, safe, or unsafe) and Asciidoctor will embed the default stylesheet, like when using the `asciidoctor` command.
@@ -81,16 +77,6 @@ require 'asciidoctor'
 Asciidoctor.convert_file 'document.adoc', safe: :safe
 ----
 
-== Disable the default stylesheet
-
-If you don't want Asciidoctor to include the default stylesheet, unset the `stylesheet` attribute:
-
- $ asciidoctor -a stylesheet! document.adoc
-
-When you view the generated HTML file, [.path]_document.html_, you'll see bare HTML without any styles applied, as shown here:
-
-image::no-stylesheet.png[]
-
 == Disable or modify the web fonts
 
 When the default stylesheet is used, the converter adds a `<link rel="stylesheet">` tag to load web fonts from Google Fonts.
@@ -179,10 +165,12 @@ Now tell Asciidoctor to use your custom stylesheet instead of the default one:
 Asciidoctor will embed the contents of your custom stylesheet instead of the default one.
 However, it will not embed the contents of the default stylesheet, so the browser is still going to go out and fetch it.
 
+To learn more about how to apply a custom stylesheet, see xref:custom-stylesheet.adoc[].
+
 == Are there different themes?
 
 The default stylesheet does not provide different themes.
 However, you can find stylesheets with different themes in the https://github.com/darshandsoni/asciidoctor-skins[Asciidoctor Skins^] project.
 These stylesheets take the approach of loading the default stylesheet (from a CDN), then overlaying additional styles to create a variety of themes.
 
-To learn more about managing and applying stylesheets, see xref:manage-stylesheets.adoc[].
+To learn how to apply a custom stylesheet, see xref:custom-stylesheet.adoc[].
diff --git a/docs/modules/html-backend/pages/manage-stylesheets.adoc b/docs/modules/html-backend/pages/manage-stylesheets.adoc
deleted file mode 100644
index 68b12174..00000000
--- a/docs/modules/html-backend/pages/manage-stylesheets.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-// FIXME: This page needs to be revised now that there's a dedicated page for the default stylesheet.
-// We may want to merge it with the custom stylesheet page.
-// It also needs to cover copycss (disable or custom value)
-= Manage Stylesheets
-
-== What is the default stylesheet?
-
-Asciidoctor comes bundled with a stylesheet, named [.path]_asciidoctor.css_.
-The built-in HTML converter uses this stylesheet for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes.
-Asciidoctor applies this stylesheet by default unless you tell Asciidoctor to use another stylesheet.
-
-== Embed a stylesheet
-
-When you generate a document using the built-in HTML converter, the [.path]_asciidoctor.css_ stylesheet is embedded into the HTML output by default when the xref:ROOT:safe-modes.adoc[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[]
-====
-
-== Disable 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:custom-stylesheets.adoc[custom stylesheet].
diff --git a/docs/modules/html-backend/pages/stylesheet-modes.adoc b/docs/modules/html-backend/pages/stylesheet-modes.adoc
new file mode 100644
index 00000000..10672215
--- /dev/null
+++ b/docs/modules/html-backend/pages/stylesheet-modes.adoc
@@ -0,0 +1,134 @@
+= Stylesheet Modes
+
+//When applying a stylesheet to the generated HTML, you can configure the HTML converter to either embed the CSS directly into the HTML or link to the stylesheet file.
+The HTML converter can be configured to embed the CSS of the stylesheet directly into the HTML, link to the stylesheet file, or disable it entirely.
+These modes are available regardless of whether you're using the xref:default-stylesheet.adoc[default stylesheet] or a xref:custom-stylesheet.adoc[custom stylesheet].
+This page covers the document attributes that control how the stylesheet is applied.
+
+IMPORTANT: The HTML converter will only apply a stylesheet when generating a standalone HTML document.
+That's because the stylesheet goes in the HTML `<head>` and the converter only generates this tag for standalone output, not embedded output.
+
+[#embed]
+== Embed the stylesheet
+
+When the xref:ROOT:safe-modes.adoc[safe mode] is server or lower, the default behavior of the HTML converter is to read the the stylesheet file, enclose its contents in a `<style>` tag, and embed it directly into the `<head>` of the generated HTML.
+This default makes the HTML more portable since you don't lose the stylesheet if you move the file.
+
+However, if the safe mode is secure, the converter will <<link,link to the stylesheet file>> instead.
+If you see a link to the stylesheet file in the generated HTML where you expect the stylesheet to be embedded, check your safe mode setting.
+
+The same two rules apply regardless of whether you're using the default stylesheet or a custom stylesheet.
+
+[#link]
+== Link to the stylesheet
+
+You already know that the HTML converter will link to the stylesheet when the safe mode is secure.
+However, it's possible to enable this behavior independent of the safe mode.
+This can be beneficial if you're converting numerous AsciiDoc documents to HTML and want them all to share the same stylesheet.
+It can also make inspecting the HTML a little simpler.
+
+If the `linkcss` document attribute is set, the converter will take this hint to link to the stylesheet using a `<link rel="stylesheet">` tag point to a relative path reference instead of embedding it.
+
+The `linkcss` document attribute must be set by the end of the header to be effective.
+One way to do that is to set the attribute in the document header:
+
+[source]
+----
+= My First Experience with the Dangers of Documentation
+: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.
+----
+
+You can also set `linkcss` using the API or CLI (shown here):
+
+ $ asciidoctor -a linkcss document.adoc
+
+In either case, if you inspect the `<head>` tag in the output file [.path]_document.html_, you'll see that the HTML links to the stylesheet.
+
+[source,html]
+----
+<link rel="stylesheet" href="./asciidoctor.css">
+----
+
+Since we didn't specify a stylesheet, the converter links to the default stylesheet.
+But where is this stylesheet located?
+Let's find out.
+
+[#copy]
+== Copy the stylesheet to the output directory
+
+If you're linking to a stylesheet file, the stylesheet file has to be available at the referenced path so the browser can access it.
+For simple cases, Asciidoctor takes care of this for you.
+
+If the safe mode is server or lower, and the `linkcss` document attribute is set, Asciidoctor will copy the stylesheet to the output directory so the HTML can link to it.
+When using the default stylesheet, Asciidoctor writes the CSS to the file [.path]_asciidoctor.css_ in the output directory.
+If you specify a custom stylesheet, Asciidoctor will copy that file instead, retaining the name of the file.
+This utility works even if you specify an xref:cli:output-file.adoc[output file in a different directory] from the source file.
+
+.A shared responsiblity
+****
+While the converter handles the task of embedding or linking to the stylesheet file, it's the processor itself (not the converter) that handles copying the stylesheet.
+****
+
+If the safe mode is secure, Asciidoctor will not copy the stylesheet file and, thus, the link to it will be broken (unless, of course, you copy the file separately).
+
+Let's revisit the previous example:
+
+ $ asciidoctor -a linkcss document.adoc
+
+After running this command, you should see the stylesheet file [.path]_asciidoctor.css_ adjacent to the HTML file [.path]_document.html_.
+When you view the HTML file in your browser, you should observe that the default stylesheet is applied.
+
+=== To copy or not to copy
+
+Whether Asciidoctor copies the stylesheet to the output directory is controlled by the `copycss` document attribute.
+The `copycss` attribute is set by default unless the safe mode is secure.
+
+To prevent Asciidoctor from copying the stylesheet independent of safe mode, unset the `copycss` document attribute.
+
+The `copycss` document attribute must be unset by the end of the header to be effective.
+One way to do that is to unset the attribute in the document header:
+
+[source]
+----
+= My First Experience with the Dangers of Documentation
+:linkcss:
+:!copycss:
+
+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.
+----
+
+You can also unset `copycss` using the API or CLI (shown here):
+
+ $ asciidoctor -a linkcss -a copycss! document.adoc
+
+In either case, if you inspect the output directory, you will see that the stylesheet file [.path]_asciidoctor.css_ is missing (unless it was already there).
+
+We'll see the `copycss` attribute come up again on the xref:custom-stylesheet.adoc[custom stylesheet page] as a means of xref:custom-stylesheet.adoc#copy-link-split[overriding the location of the stylesheet to copy].
+
+[#disable]
+== Disable the stylesheet
+
+The stylesheet is effectively disabled when generating embedded HTML, since the embedded HTML does not include the `<head>` tag.
+If you don't want the converter to include a stylesheet in the standalone HTML, unset the `stylesheet` document attribute:
+
+ $ asciidoctor -a stylesheet! document.adoc
+
+The reason you have to unset the `stylesheet` attribute is because it is set by default (to an empty value).
+When the `stylesheet` attribute is set, but empty, the HTML converter uses the default stylesheet.
+By unsetting this attribute, we're telling the converter not to use a stylesheet at all.
+
+When you view the generated HTML file, [.path]_document.html_, you'll see bare HTML without any styles applied, as shown here:
+
+image::no-stylesheet.png[]
+
+NOTE: When the `stylesheet` attribute is unset, the `linkcss` and `copycss` attributes are ignored.
+
+Now that you have a clean slate, let's learn how to apply a custom stylesheet of your very own.
-- 
cgit v1.2.3


From 44d1d3c25d12b70b8346d4435461601d20b66839 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Mon, 23 Nov 2020 04:12:09 -0700
Subject: rewrite the STEM processing section; document the functionality and
 caveats in much more detail

---
 docs/modules/stem/nav.adoc                 |  2 +
 docs/modules/stem/pages/asciimath-gem.adoc | 71 ++++++++++++++++--------
 docs/modules/stem/pages/docbook.adoc       | 28 ++++++++++
 docs/modules/stem/pages/index.adoc         | 37 +++++++++++--
 docs/modules/stem/pages/mathematical.adoc  | 87 ++++++++++++++++++++++++++++++
 docs/modules/stem/pages/mathjax.adoc       | 47 ++++++++++++++--
 6 files changed, 243 insertions(+), 29 deletions(-)
 create mode 100644 docs/modules/stem/pages/docbook.adoc
 create mode 100644 docs/modules/stem/pages/mathematical.adoc

(limited to 'docs/modules')

diff --git a/docs/modules/stem/nav.adoc b/docs/modules/stem/nav.adoc
index 4f96cb52..cb5ea3ef 100644
--- a/docs/modules/stem/nav.adoc
+++ b/docs/modules/stem/nav.adoc
@@ -1,3 +1,5 @@
 * xref:index.adoc[]
 ** xref:mathjax.adoc[]
+** xref:mathematical.adoc[]
+** xref:docbook.adoc[]
 ** xref:asciimath-gem.adoc[]
diff --git a/docs/modules/stem/pages/asciimath-gem.adoc b/docs/modules/stem/pages/asciimath-gem.adoc
index 5d9e82d7..5016bacd 100644
--- a/docs/modules/stem/pages/asciimath-gem.adoc
+++ b/docs/modules/stem/pages/asciimath-gem.adoc
@@ -1,39 +1,68 @@
-= AsciiMath RubyGem
+// add note about warning when asciimath gem is not available
+= AsciiMath Gem
 :url-asciimath-repo: https://github.com/asciidoctor/AsciiMath
+:stem:
 
-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.
+The DocBook toolchain has some support for STEM processing, though it varies depending on which DocBook pipeline you're using and which integrations you have enabled.
+But there's one thing we know for sure.
+The DocBook toolchain does not understand AsciiMath.
+That's where the {url-rubygem}/asciimath[AsciiMath gem^] comes in.
 
-TIP: For more information, see the {url-asciimath-repo}[AsciiMath RubyGem repository^].
+== AsciiMath and DocBook
 
-== Install asciimath gem
+The AsciiMath gem translates AsciiMath expressions to MathML, which is something the DocBook toolchain is capable of processing.
+When the AsciiMath gem is available, the DocBook converter uses it to convert STEM expressions written in AsciiMath notation to MathML and embeds the MathML into the generated DocBook.
+Processing the MathML into a displayable format is left up to the DocBook toolchain.
 
-To enable AsciiMath support when converting to DocBook, you need to install the asciimath gem:
+[#install]
+== Install
+
+To enable AsciiMath to MathML translation when converting to DocBook, you first need to install the asciimath gem:
 
  $ gem install asciimath
 
-== Activate asciimath stem expressions
+== Usage
+
+It's not necessary to require the `asciimath` gem explicitly.
+As long as the AsciiMath gem is available, the DocBook converter will automatically load and use it to translate AsciiMath notation to MathML.
+
+If the gem is not available, and there's at least one AsciiMath expression in the document, you will see the following message when converting to DocBook:
+
+....
+asciidoctor: WARNING: optional gem 'asciimath' is not available. Functionality disabled.
+....
+
+The functionality referenced here is the translation from AsciiMath to MathML.
+If you see this message, refer back to <<Install>>.
 
-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).
+Assuming you have it installed, let's look at an example.
 
-.Set the stem attribute
-[source,asciidoc]
+First, activate STEM support in AsciiDoc by setting the `stem` document attribute.
+This attribute must be set by the end of the document header.
+
+.Activate STEM support by setting the stem document attribute
+[source]
 ----
 = Document Title
-:stem: asciimath
+:stem:
+
+stem:[sqrt(4)] is the square root of 4, which is 2.
 ----
 
-To learn how to create inline and block AsciiMath equations, see xref:asciidoc:stem:stem.adoc[].
+Now let's convert this document to DocBook using the DocBook converter:
+
+ $ asciidoctor -b docbook asciimath-sample.adoc
 
-=== Using AsciiMath with the DocBook toolchain
+The DocBook converter will emit the following XML into the generated document:
 
-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.
+[source,xml]
+----
+<inlineequation><mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"><mml:msqrt><mml:mn>4</mml:mn></mml:msqrt></mml:math></inlineequation>
+----
 
-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.
+It's now up to the DocBook toolchain to convert the MathML embeded in the DocBook into a displayable format.
+Here's the result you should see:
 
-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.
+====
+stem:[sqrt(4)] is the square root of 4, which is 2.
+====
diff --git a/docs/modules/stem/pages/docbook.adoc b/docs/modules/stem/pages/docbook.adoc
new file mode 100644
index 00000000..5218f955
--- /dev/null
+++ b/docs/modules/stem/pages/docbook.adoc
@@ -0,0 +1,28 @@
+= STEM Support in the DocBook Toolchain
+:url-jeuclid-fop: http://jeuclid.sourceforge.net/jeuclid-fop/index.html
+
+The DocBook toolchain has some support for STEM processing, though it varies depending on which DocBook pipeline you're using and which integrations you have enabled.
+Since the DocBook toolchain is most often used to generate PDF output, let's look at how STEM processing is supported in the two pipelines for PDF generation: dblatex and fop.
+
+dblatex::
+If you're using the dblatex pipeline to produce PDF, the DocBook toolchain provides built-in processing for LaTeX and MathML notation.
+If you write your STEM expressions using the latexmath notation, you're all set.
+But that only gets us half way.
+What if you write STEM expressions in AsciiMath?
+The pipeline does not understand AsciiMath, but it does understand MathML.
+And that's something the DocBook converter can produce.
+If you have the AsciiMath gem installed, the DocBook converter will translate AsciiMath to MathML.
+That means when you're using this pipeline, you can write STEM expressions in both the AsciiMath and LaTeX notations.
+
+fop::
+If you're using the fop pipeline, the STEM support provided by the DocBook toolchain is more spotty.
+This pipeline does not support LaTeX notation at all, and there's no library that integrations with Asciidoctor like AsciiMath to convert LaTeX notation to MathML.
+So you cannot write STEM expressions in LaTeX when using this pipeline.
+If that's important to you, consider using the dblatex pipeline instead.
+There's still a path for writing STEM expressions in AsciiMath.
+If you're running the DocBook toolchain using Java, you can configure the JEuclid integration (by activating the {url-jeuclid-fop}[JEuclid FOP plugin^]) to get MathML support.
+That means we can turn again to the AsciiMath gem when converting to DocBook.
+The DocBook converter integrates with the AsciiMath gem, if available, to convert the AsciiMath notation to MathML, which the fop pipeline can understand.
+
+While neither DocBook pipeline understands AsciiMath, we can leverage the AsciiMath gem to feed it something it does understand, MathML.
+Let's explore the xref:asciimath-gem.adoc[AsciiMath gem] in more detail.
diff --git a/docs/modules/stem/pages/index.adoc b/docs/modules/stem/pages/index.adoc
index 6ea72af6..756f7fff 100644
--- a/docs/modules/stem/pages/index.adoc
+++ b/docs/modules/stem/pages/index.adoc
@@ -1,14 +1,41 @@
 = STEM Processing
 
+AsciiDoc defines syntax elements for adding xref:asciidoc:stem:stem.adoc[science, technology, engineering, and math (STEM) expressions] to an AsciiDoc document.
+Much like AsciiDoc itself, this STEM notation allows the graphical notation that scientists, mathematicians, and engineers use to describe equations, formulas, etc. be expressed in a plain text format.
+It's up to the converter to interpret and transform the source of these expressions into a displayable format.
+That's where STEM processing comes in.
+
+On this page, we look at how STEM expressions are handled when converting AsciiDoc and survey the integrations Asciidoctor offers to process them for various output formats.
+
+== How it works
+
+When a converter comes across a STEM node in an AsciiDoc document, it passes the source of the expression to a STEM processing library, such as MathJax.
+That library either displays the rendered expression itself (e.g., MathJax), turns it into an image the converter can link to or embed in the output file (e.g., Asciidoctor Mathematical), or translates it into another format that something further down the pipeline can process (e.g., AsciiMath).
+
+The STEM integrations are activated when the `stem` document attribute is set on the document and, if required, the relevant library is installed.
+
+== STEM integrations
+
 [%autowidth]
 |===
-|Integration |Supported Versions |Converters
+|Library Name |Supported Versions |Backends |Loaded By
 
 |MathJax
 |2.7.9
-|HTML
+|html
+|client
+
+|Asciidoctor Mathematical
+|0.3.5
+|any
+|processor
 
-|AsciiMath
-|2.0.x
-|Docbook
+|AsciiMath (Ruby)
+|1.0.x or 2.0.x
+|docbook
+|processor
 |===
+
+You can explore these integrations in depth on the xref:mathjax.adoc[], xref:mathematical.adoc[], and xref:asciimath-gem.adoc[] pages.
+
+If you're planning to convert to DocBook to leverage the DocBook toolchain, be sure to consider xref:docbook.adoc[] when deciding which STEM notation to use in your AsciiDoc document.
diff --git a/docs/modules/stem/pages/mathematical.adoc b/docs/modules/stem/pages/mathematical.adoc
new file mode 100644
index 00000000..17442560
--- /dev/null
+++ b/docs/modules/stem/pages/mathematical.adoc
@@ -0,0 +1,87 @@
+= Asciidoctor Mathematical
+:url-asciidoctor-mathematical: https://github.com/asciidoctor/asciidoctor-mathematical
+:url-asciidoctor-docker: https://github.com/asciidoctor/docker-asciidoctor
+
+{url-asciidoctor-mathematical}[Asciidoctor Mathematical] is an Asciidoctor extension that provides an alternate solution for converting STEM expressions in an AsciiDoc document into a displayable format.
+It has the benefit of working across all converters.
+
+The library is called Asciidoctor Mathematical because it relies on the Mathematical library to parse and transform (aka render) LaTeX expressions.
+It also uses the AsciiMath library to convert AsciiMath notation to LaTeX so Mathematical can process it.
+
+This page explains how Asciidoctor Mathematical works, how to install it and activate it, and where to go to learn more information about it.
+
+== How it works
+
+The library works by visiting each STEM node in the parsed document and converting it to an image, effectively replacing the STEM node with an image node.
+This takes the burden of transforming the STEM expressions off of the converter.
+All the converter sees are image nodes that reference the generated images.
+
+Upon visiting each STEM node, the extension first extracts the expression source.
+If the expression is written in AsciiMath, the extension uses the AsciiMath library to convert that expression to LaTeX.
+The extension then passes the expression to Mathematical to render it as an image.
+The image is sized automatically to accomodate the rendered expression and, if necessary, resized to fit within the line.
+Once the image is generated, the extension replaces the STEM node in the parsed document with an image node that references the generated image.
+
+When the extension finishes processing all the STEM nodes, it unsets the `stem` attribute on the document to indicate no further STEM processing should be performed on the document.
+
+== Benefits and drawbacks
+
+Since Asciidoctor Mathematical replaces all STEM nodes with image nodes, it serves as an an all-purpose solution for STEM processing.
+All converters know how do deal with image nodes.
+The extension can be used with the built-in converters as well as extended converters such as PDF and EPUB3.
+
+The main drawback of Asciidoctor Mathmatical when compared to MathJax is that you don't have a lot of control over the size and resolution of the images it generates.
+It also lacks the interactivity with the expression that MathJax provides.
+So when your converting to HTML, MathJax is going to give you a better result.
+
+Another drawback when compared to MathJax is that it requires installing an extra library, and that library can be difficult to install.
+Nonetheless, if you need it and you're up for the challenge, that's where we're headed next.
+
+== Install
+
+Asciidoctor Mathematical is distributed as a RubyGem named https://rubygems.org/gems/asciidoctor-mathematical[asciidoctor-mathematical^].
+You can install it using the Ruby packaging tools (gem or bundle).
+
+ $ gem install asciidoctor-mathematical
+
+However, you may run into difficulty installing this gem.
+Asciidoctor Mathematical depends on Mathematical, which is a native gem.
+In other words, Mathematical must be recompiled during installation, which requires access to build tools and native development libraries on the host system.
+//Furthermore, this compilation currently only works on Linux and on macOS with Xcode.
+Furthermore, this compilation currently only works on Linux.
+You cannot install this gem on macOS or Windows.
+Please refer to the {url-asciidoctor-mathematical}/#installation[installation section] in the Asciidoctor Mathematical documentation to learn which system tools and development libraries you need in order to install it.
+
+If you run into problems installing this gem, or need to use it on Windows, consider using the {url-asciidoctor-docker}[Asciidoctor Docker container].
+The Asciidoctor Docker container launches with the asciidoctor-mathematical gem preinstalled.
+
+== Activate
+
+//To activate the Asciidoctor Mathematical extension, you must require the gem when invoking Asciidoctor:
+Once Asciidoctor Mathematical is installed, you can activate the extension when invoking Asciidoctor using the `-r` flag:
+
+ $ asciidoctor -r asciidoctor-mathematical stem-sample.adoc
+
+If you're invoking Asciidoctor via the API, you must require the gem before invoking Asciidoctor:
+
+[source,ruby]
+----
+require 'asciidoctor-mathematical'
+
+Asciidoctor.convert_file 'stem-sample.adoc', safe: :safe
+----
+
+When the extension is activated, it will automatically find STEM nodes in the parsed document and replace them with images.
+
+== Improve image resolution
+
+To get the best quality output and maximize speed of conversion, you should configure Asciidoctor Mathematical to generate SVG files.
+You control this setting using the `mathematical-format` AsciiDoc attribute as follows:
+
+ $ asciidoctor -r asciidoctor-mathematical -a mathematical-format=svg stem-sample.adoc
+
+The extension will now generate SVG images instead of PNG images.
+
+== More info
+
+To learn more about how to use this extension and the options it provides, see the {url-asciidoctor-mathematical}[project's README].
diff --git a/docs/modules/stem/pages/mathjax.adoc b/docs/modules/stem/pages/mathjax.adoc
index b27c7928..a3d95fe1 100644
--- a/docs/modules/stem/pages/mathjax.adoc
+++ b/docs/modules/stem/pages/mathjax.adoc
@@ -1,7 +1,48 @@
-= MathJax
+// TODO: document how to change eqnums
+= MathJax and HTML
 :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
+:stem:
 
-{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.
+{url-mathjax}[MathJax^] is a JavaScript library for displaying interactive LaTeX, AsciiMath, and MathML expressions in the browser.
+The Asciidoctor HTML converter integrates with MathJax to provide STEM processing for {url-asciimath}[AsciiMath^] and {url-latexmath}[TeX and LaTeX^] notation used in the AsciiDoc document.
+This integration offers simple, out-of-the-box support for STEM content when converting to HTML.
+
+== How it works
+
+If you convert your document to HTML using the HTML converter, and the `stem` document attribute is set on your document, the HTML will be configured to automatically load MathJax into the page from a CDN.
+There's nothing you have to install.
+Specifically, it loads the MathJax bundle that includes support for both TeX and AsciiMath, as shown here:
+
+[source,html]
+----
+<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js?config=TeX-MML-AM_HTMLorMML"></script>
+----
+
+After the page loads, MathJax scans for expressions inside special delimiters and transforms them into a displayable format.
+You may notice a brief flash of the expression in source form while this is happening.
+
+Here's an example of a STEM expression written in AsciiMath and rendered by MathJax.
+
+[stem]
+++++
+e = sum_(n=0)^oo 1 / n!
+++++
+
+If you right click on the rendered expression, you'll notice its interactive.
+One of the options even allows you to view the original AsciiMath input.
+
+== Custom delimiters
+
+The delimiters that the HTML converter places around the expressions to tell MathJax what to process are not the same as the ones MathJax looks for by default.
+These custom delimiters were chosen to avoid conflicts with other syntax in the AsciiDoc language.
+
+The converter configures MathJax to look for the custom delimiters it emits.
+If you look at the HTML source, you'll see a text/x-mathjax-config stanza that defines them, as well as some other settings.
+
+== Alternatives
+
+The MathJax integration is currently only designed for HTML output.
+When converting to other backend formats, additional libraries are needed.
+A good alternative is xref:mathematical.adoc[].
-- 
cgit v1.2.3


From f096ff14e7aa881d0bb797e481ae2b66daccdebd Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Mon, 23 Nov 2020 17:44:00 -0700
Subject: rename source-highlighters module to syntax-highlighting

---
 .../pages/source-highlighting-stylesheets.adoc     |   2 +-
 docs/modules/source-highlighters/nav.adoc          |   5 -
 .../modules/source-highlighters/pages/coderay.adoc | 107 --------------
 .../source-highlighters/pages/highlightjs.adoc     |  42 ------
 docs/modules/source-highlighters/pages/index.adoc  |  32 -----
 .../source-highlighters/pages/pygments.adoc        | 156 ---------------------
 docs/modules/source-highlighters/pages/rouge.adoc  |  70 ---------
 docs/modules/syntax-highlighting/nav.adoc          |   5 +
 .../modules/syntax-highlighting/pages/coderay.adoc | 107 ++++++++++++++
 .../syntax-highlighting/pages/highlightjs.adoc     |  42 ++++++
 docs/modules/syntax-highlighting/pages/index.adoc  |  32 +++++
 .../syntax-highlighting/pages/pygments.adoc        | 156 +++++++++++++++++++++
 docs/modules/syntax-highlighting/pages/rouge.adoc  |  70 +++++++++
 13 files changed, 413 insertions(+), 413 deletions(-)
 delete mode 100644 docs/modules/source-highlighters/nav.adoc
 delete mode 100644 docs/modules/source-highlighters/pages/coderay.adoc
 delete mode 100644 docs/modules/source-highlighters/pages/highlightjs.adoc
 delete mode 100644 docs/modules/source-highlighters/pages/index.adoc
 delete mode 100644 docs/modules/source-highlighters/pages/pygments.adoc
 delete mode 100644 docs/modules/source-highlighters/pages/rouge.adoc
 create mode 100644 docs/modules/syntax-highlighting/nav.adoc
 create mode 100644 docs/modules/syntax-highlighting/pages/coderay.adoc
 create mode 100644 docs/modules/syntax-highlighting/pages/highlightjs.adoc
 create mode 100644 docs/modules/syntax-highlighting/pages/index.adoc
 create mode 100644 docs/modules/syntax-highlighting/pages/pygments.adoc
 create mode 100644 docs/modules/syntax-highlighting/pages/rouge.adoc

(limited to 'docs/modules')

diff --git a/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc b/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc
index 0b9ad08a..447595ad 100644
--- a/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc
+++ b/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc
@@ -7,7 +7,7 @@ Asciidoctor can embed the stylesheet for the CodeRay or Pygments syntax highligh
 == Requirements
 
 First, make sure the appropriate library is installed on your system.
-See xref:source-highlighters:rouge.adoc[], xref:source-highlighters:coderay.adoc[], or xref:source-highlighters:pygments.adoc[] for installation instructions.
+See xref:syntax-highlighting:rouge.adoc[], xref:syntax-highlighting:coderay.adoc[], or xref:syntax-highlighting: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]
diff --git a/docs/modules/source-highlighters/nav.adoc b/docs/modules/source-highlighters/nav.adoc
deleted file mode 100644
index 7464bc7e..00000000
--- a/docs/modules/source-highlighters/nav.adoc
+++ /dev/null
@@ -1,5 +0,0 @@
-* xref:index.adoc[]
-** xref:highlightjs.adoc[]
-** xref:rouge.adoc[]
-** xref:coderay.adoc[]
-** xref:pygments.adoc[]
diff --git a/docs/modules/source-highlighters/pages/coderay.adoc b/docs/modules/source-highlighters/pages/coderay.adoc
deleted file mode 100644
index c7b035a9..00000000
--- a/docs/modules/source-highlighters/pages/coderay.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-= 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:source-highlighting-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/source-highlighters/pages/highlightjs.adoc b/docs/modules/source-highlighters/pages/highlightjs.adoc
deleted file mode 100644
index 17372031..00000000
--- a/docs/modules/source-highlighters/pages/highlightjs.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-= 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/source-highlighters/pages/index.adoc b/docs/modules/source-highlighters/pages/index.adoc
deleted file mode 100644
index 4312be25..00000000
--- a/docs/modules/source-highlighters/pages/index.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-= Source Highlighting
-
-[%autowidth]
-|===
-| |Syntax Highlighter |Supported Versions |Converters
-
-|Client-side highlighting for source code blocks
-
-|Highlight.js
-|9.18.3
-|HTML
-
-.3+|Server-side highlighting for source code blocks
-
-|CodeRay
-|1.1.2
-|HTML
-
-|Pygments
-|2.2.0
-|HTML
-
-|Rouge
-|3.1.1
-|HTML
-|===
-
-////
-|Inline, admonition or callout font-based icons
-|Font Awesome
-|4.7
-////
diff --git a/docs/modules/source-highlighters/pages/pygments.adoc b/docs/modules/source-highlighters/pages/pygments.adoc
deleted file mode 100644
index a049b690..00000000
--- a/docs/modules/source-highlighters/pages/pygments.adoc
+++ /dev/null
@@ -1,156 +0,0 @@
-= 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:source-highlighting-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/source-highlighters/pages/rouge.adoc b/docs/modules/source-highlighters/pages/rouge.adoc
deleted file mode 100644
index b6022864..00000000
--- a/docs/modules/source-highlighters/pages/rouge.adoc
+++ /dev/null
@@ -1,70 +0,0 @@
-= 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/syntax-highlighting/nav.adoc b/docs/modules/syntax-highlighting/nav.adoc
new file mode 100644
index 00000000..7464bc7e
--- /dev/null
+++ b/docs/modules/syntax-highlighting/nav.adoc
@@ -0,0 +1,5 @@
+* xref:index.adoc[]
+** xref:highlightjs.adoc[]
+** xref:rouge.adoc[]
+** xref:coderay.adoc[]
+** xref:pygments.adoc[]
diff --git a/docs/modules/syntax-highlighting/pages/coderay.adoc b/docs/modules/syntax-highlighting/pages/coderay.adoc
new file mode 100644
index 00000000..c7b035a9
--- /dev/null
+++ b/docs/modules/syntax-highlighting/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:source-highlighting-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/syntax-highlighting/pages/highlightjs.adoc b/docs/modules/syntax-highlighting/pages/highlightjs.adoc
new file mode 100644
index 00000000..17372031
--- /dev/null
+++ b/docs/modules/syntax-highlighting/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/syntax-highlighting/pages/index.adoc b/docs/modules/syntax-highlighting/pages/index.adoc
new file mode 100644
index 00000000..bc3d4222
--- /dev/null
+++ b/docs/modules/syntax-highlighting/pages/index.adoc
@@ -0,0 +1,32 @@
+= Syntax Highlighting
+
+[%autowidth]
+|===
+| |Syntax Highlighter |Supported Versions |Converters
+
+|Client-side highlighting for source code blocks
+
+|Highlight.js
+|9.18.3
+|HTML
+
+.3+|Server-side highlighting for source code blocks
+
+|CodeRay
+|1.1.2
+|HTML
+
+|Pygments
+|2.2.0
+|HTML
+
+|Rouge
+|3.1.1
+|HTML
+|===
+
+////
+|Inline, admonition or callout font-based icons
+|Font Awesome
+|4.7
+////
diff --git a/docs/modules/syntax-highlighting/pages/pygments.adoc b/docs/modules/syntax-highlighting/pages/pygments.adoc
new file mode 100644
index 00000000..a049b690
--- /dev/null
+++ b/docs/modules/syntax-highlighting/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:source-highlighting-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/syntax-highlighting/pages/rouge.adoc b/docs/modules/syntax-highlighting/pages/rouge.adoc
new file mode 100644
index 00000000..b6022864
--- /dev/null
+++ b/docs/modules/syntax-highlighting/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'
+}
+----
+....
-- 
cgit v1.2.3


From bab6916f2a8cf7bf3791c08e90aee02dee7a7725 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Tue, 24 Nov 2020 17:49:00 -0700
Subject: write intro for Syntax Highlighting; document how to create a custom
 adapter

- explain what source highlighting is
- explain difference between client-side and build-time syntax highlighter
- rework table that summarizes built-in syntax highlighters
- clarify that Asciidoctor does not apply syntax highlighting when producing DocBook
- add page about how to create a custom adapter
---
 .../examples/syntax-highlighter-prism.rb           | 25 ++++++
 docs/modules/syntax-highlighting/nav.adoc          |  1 +
 docs/modules/syntax-highlighting/pages/custom.adoc | 22 ++++++
 docs/modules/syntax-highlighting/pages/index.adoc  | 88 ++++++++++++++++++----
 4 files changed, 120 insertions(+), 16 deletions(-)
 create mode 100644 docs/modules/syntax-highlighting/examples/syntax-highlighter-prism.rb
 create mode 100644 docs/modules/syntax-highlighting/pages/custom.adoc

(limited to 'docs/modules')

diff --git a/docs/modules/syntax-highlighting/examples/syntax-highlighter-prism.rb b/docs/modules/syntax-highlighting/examples/syntax-highlighter-prism.rb
new file mode 100644
index 00000000..8233c83e
--- /dev/null
+++ b/docs/modules/syntax-highlighting/examples/syntax-highlighter-prism.rb
@@ -0,0 +1,25 @@
+class PrismSyntaxHighlighter < Asciidoctor::SyntaxHighlighter::Base
+  register_for 'prism'
+
+  def format node, lang, opts
+    opts[:transform] = proc do |pre, code|
+      code['class'] = %(language-#{lang}) if lang
+    end
+    super
+  end
+
+  def docinfo? location
+    location == :footer
+  end
+
+  def docinfo location, doc, opts
+    base_url = doc.attr 'prismdir', %(#{opts[:cdn_base_url]}/prism/1.15.0)
+    slash = opts[:self_closing_tag_slash]
+    unless (theme_name = doc.attr 'prism-style', 'prism') == 'prism'
+      theme_name = %(prism-#{theme_name})
+    end
+    %(<link rel="stylesheet" href="#{base_url}/themes/#{theme_name}.min.css"#{slash}>
+<script src="#{base_url}/prism.min.js"></script>
+<script src="#{base_url}/components/prism-ruby.min.js"></script>)
+  end
+end
diff --git a/docs/modules/syntax-highlighting/nav.adoc b/docs/modules/syntax-highlighting/nav.adoc
index 7464bc7e..42bd9048 100644
--- a/docs/modules/syntax-highlighting/nav.adoc
+++ b/docs/modules/syntax-highlighting/nav.adoc
@@ -3,3 +3,4 @@
 ** xref:rouge.adoc[]
 ** xref:coderay.adoc[]
 ** xref:pygments.adoc[]
+** xref:custom.adoc[]
diff --git a/docs/modules/syntax-highlighting/pages/custom.adoc b/docs/modules/syntax-highlighting/pages/custom.adoc
new file mode 100644
index 00000000..21d600f2
--- /dev/null
+++ b/docs/modules/syntax-highlighting/pages/custom.adoc
@@ -0,0 +1,22 @@
+= Custom Syntax Highlighter Adapter
+:navtitle: Custom Adapter
+
+You can integrate additional syntax highlighters by implementing a syntax highlighter adapter.
+
+To implement an adapter, you must create a class that extends the `Asciidoctor::SyntaxHighlighter::Base` class, register the adapter for a value of the `source-highlighter` attribute, and implement the required methods depending on whether the highlight step runs in the converter or in the client (i.e., browser).
+
+Here's an example of how to write and register a syntax highlighter adapter for the Prism.js syntax highlighting library.
+This library runs in the browser, so the methods focus on loading the library.
+
+.Syntax highlighter adapter for Prism.js
+[source,ruby]
+----
+include::example$syntax-highlighter-prism.rb[]
+----
+
+Save this code to a file named [.path]_syntax-highlighter-prism.rb_.
+Then require this file when invoking Asciidoctor and set the source-highlighter to prism to activate it:
+
+ $ asciidoctor -r ./syntax-highlighter-prism -a source-highlighter=prism document.adoc
+
+You can also define an adapter for a syntax highlighter that runs during conversion.
diff --git a/docs/modules/syntax-highlighting/pages/index.adoc b/docs/modules/syntax-highlighting/pages/index.adoc
index bc3d4222..153e0907 100644
--- a/docs/modules/syntax-highlighting/pages/index.adoc
+++ b/docs/modules/syntax-highlighting/pages/index.adoc
@@ -1,32 +1,88 @@
 = Syntax Highlighting
 
+AsciiDoc defines a style of listing block known as a source block for adding a source code listing to a document that's intended to be colorized by a syntax highlighter.
+Here's a simple example of a source block:
+
+[source]
+....
+[source,ruby]
+----
+puts "Hello, World!"
+----
+....
+
+Here's how we expect it to appear:
+
+[source,ruby]
+----
+puts "Hello, World!"
+----
+
+It's up to an AsciiDoc processor such as Asciidoctor to apply the syntax highlighting to this source block, a process referred to as *source highlighting*.
+Asciidoctor provides adapters that integrate with several popular syntax highlighter libraries to perform this task.
+It also provides an interface for implementing a custom syntax highlighter adapter.
+
+== Syntax highlighter types
+
+Asciidoctor supports two types of syntax highlighters: client-side and build-time.
+Let's explore each type and how they work.
+
+A *client-side* syntax highlighter performs syntax highlighting in the browser as the page is loading.
+Asciidoctor does not invoke the syntax highlighter itself.
+Instead, it focuses on adding the assets to the generated HTML so the browser can load the syntax highlighter and run it.
+For this type of syntax highlighter, Asciidoctor passes the contents of the source block through to the output as is.
+It also adds metadata to the element so that the syntax highlighter knows to highlight it and which language it is.
+Unfortunately, Asciidoctor does not process callout numbers in the source block in this case, so they may cause the syntax highlighter to get tripped up.
+
+A *build-time* syntax highlighter performs syntax highlighting during AsciiDoc conversion.
+Asciidoctor does invoke the syntax highlighter in this case.
+It also takes care of hiding the callout numbers from the syntax highlighter, ensuring they are put back in the proper place afterwards.
+What Asciidoctor emits into the output is the result produced by the syntax highlighter, which are the tokens wrapped in `<span>` tags to apply color and other formatting (either inline or via CSS classes).
+These syntax highlighters tend to support more features because Asciidoctor has greater control over the process.
+
+=== Client-side vs build-time
+
+There are benefits and drawbacks of each type.
+The benefit of a client-side syntax highlighter is that does not require installing any additional libraries.
+It also makes conversion faster and makes it produce smaller output since the syntax highlighting is deferred until page load.
+The main drawback is that callouts in the source block can be mangled by the syntax highlighter or confuse it.
+The benefits of a build-time syntax highlighter is that you have more control over syntax highlighting and can enable additional features such as line numbers and line highlighting.
+The main drawback is that it requires installing an extra library, it slows down conversion, and causes the output to be larger.
+
+You should try each syntax highlighter and find the one that works best for you.
+
+== Built-in syntax highlighter adapters
+
 [%autowidth]
 |===
-| |Syntax Highlighter |Supported Versions |Converters
+|Type |Syntax Highlighter |Required RubyGem |Compatible Converters
 
-|Client-side highlighting for source code blocks
+h|Client-side
 
 |Highlight.js
-|9.18.3
-|HTML
+|_n/a_
+|HTML, Reveal.js
 
-.3+|Server-side highlighting for source code blocks
+.3+h|Build-time
 
 |CodeRay
-|1.1.2
-|HTML
+|coderay (>= 1.1)
+|HTML, PDF, EPUB3, Reveal.js
 
 |Pygments
-|2.2.0
-|HTML
+|pygments.rb (>= 1.2)
+|HTML, PDF, EPUB3, Reveal.js
 
 |Rouge
-|3.1.1
-|HTML
+|rouge (>= 2)
+|HTML, PDF, EPUB3, Reveal.js
 |===
 
-////
-|Inline, admonition or callout font-based icons
-|Font Awesome
-|4.7
-////
+Asciidoctor does not apply syntax highlighting when generating DocBook.
+The assumption is that this is a task the DocBook toolchain can handle.
+The DocBook converter generates a `<programlisting>` tag for the source block and passes through the source language as specified in the AsciiDoc.
+It's then up to the DocBook toolchain to apply syntax highlighting to the contents of that tag.
+
+You can explore these integrations in depth on the xref:highlightjs.adoc[], xref:rouge.adoc[], xref:pygments.adoc[], and xref:coderay.adoc[] pages.
+
+You can also create your own integration by making a xref:custom.adoc[].
-- 
cgit v1.2.3


From 1cf222dc38aa31dacfc3b7c17360ad806e5ee19d Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Tue, 24 Nov 2020 15:06:42 -0700
Subject: clarify that highlightjs-languages only works when generating
 standalone HTML

---
 docs/modules/syntax-highlighting/pages/highlightjs.adoc | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

(limited to 'docs/modules')

diff --git a/docs/modules/syntax-highlighting/pages/highlightjs.adoc b/docs/modules/syntax-highlighting/pages/highlightjs.adoc
index 17372031..ab9c2fc3 100644
--- a/docs/modules/syntax-highlighting/pages/highlightjs.adoc
+++ b/docs/modules/syntax-highlighting/pages/highlightjs.adoc
@@ -19,7 +19,11 @@ The version of the highlight.js library Asciidoctor loads from the CDN only incl
 
 == 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):
+To load additional languages supported by highlight.js, list them in the value of the `highlightjs-languages` document attribute.
+Separate each language by a comma followed by an optional space.
+
+The common highlight.js bundle does not include support for Rust and Swift.
+Let's set the `highlightjs-languages` attribute so the HTML converter loads support for them into the HTML page.
 
 [source]
 ----
@@ -27,6 +31,9 @@ To load additional languages supported by highlight.js, list them in the value o
 :highlightjs-languages: rust, swift
 ----
 
+The `highlightjs-languages` attribute only applies when generating a standalone HTML document (i.e., backend: html, standalone: true).
+It does not work when generating embedded HTML, which is used by site generator integrations such as Antora.
+
 == 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:
-- 
cgit v1.2.3


From e6dd4eb33e546ae6265c715ca54267874638da57 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Tue, 24 Nov 2020 18:05:58 -0700
Subject: add intro on What's New page

---
 docs/modules/ROOT/pages/whats-new.adoc | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc
index 2ca77a17..8055e9bf 100644
--- a/docs/modules/ROOT/pages/whats-new.adoc
+++ b/docs/modules/ROOT/pages/whats-new.adoc
@@ -5,6 +5,9 @@
 :url-releases-asciidoctor: {url-org}/asciidoctor/releases
 :url-milestone: {url-org}/asciidoctor/milestone/33?closed=1:
 
+This page covers the changes introduced in each of the patch releases in the Asciidoctor {page-component-version} release line ({page-component-version}.0, {page-component-version}.1, ...).
+The releases are ordered from newest to oldest.
+
 _**Cumulative issues resolved:** {url-milestone}[2.0.x^]_
 
 = Asciidoctor 2.0.11
-- 
cgit v1.2.3


From 4d22dd41573291c1ab0a4a9bcb2602f3720ba62f Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Wed, 25 Nov 2020 14:26:37 -0700
Subject: rename Language Support to Localization Support and revise intro

---
 docs/modules/ROOT/nav-lang.adoc                   |   2 +-
 docs/modules/ROOT/pages/language-support.adoc     | 159 ---------------------
 docs/modules/ROOT/pages/localization-support.adoc | 161 ++++++++++++++++++++++
 docs/modules/migrate/pages/asciidoc-python.adoc   |   2 +-
 4 files changed, 163 insertions(+), 161 deletions(-)
 delete mode 100644 docs/modules/ROOT/pages/language-support.adoc
 create mode 100644 docs/modules/ROOT/pages/localization-support.adoc

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/nav-lang.adoc b/docs/modules/ROOT/nav-lang.adoc
index 278dbd67..66a55323 100644
--- a/docs/modules/ROOT/nav-lang.adoc
+++ b/docs/modules/ROOT/nav-lang.adoc
@@ -1 +1 @@
-* xref:language-support.adoc[]
+* xref:localization-support.adoc[]
diff --git a/docs/modules/ROOT/pages/language-support.adoc b/docs/modules/ROOT/pages/language-support.adoc
deleted file mode 100644
index 362411d0..00000000
--- a/docs/modules/ROOT/pages/language-support.adoc
+++ /dev/null
@@ -1,159 +0,0 @@
-= 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,cols="m,,"]
-|===
-|Attribute |Default English Value |Notes
-
-|appendix-caption
-|Appendix
-|
-
-|caution-caption
-|Caution
-|
-
-|chapter-label
-|Chapter
-|Applies only when `doctype` is `book`.
-PDF converter only.
-
-|example-caption
-|Example
-|
-
-|figure-caption
-|Figure
-|
-
-|important-caption
-|Important
-|
-
-|last-update-label
-|Last updated
-|
-
-|listing-caption
-|_not set_
-|By default, listing blocks do not have captions.
-Specify `listing-caption` to turn on listing block captions.
-
-|manname-title
-|NAME
-|Applies only when `doctype` is `manpage`.
-
-|note-caption
-|Note
-|
-
-|preface-title
-|_not set_
-|Applies only when `doctype` is `book`.
-
-|table-caption
-|Table
-|
-
-|tip-caption
-|Tip
-|
-
-|toc-title
-|Table of Contents
-|
-
-|untitled-label
-|Untitled
-|
-
-|version-label
-|Version
-|
-
-|warning-caption
-|Warning
-|
-|===
-
-If you plan to support multiple languages, you'll want to define the attributes for each language inside a xref:asciidoc:directives:conditionals.adoc[conditional preprocessor directive].
-For example:
-
-[source,asciidoc]
-----
-\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/localization-support.adoc b/docs/modules/ROOT/pages/localization-support.adoc
new file mode 100644
index 00000000..2e1bb934
--- /dev/null
+++ b/docs/modules/ROOT/pages/localization-support.adoc
@@ -0,0 +1,161 @@
+= Localization 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
+
+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.
+The built-in labels that are used in the output generated by Asciidoctor are English by default.
+These labels can be modified by changing the value of the corresponding attributes.
+
+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,cols="m,,"]
+|===
+|Attribute |Default English Value |Notes
+
+|appendix-caption
+|Appendix
+|
+
+|caution-caption
+|Caution
+|
+
+|chapter-label
+|Chapter
+|Applies only when `doctype` is `book`.
+PDF converter only.
+
+|example-caption
+|Example
+|
+
+|figure-caption
+|Figure
+|
+
+|important-caption
+|Important
+|
+
+|last-update-label
+|Last updated
+|
+
+|listing-caption
+|_not set_
+|By default, listing blocks do not have captions.
+Specify `listing-caption` to turn on listing block captions.
+
+|manname-title
+|NAME
+|Applies only when `doctype` is `manpage`.
+
+|note-caption
+|Note
+|
+
+|preface-title
+|_not set_
+|Applies only when `doctype` is `book`.
+
+|table-caption
+|Table
+|
+
+|tip-caption
+|Tip
+|
+
+|toc-title
+|Table of Contents
+|
+
+|untitled-label
+|Untitled
+|
+
+|version-label
+|Version
+|
+
+|warning-caption
+|Warning
+|
+|===
+
+If you plan to support multiple languages, you'll want to define the attributes for each language inside a xref:asciidoc:directives:conditionals.adoc[conditional preprocessor directive].
+For example:
+
+[source,asciidoc]
+----
+\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/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc
index 56d4b608..f9424cdf 100644
--- a/docs/modules/migrate/pages/asciidoc-python.adoc
+++ b/docs/modules/migrate/pages/asciidoc-python.adoc
@@ -264,7 +264,7 @@ Instead, Asciidoctor provides an xref:extensions:register.adoc[extension API] th
 
 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.
+See xref:ROOT:localization-support.adoc[language support] for details.
 
 [#migrate-extensions]
 == AsciiDoc.py extensions
-- 
cgit v1.2.3


From ddf574ba80c64d0c77dcd1f533aca874710907b4 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Thu, 26 Nov 2020 01:34:22 -0700
Subject: add additional explicit IDs to content

---
 docs/modules/ROOT/pages/docinfo.adoc            | 8 +++++---
 docs/modules/install/pages/linux-packaging.adoc | 5 +++++
 docs/modules/install/pages/ruby-packaging.adoc  | 3 ++-
 3 files changed, 12 insertions(+), 4 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/pages/docinfo.adoc b/docs/modules/ROOT/pages/docinfo.adoc
index 2c2cc28c..0c5959ff 100644
--- a/docs/modules/ROOT/pages/docinfo.adoc
+++ b/docs/modules/ROOT/pages/docinfo.adoc
@@ -87,7 +87,7 @@ 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]
 == Footer docinfo files
 
 Footer docinfo files are differentiated from head docinfo files by the addition of `-footer` to the file name.
@@ -104,7 +104,7 @@ To disable the "Last updated" line in the footer, unassign the attribute `last-u
 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]
 == 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`").
@@ -134,7 +134,7 @@ The file extension of the docinfo file must match the file extension of the outp
 |`docinfo-footer<outfilesuffix>`
 |===
 
-[#enable-docinfo]
+[#enable]
 == Enabling docinfo
 
 To specify which file(s) you want to apply, set the `docinfo` attribute to any combination of these values:
@@ -186,6 +186,7 @@ You also want to include some additional content, but only to the head of [.path
 
 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.
 
+[#resolving]
 == Locating docinfo files
 
 By default, docinfo files are searched for in the same folder as the document file.
@@ -198,6 +199,7 @@ If you want to keep them anywhere else, set the `docinfodir` attribute to their
 
 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]
 == Attribute substitution in docinfo files
 
 Docinfo files may include attribute references.
diff --git a/docs/modules/install/pages/linux-packaging.adoc b/docs/modules/install/pages/linux-packaging.adoc
index 5df8c1f0..940fecf3 100644
--- a/docs/modules/install/pages/linux-packaging.adoc
+++ b/docs/modules/install/pages/linux-packaging.adoc
@@ -40,6 +40,7 @@ To install the package, open a terminal and type:
 
 include::partial$success.adoc[]
 
+[#apk]
 == apk (Alpine Linux)
 
 To install the gem on Alpine Linux, open a terminal and type:
@@ -48,6 +49,7 @@ To install the gem on Alpine Linux, open a terminal and type:
 
 include::partial$success.adoc[]
 
+[#pacman]
 == pacman (Arch Linux)
 
 To install the gem on Arch-based distributions, open a terminal and type:
@@ -65,18 +67,21 @@ If you need to upgrade to the latest version immediately, use xref:ruby-packagin
 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.
 
+[#upgrade-apt]
 === APT
 
 On Debian and Debian-based distributions, update the Asciidoctor package using:
 
  $ sudo apt-get upgrade -y asciidoctor
 
+[#upgrade-dnf]
 === DNF
 
 On Fedora and other RPM-based distributions, you can update the package using:
 
  $ sudo dnf update -y asciidoctor
 
+[#upgrade-apk]
 === apk (Alpine Linux)
 
 On Alpine Linux, update the Asciidoctor package using:
diff --git a/docs/modules/install/pages/ruby-packaging.adoc b/docs/modules/install/pages/ruby-packaging.adoc
index ea9e0994..a07cfe16 100644
--- a/docs/modules/install/pages/ruby-packaging.adoc
+++ b/docs/modules/install/pages/ruby-packaging.adoc
@@ -41,13 +41,14 @@ gem 'asciidoctor'
 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.
 
+[#gem-update]
 == 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.
+Simply put, system gems should only be updated 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.
-- 
cgit v1.2.3


From 5f79e05fb9cc115e897a569de2eecbf35f962d33 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Mon, 30 Nov 2020 01:43:22 -0700
Subject: update application message when include file falls outside of jail

---
 docs/modules/ROOT/pages/errors-and-warnings.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/pages/errors-and-warnings.adoc b/docs/modules/ROOT/pages/errors-and-warnings.adoc
index 9b3c2dee..7799f7ce 100644
--- a/docs/modules/ROOT/pages/errors-and-warnings.adoc
+++ b/docs/modules/ROOT/pages/errors-and-warnings.adoc
@@ -170,7 +170,7 @@ In source listings, is the callout the last thing on the line?
 |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
+|include file has illegal reference to ancestor of jail; recovering automatically
 |The safe mode is restricting access to an include file outside of the base directory.
 |#running-asciidoctor-securely#
 
-- 
cgit v1.2.3


From b5af8e2d8d66d24d9ac03d2bbfac66c74872ac78 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Mon, 30 Nov 2020 18:21:31 -0700
Subject: switch fenced code blocks to AsciiDoc source blocks and always set
 language

---
 docs/modules/ROOT/pages/localization-support.adoc      |  2 +-
 .../extensions/pages/block-macro-processor.adoc        | 15 +++++++++------
 docs/modules/extensions/pages/block-processor.adoc     | 15 +++++++++------
 .../extensions/pages/compound-block-processor.adoc     |  2 +-
 docs/modules/extensions/pages/docinfo-processor.adoc   | 10 ++++++----
 docs/modules/extensions/pages/include-processor.adoc   | 15 +++++++++------
 .../extensions/pages/inline-macro-processor.adoc       | 15 +++++++++------
 docs/modules/extensions/pages/postprocessor.adoc       | 10 ++++++----
 docs/modules/extensions/pages/preprocessor.adoc        | 18 ++++++++++--------
 docs/modules/extensions/pages/register.adoc            |  5 +++--
 docs/modules/extensions/pages/tree-processor.adoc      | 15 +++++++++------
 docs/modules/html-backend/pages/custom-stylesheet.adoc |  8 ++++----
 docs/modules/html-backend/pages/stylesheet-modes.adoc  |  4 ++--
 .../modules/html-backend/pages/verbatim-line-wrap.adoc |  2 +-
 docs/modules/install/pages/ruby-packaging.adoc         |  2 +-
 docs/modules/install/pages/windows.adoc                |  5 +----
 docs/modules/migrate/pages/asciidoc-python.adoc        |  4 ++--
 docs/modules/stem/pages/asciimath-gem.adoc             |  2 +-
 docs/modules/syntax-highlighting/pages/coderay.adoc    |  4 ++--
 .../modules/syntax-highlighting/pages/highlightjs.adoc |  4 ++--
 docs/modules/syntax-highlighting/pages/index.adoc      |  2 +-
 docs/modules/syntax-highlighting/pages/pygments.adoc   |  4 ++--
 docs/modules/syntax-highlighting/pages/rouge.adoc      |  4 ++--
 23 files changed, 93 insertions(+), 74 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/pages/localization-support.adoc b/docs/modules/ROOT/pages/localization-support.adoc
index 2e1bb934..2d39c52a 100644
--- a/docs/modules/ROOT/pages/localization-support.adoc
+++ b/docs/modules/ROOT/pages/localization-support.adoc
@@ -139,7 +139,7 @@ To use this file to translate the built-in labels according the value of the `la
 . Put the file in the folder [.path]_locale_ relative to your document.
 . Add the following line to the header of your AsciiDoc document:
 +
-[source]
+[source,asciidoc]
 ----
 \include::locale/attributes.adoc[]
 ----
diff --git a/docs/modules/extensions/pages/block-macro-processor.adoc b/docs/modules/extensions/pages/block-macro-processor.adoc
index df451c43..45ef1dc8 100644
--- a/docs/modules/extensions/pages/block-macro-processor.adoc
+++ b/docs/modules/extensions/pages/block-macro-processor.adoc
@@ -6,14 +6,16 @@ Create a block macro named `gist` for embedding a gist.
 
 == sample-with-gist-macro.adoc
 
-```
+[source,asciidoc]
+----
 .My Gist
 gist::123456[]
-```
+----
 
 == GistBlockMacro
 
-```ruby
+[source,ruby]
+----
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 
@@ -35,14 +37,15 @@ class GistBlockMacro < Asciidoctor::Extensions::BlockMacroProcessor
     create_pass_block parent, html, attrs, subs: nil
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,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
index d228642e..fb04cbca 100644
--- a/docs/modules/extensions/pages/block-processor.adoc
+++ b/docs/modules/extensions/pages/block-processor.adoc
@@ -6,14 +6,16 @@ Register a custom block style named `shout` that uppercases all the words and co
 
 == sample-with-shout-block.adoc
 
-```
+[source,asciidoc]
+----
 [shout]
 The time is now. Get a move on.
-```
+----
 
 == ShoutBlock
 
-```ruby
+[source,ruby]
+----
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 
@@ -32,14 +34,15 @@ class ShoutBlock < Asciidoctor::Extensions::BlockProcessor
     create_paragraph parent, (reader.lines.map {|l| l.upcase.gsub PeriodRx, '!' * volume }), attrs
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,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
index 32dea0e4..cd88a3b6 100644
--- a/docs/modules/extensions/pages/compound-block-processor.adoc
+++ b/docs/modules/extensions/pages/compound-block-processor.adoc
@@ -9,7 +9,7 @@ Register a custom block named `collapsible` that transforms a listing block into
 * 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]
+[source,asciidoc]
 ....
 .Show JSON
 [collapsible,json]
diff --git a/docs/modules/extensions/pages/docinfo-processor.adoc b/docs/modules/extensions/pages/docinfo-processor.adoc
index d5510c1a..084937e3 100644
--- a/docs/modules/extensions/pages/docinfo-processor.adoc
+++ b/docs/modules/extensions/pages/docinfo-processor.adoc
@@ -6,7 +6,8 @@ Appends the Google Analytics tracking code to the bottom of an HTML document.
 
 == GoogleAnalyticsDocinfoProcessor
 
-```ruby
+[source,ruby]
+----
 class GoogleAnalyticsDocinfoProcessor < Asciidoctor::Extensions::DocinfoProcessor
   use_dsl
   at_location :footer
@@ -22,15 +23,16 @@ ga('send','pageview');
 </script>)
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,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
index 8dbdd8e0..be27729a 100644
--- a/docs/modules/extensions/pages/include-processor.adoc
+++ b/docs/modules/extensions/pages/include-processor.adoc
@@ -8,7 +8,8 @@ TIP: Asciidoctor supports including content from a URI out of the box if you set
 
 == sample-with-uri-include.adoc
 
-```
+[source,asciidoc]
+....
 :source-highlighter: coderay
 
 .Gemfile
@@ -16,11 +17,12 @@ TIP: Asciidoctor supports including content from a URI out of the box if you set
 ----
 \include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/Gemfile[]
 ----
-```
+....
 
 == UriIncludeProcessor
 
-```ruby
+[source,ruby]
+----
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 require 'open-uri'
@@ -36,14 +38,15 @@ class UriIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
     reader
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,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/inline-macro-processor.adoc b/docs/modules/extensions/pages/inline-macro-processor.adoc
index b8d88b0e..69a8b89e 100644
--- a/docs/modules/extensions/pages/inline-macro-processor.adoc
+++ b/docs/modules/extensions/pages/inline-macro-processor.adoc
@@ -6,13 +6,15 @@ Create an inline macro named `man` that links to a manpage.
 
 == sample-with-man-link.adoc
 
-```
+[source,asciidoc]
+----
 See man:gittutorial[7] to get started.
-```
+----
 
 == ManpageInlineMacro
 
-```ruby
+[source,ruby]
+----
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 
@@ -35,14 +37,15 @@ class ManInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
     %(#{(create_anchor parent, text, type: :link, target: target).convert}#{suffix})
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,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
index 712706ea..61be2401 100644
--- a/docs/modules/extensions/pages/postprocessor.adoc
+++ b/docs/modules/extensions/pages/postprocessor.adoc
@@ -6,7 +6,8 @@ Insert copyright text in the footer.
 
 == CopyrightFooterPostprocessor
 
-```ruby
+[source,ruby]
+----
 class CopyrightFooterPostprocessor < Asciidoctor::Extensions::Postprocessor
   def process document, output
     content = (document.attr 'copyright') || 'Copyright Acme, Inc.'
@@ -20,14 +21,15 @@ class CopyrightFooterPostprocessor < Asciidoctor::Extensions::Postprocessor
     output
   end
 end
-```
+----
 
 == Usage
 
-```
+[source,ruby]
+----
 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
index c1e5a406..aa32516c 100644
--- a/docs/modules/extensions/pages/preprocessor.adoc
+++ b/docs/modules/extensions/pages/preprocessor.adoc
@@ -6,26 +6,27 @@ Skim off front matter from the top of the document that gets used by site genera
 
 == sample-with-front-matter.adoc
 
-```
----
+[source,asciidoc]
+----
 tags: [announcement, website]
 ---
 = Document Title
 
 content
 
-[subs="attributes,specialcharacters"]
+[subs=+attributes]
 .Captured front matter
 ....
 ---
 {front-matter}
 ---
 ....
-```
+----
 
 == FrontMatterPreprocessor
 
-```ruby
+[source,ruby]
+----
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 
@@ -53,14 +54,15 @@ class FrontMatterPreprocessor < Asciidoctor::Extensions::Preprocessor
     reader
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,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
index 7e076ba1..468398ef 100644
--- a/docs/modules/extensions/pages/register.adoc
+++ b/docs/modules/extensions/pages/register.adoc
@@ -4,7 +4,8 @@
 
 These extensions are registered per document using a callback that feels like a DSL:
 
-```ruby
+[source,ruby]
+----
 Asciidoctor::Extensions.register do |document|
   preprocessor FrontMatterPreprocessor
   tree_processor ShellSessionTreeProcessor
@@ -15,7 +16,7 @@ Asciidoctor::Extensions.register do |document|
   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.
diff --git a/docs/modules/extensions/pages/tree-processor.adoc b/docs/modules/extensions/pages/tree-processor.adoc
index 050737ed..00a66436 100644
--- a/docs/modules/extensions/pages/tree-processor.adoc
+++ b/docs/modules/extensions/pages/tree-processor.adoc
@@ -6,16 +6,18 @@ Detect literal blocks that contain shell commands, strip the prompt character an
 
 == sample-with-shell-session.adoc
 
-```
+[source,asciidoc]
+----
  $ echo "Hello, World!"
  > Hello, World!
 
  $ gem install asciidoctor
-```
+----
 
 == ShellSessionTreeProcessor
 
-```ruby
+[source,ruby]
+----
 class ShellSessionTreeProcessor < Asciidoctor::Extensions::TreeProcessor
   def process document
     return unless document.blocks?
@@ -53,17 +55,18 @@ class ShellSessionTreeProcessor < Asciidoctor::Extensions::TreeProcessor
     create_listing_block block.document, lines * EOL, attrs, subs: nil
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,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.
diff --git a/docs/modules/html-backend/pages/custom-stylesheet.adoc b/docs/modules/html-backend/pages/custom-stylesheet.adoc
index c3615dfe..578681f4 100644
--- a/docs/modules/html-backend/pages/custom-stylesheet.adoc
+++ b/docs/modules/html-backend/pages/custom-stylesheet.adoc
@@ -30,7 +30,7 @@ Now let's use the `stylesheet` attribute to apply it.
 The `stylesheet` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
-[source]
+[source,asciidoc]
 ----
 = My First Experience with the Dangers of Documentation
 :stylesheet: my-stylesheet.css
@@ -77,7 +77,7 @@ Now we need to tell Asciidoctor where it's located using `stylesdir`.
 The `stylesdir` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
-[source]
+[source,asciidoc]
 ----
 = My First Experience with the Dangers of Documentation
 :stylesheet: my-stylesheet.css
@@ -190,14 +190,14 @@ Let's say you have three AsciiDoc documents saved in the following directory str
 
 For [.path]_a.adoc_ and [.path]_b.adoc_, set `stylesdir` to:
 
-[source]
+[source,asciidoc]
 ----
 :stylesdir: my-styles
 ----
 
 For [.path]_c.adoc_, set `stylesdir` to:
 
-[source]
+[source,asciidoc]
 ----
 :stylesdir: ../my-styles
 ----
diff --git a/docs/modules/html-backend/pages/stylesheet-modes.adoc b/docs/modules/html-backend/pages/stylesheet-modes.adoc
index 10672215..8b2fdd90 100644
--- a/docs/modules/html-backend/pages/stylesheet-modes.adoc
+++ b/docs/modules/html-backend/pages/stylesheet-modes.adoc
@@ -32,7 +32,7 @@ If the `linkcss` document attribute is set, the converter will take this hint to
 The `linkcss` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
-[source]
+[source,asciidoc]
 ----
 = My First Experience with the Dangers of Documentation
 :linkcss:
@@ -93,7 +93,7 @@ To prevent Asciidoctor from copying the stylesheet independent of safe mode, uns
 The `copycss` document attribute must be unset by the end of the header to be effective.
 One way to do that is to unset the attribute in the document header:
 
-[source]
+[source,asciidoc]
 ----
 = My First Experience with the Dangers of Documentation
 :linkcss:
diff --git a/docs/modules/html-backend/pages/verbatim-line-wrap.adoc b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc
index f38b7daa..a032a193 100644
--- a/docs/modules/html-backend/pages/verbatim-line-wrap.adoc
+++ b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc
@@ -30,7 +30,7 @@ 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]
+[source,asciidoc]
 ----
 :prewrap!:
 ----
diff --git a/docs/modules/install/pages/ruby-packaging.adoc b/docs/modules/install/pages/ruby-packaging.adoc
index a07cfe16..8dbf98c8 100644
--- a/docs/modules/install/pages/ruby-packaging.adoc
+++ b/docs/modules/install/pages/ruby-packaging.adoc
@@ -25,7 +25,7 @@ To install a pre-release version of Asciidoctor (e.g., a release candidate), ope
 . 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,ruby,subs=attributes+]
 ----
 source 'https://rubygems.org'
 gem 'asciidoctor'
diff --git a/docs/modules/install/pages/windows.adoc b/docs/modules/install/pages/windows.adoc
index 2248b0b1..99d29b1e 100644
--- a/docs/modules/install/pages/windows.adoc
+++ b/docs/modules/install/pages/windows.adoc
@@ -6,10 +6,7 @@ To install Asciidoctor on Windows, you can use Chocolatey or Rubyinstaller.
 
 When you already use https://chocolatey.org[chocolatey^] on your machine, you can use:
 
-[source]
-----
-choco install ruby
-----
+ C:\> choco install ruby
 
 Then follow the xref:ruby-packaging.adoc[gem installation instructions].
 
diff --git a/docs/modules/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc
index f9424cdf..1391f1c3 100644
--- a/docs/modules/migrate/pages/asciidoc-python.adoc
+++ b/docs/modules/migrate/pages/asciidoc-python.adoc
@@ -333,7 +333,7 @@ This content needs to be move to the specific subject docs pages if applicable
 Asciidoctor has shorthand for id, role, style and options.
 The following longhand syntax in AsciiDoc.py:
 
-[source]
+[source,asciidoc]
 ----
 [[id]]
 [style,role="role",options="option1,option2"]
@@ -341,7 +341,7 @@ The following longhand syntax in AsciiDoc.py:
 
 can be written using the shorthand supported by Asciidoctor:
 
-[source]
+[source,asciidoc]
 ----
 [style#id.role%option1%option2]
 ----
diff --git a/docs/modules/stem/pages/asciimath-gem.adoc b/docs/modules/stem/pages/asciimath-gem.adoc
index 5016bacd..08a940cb 100644
--- a/docs/modules/stem/pages/asciimath-gem.adoc
+++ b/docs/modules/stem/pages/asciimath-gem.adoc
@@ -41,7 +41,7 @@ First, activate STEM support in AsciiDoc by setting the `stem` document attribut
 This attribute must be set by the end of the document header.
 
 .Activate STEM support by setting the stem document attribute
-[source]
+[source,asciidoc]
 ----
 = Document Title
 :stem:
diff --git a/docs/modules/syntax-highlighting/pages/coderay.adoc b/docs/modules/syntax-highlighting/pages/coderay.adoc
index c7b035a9..1eba3525 100644
--- a/docs/modules/syntax-highlighting/pages/coderay.adoc
+++ b/docs/modules/syntax-highlighting/pages/coderay.adoc
@@ -60,7 +60,7 @@ Install using dnf (Fedora-based systems)::
 
 Once you've installed the RubyGem, assign the `coderay` value to the `source-highlighter` attribute in the document header to activate it.
 
-[source]
+[source,asciidoc]
 ----
 :source-highlighter: coderay
 ----
@@ -81,7 +81,7 @@ If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you wa
 Default: `table`.
 
 .Customizing a source block with CodeRay line numbers
-[source]
+[source,asciidoc]
 ....
 :source-highlighter: coderay
 :coderay-linenums-mode: inline
diff --git a/docs/modules/syntax-highlighting/pages/highlightjs.adoc b/docs/modules/syntax-highlighting/pages/highlightjs.adoc
index ab9c2fc3..c1f95543 100644
--- a/docs/modules/syntax-highlighting/pages/highlightjs.adoc
+++ b/docs/modules/syntax-highlighting/pages/highlightjs.adoc
@@ -9,7 +9,7 @@
 
 To activate highlight.js, add the following attribute entry to the header of your AsciiDoc file:
 
-[source]
+[source,asciidoc]
 ----
 :source-highlighter: highlight.js
 ----
@@ -25,7 +25,7 @@ Separate each language by a comma followed by an optional space.
 The common highlight.js bundle does not include support for Rust and Swift.
 Let's set the `highlightjs-languages` attribute so the HTML converter loads support for them into the HTML page.
 
-[source]
+[source,asciidoc]
 ----
 :source-highlighter: highlight.js
 :highlightjs-languages: rust, swift
diff --git a/docs/modules/syntax-highlighting/pages/index.adoc b/docs/modules/syntax-highlighting/pages/index.adoc
index 153e0907..ad858d1f 100644
--- a/docs/modules/syntax-highlighting/pages/index.adoc
+++ b/docs/modules/syntax-highlighting/pages/index.adoc
@@ -3,7 +3,7 @@
 AsciiDoc defines a style of listing block known as a source block for adding a source code listing to a document that's intended to be colorized by a syntax highlighter.
 Here's a simple example of a source block:
 
-[source]
+[source,asciidoc]
 ....
 [source,ruby]
 ----
diff --git a/docs/modules/syntax-highlighting/pages/pygments.adoc b/docs/modules/syntax-highlighting/pages/pygments.adoc
index a049b690..6efa59b6 100644
--- a/docs/modules/syntax-highlighting/pages/pygments.adoc
+++ b/docs/modules/syntax-highlighting/pages/pygments.adoc
@@ -32,7 +32,7 @@ $ gem install pygments.rb # <.>
 
 Once you've installed these libraries, assign `pygments` to the `source-highlighter` attribute in your document's header.
 
-[source]
+[source,asciidoc]
 ----
 :source-highlighter: pygments
 ----
@@ -59,7 +59,7 @@ If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you wa
 Default: `table`.
 
 .Customizing a source block with Pygments attributes
-[source]
+[source,asciidoc]
 ....
 :source-highlighter: pygments
 :pygments-style: manni
diff --git a/docs/modules/syntax-highlighting/pages/rouge.adoc b/docs/modules/syntax-highlighting/pages/rouge.adoc
index b6022864..2cb56468 100644
--- a/docs/modules/syntax-highlighting/pages/rouge.adoc
+++ b/docs/modules/syntax-highlighting/pages/rouge.adoc
@@ -26,7 +26,7 @@ Install using `dnf` (Fedora-based systems)::
 
 Once you've installed the RubyGem, assign the `rouge` value to the `source-highlighter` attribute in the document header to activate it.
 
-[source]
+[source,asciidoc]
 ----
 :source-highlighter: rouge
 ----
@@ -51,7 +51,7 @@ 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,asciidoc]
 ....
 :source-highlighter: rouge
 
-- 
cgit v1.2.3


From a90f36363994f51fd5bb142942608e9dd7b8dd25 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Mon, 30 Nov 2020 18:25:25 -0700
Subject: use Ruby 2 hash syntax in examples

---
 docs/modules/api/pages/convert-strings.adoc               | 2 +-
 docs/modules/api/pages/set-safe-mode.adoc                 | 6 +++---
 docs/modules/extensions/pages/block-macro-processor.adoc  | 2 +-
 docs/modules/extensions/pages/block-processor.adoc        | 2 +-
 docs/modules/extensions/pages/docinfo-processor.adoc      | 3 +--
 docs/modules/extensions/pages/include-processor.adoc      | 2 +-
 docs/modules/extensions/pages/inline-macro-processor.adoc | 2 +-
 docs/modules/extensions/pages/postprocessor.adoc          | 2 +-
 docs/modules/extensions/pages/preprocessor.adoc           | 2 +-
 docs/modules/extensions/pages/tree-processor.adoc         | 2 +-
 10 files changed, 12 insertions(+), 13 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/api/pages/convert-strings.adoc b/docs/modules/api/pages/convert-strings.adoc
index 6eec4faf..71577c74 100644
--- a/docs/modules/api/pages/convert-strings.adoc
+++ b/docs/modules/api/pages/convert-strings.adoc
@@ -73,7 +73,7 @@ If you only want the inline markup to be returned, set the `:doctype` option to
 
 [source,ruby]
 ----
-puts Asciidoctor.convert '*This* is Asciidoctor.', :doctype => 'inline'
+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.
diff --git a/docs/modules/api/pages/set-safe-mode.adoc b/docs/modules/api/pages/set-safe-mode.adoc
index 8ff65b5d..eca166a3 100644
--- a/docs/modules/api/pages/set-safe-mode.adoc
+++ b/docs/modules/api/pages/set-safe-mode.adoc
@@ -8,14 +8,14 @@ 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')
+ result = Asciidoctor.convert_file('master.adoc', safe: 'server')
 
 or
 
- result = Asciidoctor.convert_file('master.adoc', :safe => :server)
+ result = Asciidoctor.convert_file('master.adoc', safe: :server)
 
 or
 
- result = Asciidoctor.convert_file('master.adoc', :safe => 10)
+ 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:reference-safe-mode.adoc[enable or disable content based on the current safe mode].
diff --git a/docs/modules/extensions/pages/block-macro-processor.adoc b/docs/modules/extensions/pages/block-macro-processor.adoc
index 45ef1dc8..1d2ac22d 100644
--- a/docs/modules/extensions/pages/block-macro-processor.adoc
+++ b/docs/modules/extensions/pages/block-macro-processor.adoc
@@ -47,5 +47,5 @@ Asciidoctor::Extensions.register do
   block_macro GistBlockMacro if document.basebackend? 'html'
 end
 
-Asciidoctor.convert_file 'sample-with-gist.adoc', :safe => :safe
+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
index fb04cbca..7352af31 100644
--- a/docs/modules/extensions/pages/block-processor.adoc
+++ b/docs/modules/extensions/pages/block-processor.adoc
@@ -44,5 +44,5 @@ Asciidoctor::Extensions.register do
   block ShoutBlock
 end
 
-Asciidoctor.convert_file 'sample-with-shout-block.adoc', :safe => :safe
+Asciidoctor.convert_file 'sample-with-shout-block.adoc', safe: :safe
 ----
diff --git a/docs/modules/extensions/pages/docinfo-processor.adoc b/docs/modules/extensions/pages/docinfo-processor.adoc
index 084937e3..636b24a0 100644
--- a/docs/modules/extensions/pages/docinfo-processor.adoc
+++ b/docs/modules/extensions/pages/docinfo-processor.adoc
@@ -33,6 +33,5 @@ Asciidoctor::Extensions.register do
   docinfo_processor GoogleAnalyticsDocinfoProcessor
 end
 
-Asciidoctor.convert_file 'sample.adoc', :safe => :safe,
-    :attributes => 'UA-ABCXYZ123'
+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
index be27729a..ee1a220a 100644
--- a/docs/modules/extensions/pages/include-processor.adoc
+++ b/docs/modules/extensions/pages/include-processor.adoc
@@ -48,5 +48,5 @@ Asciidoctor::Extensions.register do
   include_processor UriIncludeProcessor
 end
 
-Asciidoctor.convert_file 'sample-with-uri-include.adoc', :safe => :safe
+Asciidoctor.convert_file 'sample-with-uri-include.adoc', safe: :safe
 ----
diff --git a/docs/modules/extensions/pages/inline-macro-processor.adoc b/docs/modules/extensions/pages/inline-macro-processor.adoc
index 69a8b89e..b16b4854 100644
--- a/docs/modules/extensions/pages/inline-macro-processor.adoc
+++ b/docs/modules/extensions/pages/inline-macro-processor.adoc
@@ -47,5 +47,5 @@ Asciidoctor::Extensions.register do
   inline_macro ManInlineMacro
 end
 
-Asciidoctor.convert_file 'sample-with-man-link.adoc', :safe => :safe
+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
index 61be2401..130ca547 100644
--- a/docs/modules/extensions/pages/postprocessor.adoc
+++ b/docs/modules/extensions/pages/postprocessor.adoc
@@ -31,5 +31,5 @@ Asciidoctor::Extensions.register do
   postprocessor CopyrightFooterPostprocessor
 end
 
-Asciidoctor.convert_file 'sample-with-copyright-footer.adoc', :safe => :safe
+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
index aa32516c..d1cc95f1 100644
--- a/docs/modules/extensions/pages/preprocessor.adoc
+++ b/docs/modules/extensions/pages/preprocessor.adoc
@@ -64,5 +64,5 @@ Asciidoctor::Extensions.register do
   preprocessor FrontMatterPreprocessor
 end
 
-Asciidoctor.convert_file 'sample-with-front-matter.adoc', :safe => :safe
+Asciidoctor.convert_file 'sample-with-front-matter.adoc', safe: :safe
 ----
diff --git a/docs/modules/extensions/pages/tree-processor.adoc b/docs/modules/extensions/pages/tree-processor.adoc
index 00a66436..ac97cbc7 100644
--- a/docs/modules/extensions/pages/tree-processor.adoc
+++ b/docs/modules/extensions/pages/tree-processor.adoc
@@ -65,7 +65,7 @@ Asciidoctor::Extensions.register do
   tree_processor ShellSessionTreeProcessor
 end
 
-Asciidoctor.convert_file 'sample-with-shell-session.adoc', :safe => :safe
+Asciidoctor.convert_file 'sample-with-shell-session.adoc', safe: :safe
 ----
 
 ////
-- 
cgit v1.2.3


From 062ddfe40c7b90205b74d1313969cd3287be99fe Mon Sep 17 00:00:00 2001
From: Sarah White <graphitefriction@gmail.com>
Date: Thu, 3 Dec 2020 17:30:34 -0700
Subject: content clarifications, syntax fixes, and added xrefs

---
 docs/modules/ROOT/nav-top.adoc                     |  3 ++
 docs/modules/ROOT/pages/converters.adoc            |  2 +-
 docs/modules/ROOT/pages/features.adoc              | 24 ++++++-------
 docs/modules/ROOT/pages/index.adoc                 | 20 ++++-------
 docs/modules/ROOT/pages/localization-support.adoc  | 39 +++++++++++-----------
 docs/modules/ROOT/pages/whats-new.adoc             |  4 +--
 docs/modules/api/pages/index.adoc                  |  2 +-
 docs/modules/docbook-backend/pages/index.adoc      |  4 +++
 docs/modules/get-started/pages/index.adoc          |  2 +-
 docs/modules/html-backend/pages/index.adoc         |  7 ++--
 docs/modules/install/pages/index.adoc              |  2 +-
 docs/modules/install/pages/linux-packaging.adoc    | 12 +++----
 .../modules/install/pages/supported-platforms.adoc |  2 +-
 docs/modules/install/partials/success.adoc         |  2 +-
 docs/modules/manpage-backend/pages/index.adoc      |  4 +++
 docs/modules/stem/pages/index.adoc                 |  2 +-
 docs/modules/syntax-highlighting/pages/index.adoc  |  8 ++---
 17 files changed, 72 insertions(+), 67 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/nav-top.adoc b/docs/modules/ROOT/nav-top.adoc
index 98431ff5..63ac8da8 100644
--- a/docs/modules/ROOT/nav-top.adoc
+++ b/docs/modules/ROOT/nav-top.adoc
@@ -1,2 +1,5 @@
+[]
 * xref:features.adoc[]
+
+[]
 * xref:whats-new.adoc[]
diff --git a/docs/modules/ROOT/pages/converters.adoc b/docs/modules/ROOT/pages/converters.adoc
index 9340f9f0..31c54489 100644
--- a/docs/modules/ROOT/pages/converters.adoc
+++ b/docs/modules/ROOT/pages/converters.adoc
@@ -18,7 +18,7 @@ Each converter is mapped to a name that you specify using the `-b` (`--backend`)
 
 These built-in converters are bundled with Asciidoctor.
 
-HTML::
+xref:html-backend:index.adoc[HTML]::
 The HTML 5 converter (`html` or `html5`) generates HTML 5 styled with CSS3.
 This is the converter Asciidoctor uses by default.
 
diff --git a/docs/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc
index 29d45840..e091af55 100644
--- a/docs/modules/ROOT/pages/features.adoc
+++ b/docs/modules/ROOT/pages/features.adoc
@@ -6,25 +6,25 @@ This page covers the features of Asciidoctor that make it a great choice for pro
 
 Asciidoctor is written in Ruby, which means it must be run on a Ruby language runtime (including JRuby).
 But that's its only requirement.
-Asciidoctor is packaged and distributed as a RubyGem (aka gem) to the main package repository at https://rubygems.org[RubyGems.org^].
-What that means is that the gem can be installed on *any operating system* Ruby supports using Ruby's package management tools (gem or bundle).
+Asciidoctor is packaged and distributed as a {url-rubygem}/asciidoctor[RubyGem to the package repository at RubyGems.org^].
+The gem can be installed on *any operating system* Ruby supports using Ruby's package management tools (gem or bundle).
 Asciidoctor itself has no dependencies.
 
 But what if you aren't familiar with Ruby or, for whatever reason, prefer not to install it?
 No problem!
 Thanks to {url-asciidoctorj}[AsciidoctorJ^] and xref:asciidoctor.js::index.adoc[Asciidoctor.js], you can run the same exact version of Asciidoctor on a Java Virtual Machine (JVM) or JavaScript runtime, respectively.
-That means you _don't_ need a Ruby runtime installed on your machine after all.
-(AsciidoctorJ uses JRuby internally, whereas Asciidoctor.js relies on a Ruby-like runtime written in JavaScript).
+That means you don't need a Ruby runtime installed on your machine after all.
+AsciidoctorJ uses JRuby internally, whereas Asciidoctor.js relies on a Ruby-like runtime written in JavaScript.
 
 Whether your working in Ruby, Java, or JavaScript, Asciidoctor is readily available for you to start using.
-(Only when you get into extended converters and extensions do you need to install dependencies).
+Only when you get into extended converters and extensions do you need to install dependencies.
 
 == Quick wins
 
-Asciidoctor provides a really nice out-of-the-box xref:html-backend:index.adoc[HTML experience], complete with a default stylesheet and built-in integrations like Font Awesome (for icons), Highlight.js (for source highlighting), and MathJax (for STEM processing).
+Asciidoctor provides a nice out-of-the-box xref:html-backend:index.adoc[HTML experience], complete with a default stylesheet and built-in integrations like Font Awesome (for icons), Highlight.js (for source highlighting), and MathJax (for STEM processing).
 When you're just getting into using AsciiDoc for writing, Asciidoctor's HTML output should be sufficient for all of your publishing needs.
 
-The following before and after picture should give you an idea of what to expect:
+The following before and after picture gives you an idea of what to expect:
 
 image::source-vs-output.png[AsciiDoc source vs HTML output]
 
@@ -37,8 +37,8 @@ So there is plenty of room to grow.
 Asciidoctor provides converters for three output formats by default: xref:html-backend:index.adoc[HTML 5], xref:docbook-backend:index.adoc[DocBook 5], and xref:manpage-backend:index.adoc[manpage] (manual page).
 These converters are designed to cover a majority of users`' needs for basic preview and publishing.
 
-The *HTML* converter gives you a result you can publish the web straight away without any tweaking.
-The *DocBook* converter allows you to either leverage an existing publishing toolchain or migrate the content to a different authoring format (without the tool needing to know how to parse AsciiDoc).
+The *HTML* converter provides a result you can publish the web straight away without any tweaking.
+The *DocBook* converter allows you to leverage an existing publishing toolchain or migrate the content to a different authoring format (without the tool needing to know how to parse AsciiDoc).
 The *manpage* converter drastically lowers the barrier to making system help files.
 
 But it doesn't end there.
@@ -127,15 +127,15 @@ In addition to its performance, these security levels make Asciidoctor well-suit
 == Access to an ecosystem of extensions and tools
 
 Installating Asciidoctor is just the beginning of your publishing experience.
-Asciidoctor gives you access to a {url-org}[healthy ecosystem of extensions and tools], ranging from converters, to extended syntax, to build plugins, to integrated writing and preview environments.
+Asciidoctor gives you access to a {url-org}[healthy ecosystem of extensions and tools^], ranging from converters, to extended syntax, to build plugins, to integrated writing and preview environments.
 
-One popular extension is {url-org}/asciidoctor-diagram[Asciidoctor Diagram].
+One popular extension is {url-org}/asciidoctor-diagram[Asciidoctor Diagram^].
 When loaded, Asciidoctor Diagram allows you to make diagrams from plain text (much like AsciiDoc does for writing).
 Asciidoctor Diagram does this by extending the syntax of AsciiDoc to recognize specially marked literal blocks.
 It takes the text inside those blocks, passes it through one of the diagramming tools it integrates with, and reinserts the image back into the document as it is being processed.
 The result is that the diagram source in the AsciiDoc document becomes an image in the generated output.
 
-One popular tool is the {url-org}/asciidoctor-browser-extension[browser extension].
+Another popular tool is the {url-org}/asciidoctor-browser-extension[browser extension^].
 When this extension is installed, you can browse to an AsciiDoc file on your harddisk or on the web and the browser will show you the converted HTML *instead of* the AsciiDoc source.
 That means you can get the out-of-the-box HTML experience that Asciidoctor provides without even having to run a command or script.
 The extension running in the browser does everything for you.
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index bccb23e5..0644b608 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -1,38 +1,32 @@
 = 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.
+This is the documentation for the Ruby-based AsciiDoc processor, Asciidoctor.
 Asciidoctor currently serves as the reference implementation for how to interpret the AsciiDoc language.
-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.
+If you're looking for the documentation for the AsciiDoc language, see the xref:asciidoc::index.adoc[AsciiDoc section] of this website.
 
 == What is Asciidoctor?
 
-Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc into a document model and converting to output formats such as [.nowrap]#HTML 5#, [.nowrap]#DocBook 5#, manpage, PDF, and [.nowrap]#EPUB 3#.
+Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc into a document model and converting to output formats such as [.nowrap]#HTML 5#, [.nowrap]#DocBook 5#, manual pages, PDF, and [.nowrap]#EPUB 3#.
 This Ruby library is often referred to as Asciidoctor core.
 That's because Asciidoctor is also the name of the family of projects that contribute extensions and tools for Asciidoctor.
 When we say Asciidoctor in this section of the documentation, we're specifically referring to Asciidoctor core.
 
-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^].
+To simplify installation, Asciidoctor is packaged and distributed to RubyGems.org as a {url-rubygem}/asciidoctor[RubyGem named asciidoctor^].
 The asciidoctor gem can be installed on all major operating systems using Ruby packaging tools (gem or bundle).
 Asciidoctor is also distributed as a package for numerous Linux distributions as well as macOS.
 
 Asciidoctor is open source software that is available under the terms of the MIT license and {url-org}[hosted on GitHub^].
 
 Asciidoctor is the successor to AsciiDoc Python (AsciiDoc.py).
-If you're still using AsciiDoc.py, follow xref:migrate:asciidoc-python.adoc[] to learn how to upgrade to Asciidoctor.
+If you're using AsciiDoc.py, follow xref:migrate:asciidoc-python.adoc[] to learn how to upgrade to Asciidoctor.
 
 == Basic usage
 
 Asciidoctor provides two primary interfaces for processing AsciiDoc documents:
 
-[cols=2*]
 |===
-| CLI | API
+|CLI |API
 
 a|
  $ asciidoctor document.adoc
@@ -81,7 +75,7 @@ You can find the documentation for these projects elsewhere on this site or in t
 
 == Beyond Ruby
 
-Although Asciidoctor is written in Ruby, it does not mean you are stuck using Ruby.
+Although Asciidoctor is written in Ruby, it does not mean you have to use Ruby.
 You can also run Asciidoctor using a JVM or JavaScript.
 
 === Java / JVM
diff --git a/docs/modules/ROOT/pages/localization-support.adoc b/docs/modules/ROOT/pages/localization-support.adoc
index 2d39c52a..054dd96a 100644
--- a/docs/modules/ROOT/pages/localization-support.adoc
+++ b/docs/modules/ROOT/pages/localization-support.adoc
@@ -1,9 +1,8 @@
 = Localization 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
 
-However, Asciidoctor is not restricted to working with English-only content.
+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.
 
@@ -41,77 +40,77 @@ If you're not using the DocBook toolchain for publishing, you must translate eac
 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,cols="m,,"]
+[cols="~,~,30%"]
 |===
 |Attribute |Default English Value |Notes
 
-|appendix-caption
+|`appendix-caption`
 |Appendix
 |
 
-|caution-caption
+|`caution-caption`
 |Caution
 |
 
-|chapter-label
+|`chapter-label`
 |Chapter
 |Applies only when `doctype` is `book`.
 PDF converter only.
 
-|example-caption
+|`example-caption`
 |Example
 |
 
-|figure-caption
+|`figure-caption`
 |Figure
 |
 
-|important-caption
+|`important-caption`
 |Important
 |
 
-|last-update-label
+|`last-update-label`
 |Last updated
 |
 
-|listing-caption
+|`listing-caption`
 |_not set_
 |By default, listing blocks do not have captions.
 Specify `listing-caption` to turn on listing block captions.
 
-|manname-title
+|`manname-title`
 |NAME
 |Applies only when `doctype` is `manpage`.
 
-|note-caption
+|`note-caption`
 |Note
 |
 
-|preface-title
+|`preface-title`
 |_not set_
 |Applies only when `doctype` is `book`.
 
-|table-caption
+|`table-caption`
 |Table
 |
 
-|tip-caption
+|`tip-caption`
 |Tip
 |
 
-|toc-title
+|`toc-title`
 |Table of Contents
 |
 
-|untitled-label
+|`untitled-label`
 |Untitled
 |
 
-|version-label
+|`version-label`
 |Version
 |
 
-|warning-caption
+|`warning-caption`
 |Warning
 |
 |===
diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc
index 8055e9bf..7c7b2305 100644
--- a/docs/modules/ROOT/pages/whats-new.adoc
+++ b/docs/modules/ROOT/pages/whats-new.adoc
@@ -1,11 +1,11 @@
 //= What's New (Asciidoctor {page-component-version})
-= What's New ({page-component-version})
+= What's New in {page-component-version}
 :doctype: book
 :page-toclevels: 0
 :url-releases-asciidoctor: {url-org}/asciidoctor/releases
 :url-milestone: {url-org}/asciidoctor/milestone/33?closed=1:
 
-This page covers the changes introduced in each of the patch releases in the Asciidoctor {page-component-version} release line ({page-component-version}.0, {page-component-version}.1, ...).
+This page lists the changes made in each of the patch releases in the Asciidoctor {page-component-version} release line.
 The releases are ordered from newest to oldest.
 
 _**Cumulative issues resolved:** {url-milestone}[2.0.x^]_
diff --git a/docs/modules/api/pages/index.adoc b/docs/modules/api/pages/index.adoc
index 5c909faa..6a53b4b1 100644
--- a/docs/modules/api/pages/index.adoc
+++ b/docs/modules/api/pages/index.adoc
@@ -20,7 +20,7 @@ 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.
+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.
 
diff --git a/docs/modules/docbook-backend/pages/index.adoc b/docs/modules/docbook-backend/pages/index.adoc
index c6ef9962..b6e5c184 100644
--- a/docs/modules/docbook-backend/pages/index.adoc
+++ b/docs/modules/docbook-backend/pages/index.adoc
@@ -8,6 +8,10 @@
 Asciidoctor can produce DocBook 5.0 XML output.
 There's a corresponding DocBook element for each AsciiDoc element.
 
+`docbook`::
+The DocBook 5.0 converter generates DocBook 5.0 XML.
+To use the DocBook converter, assign `docbook` or `docbook5` to the `backend` option.
+
 == 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`.
diff --git a/docs/modules/get-started/pages/index.adoc b/docs/modules/get-started/pages/index.adoc
index 89b0bee1..9daf9562 100644
--- a/docs/modules/get-started/pages/index.adoc
+++ b/docs/modules/get-started/pages/index.adoc
@@ -47,4 +47,4 @@ The converted document should look like the example below.
 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.
+TIP: Most of the examples in the general documentation use the CLI, but there are usually corresponding API examples under xref:api:index.adoc[].
diff --git a/docs/modules/html-backend/pages/index.adoc b/docs/modules/html-backend/pages/index.adoc
index be3c9ec3..2e556ed4 100644
--- a/docs/modules/html-backend/pages/index.adoc
+++ b/docs/modules/html-backend/pages/index.adoc
@@ -5,7 +5,7 @@
 
 Asciidoctor's default output format is HTML.
 
-`html5`:: HTML 5 markup styled with CSS3.
+`html`:: The HTML 5 converter (`html` or `html5`) generates HTML 5 styled with CSS3.
 
 == Generate HTML using the html5 converter
 
@@ -53,9 +53,10 @@ As a result, you could save [.path]_my-sample.html_ to any computer and it will
 [#xhtml]
 == Generate XHTML
 
-To convert AsciiDoc to XHTML, set the backend to `xhtml5`.
+`xhtml`:: The XHTML variant of the HTML 5 converter.
+To use the XHTML converter, assign `xhtml` or `xhtml5` to the `backend` option.
 
-.Produce XHTML using the built-in HTML converter
+.Produce XHTML using the xhtml5 backend option
 [source,console]
 ----
 asciidoctor -b xhtml5 document.adoc
diff --git a/docs/modules/install/pages/index.adoc b/docs/modules/install/pages/index.adoc
index 67ecc0b0..1cfcaa2c 100644
--- a/docs/modules/install/pages/index.adoc
+++ b/docs/modules/install/pages/index.adoc
@@ -1,6 +1,6 @@
 = Install and Update
 
-To simplify installation, Asciidoctor is packaged and distributed as a RubyGem (aka gem) to {url-rubygem}/asciidoctor[RubyGems.org^].
+To simplify installation, Asciidoctor is packaged and distributed as a {url-rubygem}/asciidoctor[RubyGem to the package repository at 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].
 
diff --git a/docs/modules/install/pages/linux-packaging.adoc b/docs/modules/install/pages/linux-packaging.adoc
index 940fecf3..1033a622 100644
--- a/docs/modules/install/pages/linux-packaging.adoc
+++ b/docs/modules/install/pages/linux-packaging.adoc
@@ -13,12 +13,12 @@ The benefit of using your operating system's package manager to install the gem
 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)]
+* {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:ruby-packaging.adoc[].
 
diff --git a/docs/modules/install/pages/supported-platforms.adoc b/docs/modules/install/pages/supported-platforms.adoc
index 789a01d4..3d14e255 100644
--- a/docs/modules/install/pages/supported-platforms.adoc
+++ b/docs/modules/install/pages/supported-platforms.adoc
@@ -42,4 +42,4 @@ Catalina
 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.
+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/partials/success.adoc b/docs/modules/install/partials/success.adoc
index 8ad68700..df70c570 100644
--- a/docs/modules/install/partials/success.adoc
+++ b/docs/modules/install/partials/success.adoc
@@ -1,4 +1,4 @@
-If the gem installed successfully, its xref:cli:index.adoc[command line interface (CLI)] will be available on your PATH.
+If the gem installed successfully, Asciidoctor's xref:cli:index.adoc[command line interface (CLI)] will be available on your PATH.
 To confirm that Asciidoctor is available, execute:
 
  $ asciidoctor --version
diff --git a/docs/modules/manpage-backend/pages/index.adoc b/docs/modules/manpage-backend/pages/index.adoc
index 346fa25a..72c239d1 100644
--- a/docs/modules/manpage-backend/pages/index.adoc
+++ b/docs/modules/manpage-backend/pages/index.adoc
@@ -8,6 +8,10 @@
 
 Asciidoctor's built-in man page converter generates {url-man7}[roff-formatted^] manual pages from AsciiDoc documents.
 
+`manpage`::
+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.
+
 == 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.
diff --git a/docs/modules/stem/pages/index.adoc b/docs/modules/stem/pages/index.adoc
index 756f7fff..4750d463 100644
--- a/docs/modules/stem/pages/index.adoc
+++ b/docs/modules/stem/pages/index.adoc
@@ -12,7 +12,7 @@ On this page, we look at how STEM expressions are handled when converting AsciiD
 When a converter comes across a STEM node in an AsciiDoc document, it passes the source of the expression to a STEM processing library, such as MathJax.
 That library either displays the rendered expression itself (e.g., MathJax), turns it into an image the converter can link to or embed in the output file (e.g., Asciidoctor Mathematical), or translates it into another format that something further down the pipeline can process (e.g., AsciiMath).
 
-The STEM integrations are activated when the `stem` document attribute is set on the document and, if required, the relevant library is installed.
+The STEM integrations are activated when the xref:asciidoc:stem:stem.adoc[stem document attribute] is set on the document and, if required, the relevant library is installed.
 
 == STEM integrations
 
diff --git a/docs/modules/syntax-highlighting/pages/index.adoc b/docs/modules/syntax-highlighting/pages/index.adoc
index ad858d1f..3bdc0e05 100644
--- a/docs/modules/syntax-highlighting/pages/index.adoc
+++ b/docs/modules/syntax-highlighting/pages/index.adoc
@@ -1,6 +1,6 @@
 = Syntax Highlighting
 
-AsciiDoc defines a style of listing block known as a source block for adding a source code listing to a document that's intended to be colorized by a syntax highlighter.
+AsciiDoc defines a style of listing block known as a xref:asciidoc:verbatim:source-blocks.adoc[source block] for adding a source code snippets to a document that are intended to be colorized by a syntax highlighter.
 Here's a simple example of a source block:
 
 [source,asciidoc]
@@ -18,7 +18,7 @@ Here's how we expect it to appear:
 puts "Hello, World!"
 ----
 
-It's up to an AsciiDoc processor such as Asciidoctor to apply the syntax highlighting to this source block, a process referred to as *source highlighting*.
+It's up to an AsciiDoc processor such as Asciidoctor to apply the syntax highlighting to this source block, a process referred to as xref:asciidoc:verbatim:source-highlighter.adoc[source highlighting].
 Asciidoctor provides adapters that integrate with several popular syntax highlighter libraries to perform this task.
 It also provides an interface for implementing a custom syntax highlighter adapter.
 
@@ -27,14 +27,14 @@ It also provides an interface for implementing a custom syntax highlighter adapt
 Asciidoctor supports two types of syntax highlighters: client-side and build-time.
 Let's explore each type and how they work.
 
-A *client-side* syntax highlighter performs syntax highlighting in the browser as the page is loading.
+A [.term]*client-side syntax highlighter* performs syntax highlighting in the browser as the page is loading.
 Asciidoctor does not invoke the syntax highlighter itself.
 Instead, it focuses on adding the assets to the generated HTML so the browser can load the syntax highlighter and run it.
 For this type of syntax highlighter, Asciidoctor passes the contents of the source block through to the output as is.
 It also adds metadata to the element so that the syntax highlighter knows to highlight it and which language it is.
 Unfortunately, Asciidoctor does not process callout numbers in the source block in this case, so they may cause the syntax highlighter to get tripped up.
 
-A *build-time* syntax highlighter performs syntax highlighting during AsciiDoc conversion.
+A [.term]*build-time syntax highlighter* performs syntax highlighting during AsciiDoc conversion.
 Asciidoctor does invoke the syntax highlighter in this case.
 It also takes care of hiding the callout numbers from the syntax highlighter, ensuring they are put back in the proper place afterwards.
 What Asciidoctor emits into the output is the result produced by the syntax highlighter, which are the tokens wrapped in `<span>` tags to apply color and other formatting (either inline or via CSS classes).
-- 
cgit v1.2.3


From 5bf750df9cb49e5553557b14f71591e6d2867167 Mon Sep 17 00:00:00 2001
From: Sarah White <graphitefriction@gmail.com>
Date: Thu, 3 Dec 2020 17:51:45 -0700
Subject: create safe mode section titles and anchors

---
 docs/modules/ROOT/pages/reference-safe-mode.adoc |  6 +--
 docs/modules/ROOT/pages/safe-modes.adoc          | 50 ++++++++++++------------
 2 files changed, 29 insertions(+), 27 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/pages/reference-safe-mode.adoc b/docs/modules/ROOT/pages/reference-safe-mode.adoc
index 8c5b47b2..fe9eda35 100644
--- a/docs/modules/ROOT/pages/reference-safe-mode.adoc
+++ b/docs/modules/ROOT/pages/reference-safe-mode.adoc
@@ -1,12 +1,12 @@
 = Safe Mode Specific Content
 // anchor: set-safe-attrs
 
-Asciidoctor provides access to the xref:safe-modes.adoc[current safe mode] through built-in attributes.
+Asciidoctor provides access to the 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.
 
 == Referencing safe modes
 
-The safe mode can be referenced by one of the following attributes:
+The xref:safe-modes.adoc[safe mode] can be referenced by one of the following document 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.)
@@ -21,7 +21,7 @@ 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.
+This feature is particularly handy for displaying content on GitHub, where the safe mode is set to its most restrictive setting, xref:safe-modes.adoc#secure[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].
 
diff --git a/docs/modules/ROOT/pages/safe-modes.adoc b/docs/modules/ROOT/pages/safe-modes.adoc
index c8ac7d8f..5a442236 100644
--- a/docs/modules/ROOT/pages/safe-modes.adoc
+++ b/docs/modules/ROOT/pages/safe-modes.adoc
@@ -3,42 +3,48 @@
 Asciidoctor provides security levels that control the read and write access of attributes, include directives, macros, and scripts while a document is processing.
 Each level includes the restrictions enabled in the prior security level.
 
-== Safe mode levels
+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:reference-safe-mode.adoc[enable or disable content based on the current safe mode].
 
-`UNSAFE`::
-A safe mode level that disables any security features enforced by Asciidoctor.
+[#unsafe]
+== UNSAFE
+
+The `UNSAFE` safe mode level 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.
+[#safe]
+== SAFE
+
+The `SAFE` safe mode level prevents access to files which reside outside of the parent directory of the source file.
+Include directives (`+include::[]+`) are 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.
+[#server]
+== SERVER
+
+The `SERVER` safe mode level 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.
+[#secure]
+== SECURE
+
+The `SECURE` safe mode level 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
+* disables include directives (`+include::[]+`)
 * data can not be retrieved from URIs
 * prevents access to stylesheets and JavaScripts
 * sets the backend to `html5`
@@ -52,7 +58,8 @@ xref:extensions:index.adoc[Asciidoctor extensions] may still embed content into
 
 *This is the default safe mode for the API.*
 Its integer value is `20`.
---
+
+TIP: GitHub processes AsciiDoc files using the `SECURE` mode.
 
 ////
 |===
@@ -75,9 +82,4 @@ Its integer value is `20`.
 |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:reference-safe-mode.adoc[enable or disable content based on the current safe mode].
-- 
cgit v1.2.3


From 6dc7d871ab6c396071cb51ed3e3e8b1d349c6a47 Mon Sep 17 00:00:00 2001
From: Sarah White <graphitefriction@gmail.com>
Date: Fri, 4 Dec 2020 12:51:34 -0700
Subject: clean up API options table and add xrefs

---
 docs/modules/api/pages/options.adoc | 183 ++++++++++++++++--------------------
 1 file changed, 79 insertions(+), 104 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/api/pages/options.adoc b/docs/modules/api/pages/options.adoc
index fe4fc0ac..c0f30552 100644
--- a/docs/modules/api/pages/options.adoc
+++ b/docs/modules/api/pages/options.adoc
@@ -1,14 +1,14 @@
 = API Options
 
-[cols="15m,15,15,15,15"]
+[cols="~,~,30%,~"]
 |===
-|Name |Description |Default value |Allowed values |CLI equivalent
+|Name |Description |Default value |Allowed values
 
-|: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.
+|`:attributes`
+|Sets document attributes, which override equivalently-named attributes defined in the document unless soft set (`@`).
+When using the hash format, 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:
+|xref:asciidoc:attributes:document-attributes.adoc[Document attributes] in the following formats:
 
 Hash: +
 `{'name'\=>'value'}` +
@@ -16,153 +16,128 @@ 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`
+|`:backend`
+|Selects the converter to use.
+|`html5`
+|`html5`, `docbook5`, `manpage`, or a backend registered through an active converter
 
-|:base_dir
+|`: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.
+|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.
+|`:catalog_assets`
+|If `true`, the parser captures 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_
+|`false`
+|_Boolean_
 
-|:converter
-|Specifies a user-supplied `Asciidoctor::Converter` instance, used in place of the converter that is automatically resolved from the backend value.
+|`: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
+|`:doctype`
 |Sets the document type.
-|article
-|article, book, manpage, inline
-|`-d`, `--doctype`
+|`article`
+|`article`, `book`, `manpage`, `inline`
 
-|:eruby
+|`:eruby`
 |Specifies the eRuby implementation to use for executing the converter templates written in ERB.
-|erb
-|erb, erubis
-|`-e`, `--eruby`
+|`erb`
+|`erb`, `erubis`
 
-|:extensions
+|`: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
+|`: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_
 
-|:standalone
-|If true, generate a standalone output document (which includes the shell around the body content, such as the header and footer).
+|`:standalone`
+|If `true`, generates a standalone output document (which includes the shell around the body content, such as the header and footer).
 When converting to a file, the default value is `true`.
 Otherwise, the default value is `false`.
 The deprecated alias for this option is `:header_footer`.
-Note that the default value for this option is opposite of the default value for the CLI.
-|_contingent_
-|_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
+The default value for this option is opposite of the default value for the CLI.
+|_Varies_
+|_Boolean_
+
+|`:mkdirs`
+|If `true`, the processor creates the necessary output directories if they don't yet exist.
+|`false`
+|_Boolean_
+
+|`: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_
+
+|`: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.*
+|`:secure`
+|`:unsafe`, `:safe`, `:server`, `:secure`
+
+|`:sourcemap`
+|Tracks 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_
+
+|`:template_cache`
+|Enables the built-in cache used by the template converter when reading the source of template files.
+Only relevant if `:template_dirs` is specified.
+|`true`
+|_Boolean_
+
+//|`:template_dir`
+//|Specifies a directory of Tilt-compatible templates to be used instead of the default built-in templates.
+//*Deprecated. Use `:template_dirs` instead.*
+//|_not set_
+//|file path
+
+|`:template_dirs`
+|Array of directories containing Tilt-compatible converter templates to be used instead of the default built-in templates.
 |_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`
+|Array of file paths
 
-|:template_engine
+|`: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 name (e.g., `slim`, `haml`, `erb`, etc.)
 
-|:template_engine_options
+|`: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_
+|Nested Hash of options with the template engine name as the top-level key and the option name as the second-level key.
 
-|:timings
+|`: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`).
+|`:to_file`
+|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`
+|`true`, file path
 
-|:to_dir
+|`: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`
+|Directory containing source file, or working directory if source is read from a stream.
+|File path
 |===
-- 
cgit v1.2.3


From 1a786220564d3d31ff5d82dc2ea47ed84213c8f4 Mon Sep 17 00:00:00 2001
From: Sarah White <graphitefriction@gmail.com>
Date: Fri, 4 Dec 2020 14:48:07 -0700
Subject: clean up syntax migration tables and add xrefs

---
 docs/modules/migrate/pages/asciidoc-python.adoc | 198 +++++++++++++-----------
 docs/modules/migrate/pages/upgrade.adoc         |  71 ++++-----
 2 files changed, 139 insertions(+), 130 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc
index 1391f1c3..7f36cd8c 100644
--- a/docs/modules/migrate/pages/asciidoc-python.adoc
+++ b/docs/modules/migrate/pages/asciidoc-python.adoc
@@ -58,122 +58,131 @@ There are similar attributes to control how additional resources are resolved.
 
 === Inline formatting
 
-[cols="15,20,30,15"]
+[cols="~,~,~,~"]
 |===
 |Feature |AsciiDoc.py |Asciidoctor |Notes
 
 |_italic text_
 |pass:['italic text']
 |pass:[_italic text_]
-|Allowed with `compat-mode`
+|Allowed with `compat-mode`.
+See xref:asciidoc:text:italic.adoc[].
 
 |`monospace text`
 |pass:[+monospace text+]
 |pass:[`monospace text`]
-|Allowed with `compat-mode`
+|Allowed with `compat-mode`.
+See xref:asciidoc:text:monospace.adoc[].
 
 |`+literal monospace text+`
 |pass:[`literal monospace text`]
 |pass:[`+literal monospace text+`]
-|Allowed with `compat-mode`
+|Allowed with `compat-mode`.
+See xref:asciidoc:text:monospace.adoc#literal-monospace[Literal monospace].
 
 |Curved "`double quotes`"
 |pass:[``double quotes'']
-|pass:["`double quotes`"], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8220;)
-|
+|pass:["`double quotes`"], editor keybinding, or Unicode character in numeric character reference form
+|See xref:asciidoc:text:quotation-marks-and-apostrophes.adoc[].
 
 |Curved '`single quotes`'
 |pass:[`single quotes']
-|pass:['`single quotes`'], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8217;)
-|
+|pass:['`single quotes`'], editor keybinding, or Unicode character in numeric character reference form
+|See xref:asciidoc:text:quotation-marks-and-apostrophes.adoc[].
+
+|Sizes and overline
+|`big`, `small`, `overline`
+|user-specified `+[.<role-name>]+` and associated formatting in stylesheet
+|See xref:asciidoc:text:custom-inline-styles.adoc[].
 
-|Sizes, lines, and colors
-|`big`, `small`, `underline`, `overline`, `line-through`, colors
+|Underline and line-through
+|`underline`, `line-through`
+|`+[.underline]+`, `+[.line-through]+`
+|See xref:asciidoc:text:custom-inline-styles.adoc[].
+
+|Colors
+|Name of color
 |user-specified `+[.<role-name>]+` and associated formatting in stylesheet
-|See xref:asciidoc:text:custom-inline-styles.adoc[custom text styles]
+|See xref:asciidoc:text:custom-inline-styles.adoc[].
 |===
 
 === Table of contents
 
-[cols="15,20,30,15"]
+[cols="~,~,~,~"]
 |===
 |Feature |AsciiDoc.py |Asciidoctor |Notes
 
-|Scrollable, left margin ToC
+|Scrollable, left margin TOC
 |`toc2`
 |`+:toc: left+`
-|
+|See xref:asciidoc:toc:position.adoc[].
 
-|ToC location
+|TOC location
 |`toc-placement` and `toc-position`
 |`+:toc: <value>+`
-|
+|See xref:asciidoc:toc:position.adoc[].
 
-|User-specified ToC location
+|User-specified TOC location
 |`+:toc-placement: manual+`
 |`+:toc: macro+`
-|
+|See xref:asciidoc:toc:position.adoc[].
 |===
 
-=== Document header
+=== Document and section titles
 
-[cols="15,20,15,35"]
+[cols="~,~,30%,~"]
 |===
 |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]
+|`= Title`
+|Allowed with `compat-mode`.
+See xref:asciidoc:document:title.adoc[].
+
+|Two-line style (setext) document title
+|`Title` +
+`+=====+`
+|`= 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.
-|===
+But, by using it, `compat-mode` is implicitly set.
+To use the new syntax, use `= Title` or explicitly unset `compat-mode`.
+See xref:asciidoc:document:title.adoc[].
 
-.Sections
-[cols="15,20,30,15"]
-|===
-|Feature |AsciiDoc.py |Asciidoctor |Notes
-
-|Underlined titles
+|Underlined section 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]
+|`== Level 1 title` +
+`=== Level 2 title` +
+`==== Level 3 title` +
+`===== Level 4 title`
+|See xref:asciidoc:sections:titles-and-levels.adoc[].
 
 |Section numbers
 |`numbered`
 |`sectnums`
-|
+|See xref:asciidoc:sections:numbers.adoc[].
 |===
 
 === Tables
 
-[cols="15,20,20,20"]
+[cols="~,~,~,~"]
 |===
 |Feature |AsciiDoc.py |Asciidoctor |Notes
 
-|AsciiDoc table cell
+|Table cell
 |`a{vbar}` or `asciidoc{vbar}`
 |`a{vbar}` only
-|
+|See xref:asciidoc:tables:add-cells-and-rows.adoc[].
 
 |Table cell separator
 |A Python regular expression.
-|One or more literal characters or \t for tab.
-|
+|One or more literal characters or `\t` for tab.
+|See xref:asciidoc:tables:add-cells-and-rows.adoc[], xref:asciidoc:tables:data-format.adoc[], and xref:asciidoc:tables:data-format.adoc#custom-delimiters[custom separators].
 
 |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].
+|See xref:asciidoc:tables:align-by-column.adoc[] and xref:asciidoc:tables:align-by-cell.adoc[].
 
 |Make tables full page width in DocBook
 |`options="pgwide"`
@@ -183,25 +192,48 @@ pass:[===== Level 4 section title] +
 
 === Blocks
 
-[cols="15,20,30,15"]
+[cols="~,~,~,~"]
 |===
 |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.
-|
+|See xref:asciidoc:blocks:build-basic-block.adoc#delimited-blocks[Delimited blocks].
+|===
+
+=== Substitutions
+
+[cols="~,~,~,~"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Substitute `+`
+|`replacements2`
+|`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_
+|Close equivalent is a xref:asciidoc:pass:pass-block.adoc[passthrough block] or a listing block with xref:asciidoc:directives:include-with-indent.adoc#the-indent-attribute[the indent attribute].
 |===
 
-.General
-[cols="15,20,30,15"]
+=== Mathematical expressions
+
+AsciiDoc.py and Asciidoctor can convert embedded LaTeX and AsciiMath expressions (e.g., `pass:[asciimath:[expression]]`, `pass:[latexmath:[expression]]`, etc.).
+In Asciidoctor, activate STEM support first using the xref:asciidoc:stem:stem.adoc[stem attribute].
+
+=== Miscellaneous
+
+[cols="~,~,~,30%"]
 |===
 |Feature |AsciiDoc.py |Asciidoctor |Notes
 
-|+ifeval::[ ]+
+|`+ifeval::[ ]+`
 |Evaluates any Python expression.
 |Evaluates simple logical expressions testing the value of attributes.
-|See xref:asciidoc:directives:ifeval.adoc[ifeval directive]
+|See xref:asciidoc:directives:ifeval.adoc[].
 
 |Provide name of current document
 |`infile`
@@ -213,30 +245,7 @@ pass:[===== Level 4 section title] +
 |_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.
+|Apply special formatting to named text
 |`specialwords`
 |_not implemented_
 |
@@ -244,38 +253,47 @@ a|If you want to send remarks to the output, use an extension, or:
 |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.
+|Asciidoctor only replaces tabs with spaces in verbatim blocks, 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.
+See xref:asciidoc:directives:include-with-indent.adoc[normalize block indentation].
 |===
 
-== Mathematical expressions
+=== showcomments
 
-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].
+In AsciiDoc.py, single line comments could be turned into DocBook `<remark>` elements using `showcomments`.
+This feature isn't implemented in Asciidoctor, but you can send remarks to the output, using an extension, or ifdef directives and passthrough blocks like the example shown below.
+
+[source,asciidoc]
+----
+ ifdef::showcomments+basebackend-docbook[]
+ ++++
+ <remark>Your comment here</remark>
+ ++++
+ endif::[]
+----
 
 == 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
+=== Localization
 
 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:localization-support.adoc[language support] for details.
+See xref:ROOT:localization-support.adoc[] 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.
+The extension mechanism is completely different in Asciidoctor, but most of the standard extensions have been re-implemented, so they should work with minor changes.
 
-[cols="<20,<80"]
+[cols="~,~"]
 |===
 |AsciiDoc.py |Asciidoctor
 
-|source
+|`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.
@@ -287,7 +305,7 @@ a|
 |`[latex]` block macro
 |Use a xref:asciidoc:stem:stem.adoc#stem-bl[stem block].
 
-|graphviz
+|`graphviz`
 |Use {url-diagram}[Asciidoctor Diagram^].
 |===
 
@@ -302,7 +320,7 @@ 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
+== 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`.
diff --git a/docs/modules/migrate/pages/upgrade.adoc b/docs/modules/migrate/pages/upgrade.adoc
index 9ad2d9fa..7fae3f9b 100644
--- a/docs/modules/migrate/pages/upgrade.adoc
+++ b/docs/modules/migrate/pages/upgrade.adoc
@@ -1,5 +1,4 @@
 = 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[].
@@ -14,94 +13,86 @@ In most cases, they've been replaced with a new feature that provides improved f
 
 === Inline formatting
 
-[cols="15,20,20,5,20"]
+[cols="~,~,~,~"]
 |===
-|Feature |Deprecated |New |As of Version |Notes
+|Feature |Deprecated |New |Notes
 
 |_italic text_
 |pass:['italic text']
 |pass:[_italic text_]
-|1.5.0
-|Allowed with `compat-mode`
+|Allowed with `compat-mode`.
+See xref:asciidoc:text:italic.adoc[].
 
 |`monospace text`
 |pass:[+monospace text+]
 |pass:[`monospace text`]
-|1.5.0
-|Allowed with `compat-mode`
+|Allowed with `compat-mode`.
+See xref:asciidoc:text:monospace.adoc[].
 
 |`+literal monospace text+`
 |pass:[`literal monospace text`]
 |pass:[`+literal monospace text+`]
-|1.5.0
-|Allowed with `compat-mode`
+|Allowed with `compat-mode`.
+See xref:asciidoc:text:monospace.adoc#literal-monospace[Literal monospace].
 
 |Curved "`double quotes`"
 |pass:[``double quotes'']
-|pass:["`double quotes`"], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8220;)
-|1.5.0
-|
+|pass:["`double quotes`"], editor keybinding, or Unicode character in numeric character reference form
+|See xref:asciidoc:text:quotation-marks-and-apostrophes.adoc[].
 
 |Curved '`single quotes`'
 |pass:[`single quotes']
-|pass:['`single quotes`'], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8217;)
-|1.5.0
-|
+|pass:['`single quotes`'], editor keybinding, or Unicode character in numeric character reference form
+|See xref:asciidoc:text:quotation-marks-and-apostrophes.adoc[].
 |===
 
 === Table of contents
 
-[cols="15,20,20,5,20"]
+[cols="~,~,~,~"]
 |===
-|Feature |Deprecated |New |As of Version |Notes
+|Feature |Deprecated |New |Notes
 
 |Scrollable, left margin TOC
 |`toc2`
 |`+:toc: left+`
-|1.5.0
-|
+|See xref:asciidoc:toc:position.adoc[].
 
 |TOC location
 |`toc-placement` and `toc-position`
 |`+:toc: <value>+`
-|1.5.0
-|
+|See xref:asciidoc:toc:position.adoc[].
 
 |User-specified TOC location
 |`+:toc-placement: manual+`
 |`+:toc: macro+`
-|1.5.0
-|
-
+|See xref:asciidoc:toc:position.adoc[].
 |===
 
 === Document header
 
-[cols="15,20,15,5,25"]
+[cols="~,~,~,~"]
 |===
-|Feature |Deprecated |New |As of Version |Notes
+|Feature |Deprecated |New |Notes
 
-|Setext (i.e., two-line style) document title
-l|Title
-=====
-l|= Title
-|
+|Two-line style (setext) document title
+|`Title` +
+`+=====+`
+|`={nbsp}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.
+But, by using it, `compat-mode` is implicitly set.
+To use the new syntax, use `= Title` or explicitly unset `compat-mode`.
+See xref:asciidoc:document:title.adoc[].
 |===
 
 === API
 
-[cols="15,20,20,5,20"]
+[cols="~,~,~"]
 |===
-|Feature |Deprecated |New |As of Version |Notes
+|Feature |Deprecated |New
 
-|render class method
-|+.render(input, options = {}) ⇒ Object+
-|+.convert(input, options = {}) ⇒ Object+
-|1.5.7
-|
+|Render class method
+|`+.render(input, options = {}) ⇒ Object+`
+|`+.convert(input, options = {}) ⇒ Object+`
 |===
 
 == New features
-- 
cgit v1.2.3


From b1e4fd07b0bc2484ef4fcad1a52ad79c289f31ee Mon Sep 17 00:00:00 2001
From: Sarah White <graphitefriction@gmail.com>
Date: Fri, 4 Dec 2020 17:23:10 -0700
Subject: update migration to Asciidoctor pages

---
 docs/modules/migrate/pages/confluence-xhtml.adoc |  4 ++--
 docs/modules/migrate/pages/markdown.adoc         |  6 +++---
 docs/modules/migrate/pages/ms-word.adoc          | 18 +++++++++---------
 3 files changed, 14 insertions(+), 14 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/migrate/pages/confluence-xhtml.adoc b/docs/modules/migrate/pages/confluence-xhtml.adoc
index 744cf0f1..20afe896 100644
--- a/docs/modules/migrate/pages/confluence-xhtml.adoc
+++ b/docs/modules/migrate/pages/confluence-xhtml.adoc
@@ -14,8 +14,8 @@ If you have trouble running this script, you can use the Pandoc command referenc
 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].
+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.
 
diff --git a/docs/modules/migrate/pages/markdown.adoc b/docs/modules/migrate/pages/markdown.adoc
index eab57dc3..2d19acdd 100644
--- a/docs/modules/migrate/pages/markdown.adoc
+++ b/docs/modules/migrate/pages/markdown.adoc
@@ -1,6 +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#.
+Asciidoctor recognizes some Markdown syntax, thus allowing you to migrate from Markdown to AsciiDoc gradually.
+See xref:asciidoc::syntax-quick-reference.adoc#markdown-compatibility[Markdown compatibility] to learn what syntax is shared.
+The syntax you must change is listed in the table under the xref:asciidoc::asciidoc-vs-markdown.adoc#comparison-by-example[Comparison by example section].
diff --git a/docs/modules/migrate/pages/ms-word.adoc b/docs/modules/migrate/pages/ms-word.adoc
index aea595c6..7936e787 100644
--- a/docs/modules/migrate/pages/ms-word.adoc
+++ b/docs/modules/migrate/pages/ms-word.adoc
@@ -1,6 +1,6 @@
 = 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.
+:description: This page 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/
@@ -54,9 +54,10 @@ Column widths are ignored.
 |Yes
 
 |URL links
-|No - see <<remove-refs,how to remove hyperlinks>> to fix it
+|No.
+See <<remove-refs,how to remove hyperlinks>> to fix it.
 
-|email links
+|Email links
 |Yes
 
 |Document automation (fields, auto-generated figure and table numbers)
@@ -121,7 +122,7 @@ If you have a lot to do, it's worth while cleaning the input document first, and
 ====
 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.
+Embedded images are located in [.path]_word/media_ directory.
 
  $ unzip input.docx -d input-docx
    ls input-docx/word/media/
@@ -140,7 +141,7 @@ Embedded images are located in [.path}_word/media_ directory.
 // 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.
+** 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.
@@ -172,7 +173,7 @@ It will get confused by abbreviations, but there is no way around that.
 == 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.
+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^].
 
@@ -180,9 +181,8 @@ The source for the add-on can be found in {url-google-asciidoc-source}[its repos
 
 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.
+* 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:
 
-- 
cgit v1.2.3


From 9200ee1771cd2ee8820093aee8d71e5275110b0c Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Tue, 8 Dec 2020 01:53:55 -0700
Subject: fix broken fragment links

---
 docs/modules/ROOT/pages/docinfo.adoc            | 6 +++---
 docs/modules/migrate/pages/asciidoc-python.adoc | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/pages/docinfo.adoc b/docs/modules/ROOT/pages/docinfo.adoc
index 0c5959ff..afaa0074 100644
--- a/docs/modules/ROOT/pages/docinfo.adoc
+++ b/docs/modules/ROOT/pages/docinfo.adoc
@@ -9,7 +9,7 @@ Docinfo files are useful for injecting auxiliary metadata, stylesheet, and scrip
 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>>).
+The docinfo feature must be explicitly enabled using the `docinfo` attribute (see <<enable>>).
 Which docinfo files get used depends on the value of the `docinfo` attribute as well as the backend.
 
 [#head]
@@ -44,7 +44,7 @@ Here's an example:
 ----
 
 Docinfo files for HTML output must be saved with the `.html` file extension.
-See <<name-docinfo>> for more details.
+See <<naming>> 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:
 
@@ -83,7 +83,7 @@ The following example shows some of the content a docinfo file for DocBook might
 ----
 
 Docinfo files for DocBook output must be saved with the `.xml` file extension.
-See <<name-docinfo>> for more details.
+See <<naming>> 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^].
 
diff --git a/docs/modules/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc
index 7f36cd8c..9120972c 100644
--- a/docs/modules/migrate/pages/asciidoc-python.adoc
+++ b/docs/modules/migrate/pages/asciidoc-python.adoc
@@ -303,7 +303,7 @@ a|
 |Not implemented.
 
 |`[latex]` block macro
-|Use a xref:asciidoc:stem:stem.adoc#stem-bl[stem block].
+|Use a xref:asciidoc:stem:stem.adoc#block[stem block].
 
 |`graphviz`
 |Use {url-diagram}[Asciidoctor Diagram^].
-- 
cgit v1.2.3


From faad155cc406d4e798d316a96a01c28bfcae1540 Mon Sep 17 00:00:00 2001
From: Sarah White <graphitefriction@gmail.com>
Date: Tue, 8 Dec 2020 14:08:49 -0700
Subject: update mysample and consolidate to my-document, generate new
 screenshots

---
 docs/modules/html-backend/examples/my-document.adoc  |  19 +++++++++++++++++++
 .../html-backend/examples/mysample-data-uri.adoc     |  17 -----------------
 .../modules/html-backend/examples/mysample-link.adoc |  13 -------------
 .../examples/mysample-stylesdir-link.adoc            |  15 ---------------
 .../html-backend/examples/mysample-stylesdir.adoc    |  14 --------------
 .../html-backend/examples/mysample-stylesheet.adoc   |  13 -------------
 docs/modules/html-backend/examples/mysample.adoc     |  12 ------------
 .../images/my-document-with-data-uri.png             | Bin 0 -> 465443 bytes
 docs/modules/html-backend/images/my-document.png     | Bin 0 -> 130457 bytes
 docs/modules/html-backend/images/wolpertinger.jpg    | Bin 0 -> 22487 bytes
 10 files changed, 19 insertions(+), 84 deletions(-)
 create mode 100644 docs/modules/html-backend/examples/my-document.adoc
 delete mode 100644 docs/modules/html-backend/examples/mysample-data-uri.adoc
 delete mode 100644 docs/modules/html-backend/examples/mysample-link.adoc
 delete mode 100644 docs/modules/html-backend/examples/mysample-stylesdir-link.adoc
 delete mode 100644 docs/modules/html-backend/examples/mysample-stylesdir.adoc
 delete mode 100644 docs/modules/html-backend/examples/mysample-stylesheet.adoc
 delete mode 100644 docs/modules/html-backend/examples/mysample.adoc
 create mode 100644 docs/modules/html-backend/images/my-document-with-data-uri.png
 create mode 100644 docs/modules/html-backend/images/my-document.png
 create mode 100644 docs/modules/html-backend/images/wolpertinger.jpg

(limited to 'docs/modules')

diff --git a/docs/modules/html-backend/examples/my-document.adoc b/docs/modules/html-backend/examples/my-document.adoc
new file mode 100644
index 00000000..e2a0abd5
--- /dev/null
+++ b/docs/modules/html-backend/examples/my-document.adoc
@@ -0,0 +1,19 @@
+// tag::title[]
+= The Dangers of Wolpertingers
+:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger
+// end::title[]
+// tag::body[]
+
+Don't worry about gumberoos or splintercats.
+Something far more fearsome plagues the days, nights, and inbetweens.
+Wolpertingers.
+
+== Origins
+
+Wolpertingers are {url-wolpertinger}[ravenous beasts].
+// end::body[]
+// tag::image[]
+[.left.text-center]
+image:wolpertinger.jpg[Wolpertinger,100,,link="https://commons.wikimedia.org/wiki/File:Wolpertinger.jpg"]
+They may look cute and cuddly, but don't be fooled.
+// end::image[]
diff --git a/docs/modules/html-backend/examples/mysample-data-uri.adoc b/docs/modules/html-backend/examples/mysample-data-uri.adoc
deleted file mode 100644
index ec32d03e..00000000
--- a/docs/modules/html-backend/examples/mysample-data-uri.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-= 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
deleted file mode 100644
index e24aeea9..00000000
--- a/docs/modules/html-backend/examples/mysample-link.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-= 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
deleted file mode 100644
index bb56b9e2..00000000
--- a/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-= 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
deleted file mode 100644
index 452e7f5c..00000000
--- a/docs/modules/html-backend/examples/mysample-stylesdir.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-= 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
deleted file mode 100644
index b1cc475c..00000000
--- a/docs/modules/html-backend/examples/mysample-stylesheet.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-= 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
deleted file mode 100644
index 0a00ca64..00000000
--- a/docs/modules/html-backend/examples/mysample.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-= 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/images/my-document-with-data-uri.png b/docs/modules/html-backend/images/my-document-with-data-uri.png
new file mode 100644
index 00000000..dafb8ced
Binary files /dev/null and b/docs/modules/html-backend/images/my-document-with-data-uri.png differ
diff --git a/docs/modules/html-backend/images/my-document.png b/docs/modules/html-backend/images/my-document.png
new file mode 100644
index 00000000..37b34fc0
Binary files /dev/null and b/docs/modules/html-backend/images/my-document.png differ
diff --git a/docs/modules/html-backend/images/wolpertinger.jpg b/docs/modules/html-backend/images/wolpertinger.jpg
new file mode 100644
index 00000000..cc2caa21
Binary files /dev/null and b/docs/modules/html-backend/images/wolpertinger.jpg differ
-- 
cgit v1.2.3


From 112d3f2d1640d528ce2f228f47d7be22edde381a Mon Sep 17 00:00:00 2001
From: Sarah White <graphitefriction@gmail.com>
Date: Tue, 8 Dec 2020 14:11:22 -0700
Subject: add my-document source and image references, update associated
 content

---
 docs/modules/get-started/pages/index.adoc          |  31 +++++++-----
 docs/modules/html-backend/images/no-stylesheet.png | Bin 75479 -> 108261 bytes
 .../html-backend/pages/custom-stylesheet.adoc      |  36 ++++++-------
 docs/modules/html-backend/pages/index.adoc         |  56 ++++++++++++---------
 docs/modules/html-backend/pages/manage-images.adoc |  25 ++++++---
 .../html-backend/pages/stylesheet-modes.adoc       |  43 ++++++++--------
 6 files changed, 105 insertions(+), 86 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/get-started/pages/index.adoc b/docs/modules/get-started/pages/index.adoc
index 9daf9562..7e689c15 100644
--- a/docs/modules/get-started/pages/index.adoc
+++ b/docs/modules/get-started/pages/index.adoc
@@ -11,17 +11,25 @@ On this page, you'll learn how to run Asciidoctor on an AsciiDoc document and co
 == 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.
+. To follow along with the steps below, copy the contents of <<ex-my-doc>> into a new plain text file or use your own AsciiDoc document.
++
+.my-document.adoc
+[source#ex-my-doc,asciidoc]
+----
+include::html-backend:example$my-document.adoc[tags=title;body]
+----
 
+. Make sure to save the file with the _.adoc_ file extension.
+. 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
+ $ asciidoctor my-document.adoc
 
 As long as the document didn't contain any syntax errors, you won't see any messages printed to your terminal.
 --
@@ -30,21 +38,20 @@ As long as the document didn't contain any syntax errors, you won't see any mess
 +
 --
  $ ls
- my-sample.adoc  my-sample.html
+ my-document.adoc  my-document.html
 
-You should see a new file named [.path]_my-sample.html_.
+You should see a new file named [.path]_my-document.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.
+. Open [.path]_my-document.html_ in your web browser.
 The converted document should look like the example below.
 +
-====
-#fix ex#
-//image::mysample.png[]
-====
-+
+--
+image::html-backend:my-document.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.
+As a result, you could save [.path]_my-document.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 xref:api:index.adoc[].
diff --git a/docs/modules/html-backend/images/no-stylesheet.png b/docs/modules/html-backend/images/no-stylesheet.png
index 77e880ad..ffe779b8 100644
Binary files a/docs/modules/html-backend/images/no-stylesheet.png and b/docs/modules/html-backend/images/no-stylesheet.png differ
diff --git a/docs/modules/html-backend/pages/custom-stylesheet.adoc b/docs/modules/html-backend/pages/custom-stylesheet.adoc
index 578681f4..18591039 100644
--- a/docs/modules/html-backend/pages/custom-stylesheet.adoc
+++ b/docs/modules/html-backend/pages/custom-stylesheet.adoc
@@ -30,29 +30,26 @@ Now let's use the `stylesheet` attribute to apply it.
 The `stylesheet` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
+.stylesheet attribute set in document header
 [source,asciidoc]
 ----
-= My First Experience with the Dangers of Documentation
+include::example$my-document.adoc[tag=title]
 :stylesheet: my-stylesheet.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.
+include::example$my-document.adoc[tag=body]
 ----
 
 You can also set `stylesheet` using the API or CLI (shown here):
 
- $ asciidoctor -a stylesheet=my-stylesheet.css document.adoc
+ $ asciidoctor -a stylesheet=my-stylesheet.css my-document.adoc
 
-When you view the generated HTML file [.path]_document.html_ in your browser, you'll see that all the text is red.
+When you view the generated HTML file [.path]_my-document.html_ in your browser, you'll see that all the text is red.
 
 TIP: If you want to create a custom stylesheet by extending the default stylesheet, see xref:default-stylesheet.adoc#customize-extend[Extend the default stylesheet].
 
 As with the default stylesheet, you can set the `linkcss` document attribute and Asciidoctor will link to your stylesheet instead.
 (Note that it doesn't copy it in this case since it's already in the same folder as the output file).
 
- $ asciidoctor -a stylesheet=my-stylesheet.css -a linkcss document.adoc
+ $ asciidoctor -a stylesheet=my-stylesheet.css -a linkcss my-document.adoc
 
 You may not want to keep your stylesheet in the same directory as your AsciiDoc documents.
 Let's see how to tell Asciidoctor to look for it elsewhere.
@@ -77,27 +74,24 @@ Now we need to tell Asciidoctor where it's located using `stylesdir`.
 The `stylesdir` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
+.stylesdir attribute set in document header
 [source,asciidoc]
 ----
-= My First Experience with the Dangers of Documentation
+include::example$my-document.adoc[tag=title]
 :stylesheet: my-stylesheet.css
 :stylesdir: my-styles
-
-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.
+include::example$my-document.adoc[tag=body]
 ----
 
 You can also set `stylesdir` using the API or CLI (shown here):
 
- $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css document.adoc
+ $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css my-document.adoc
 
 Asciidoctor now looks for the stylesheet file [.path]_my-styles/my-stylesheet.css_ relative to the AsciiDoc document and embeds it into the HTML.
 
 You can achieve the same result by including the directory in the value of the `stylesheet` attribute:
 
- $ asciidoctor -a stylesheet=my-styles/my-stylesheet.css document.adoc
+ $ asciidoctor -a stylesheet=my-styles/my-stylesheet.css my-document.adoc
 
 If you set the value of `stylesdir` to an absolute directory, then Asciidoctor would still locate the stylesheet and embed it into the HTML.
 But this can create problems if you've configured the converter to link to the stylesheet instead.
@@ -115,7 +109,7 @@ First, it's important to understand that Asciidoctor mirrors the `stylesdir` pat
 Let's use the previous example to demonstrate.
 If you invoke Asciidoctor as follows:
 
- $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css -a linkcss document.adoc
+ $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css -a linkcss my-document.adoc
 
 Then when you inspect the HTML, you will see:
 
@@ -131,9 +125,9 @@ There are certain situations where this isn't going to work (at least not when p
 Let's consider one such case.
 We'll specify the location of `stylesdir` as an absolute path and generate the output file into a separate output directory.
 
- $ asciidoctor -a stylesdir=`pwd`/my-styles -a stylesheet=my-stylesheet.css -a linkcss -D public document.adoc
+ $ asciidoctor -a stylesdir=`pwd`/my-styles -a stylesheet=my-stylesheet.css -a linkcss -D public my-document.adoc
 
-Asciidoctor generates the HTML file into the [.path]_public_ folder, but it _does not_ copy the stylesheet.
+Asciidoctor generates the HTML file into the [.path]_public_ folder, but it does not copy the stylesheet.
 Furthermore, it uses an absolute path in the link to the stylesheet:
 
 [source,html]
@@ -165,7 +159,7 @@ That means we can use `stylesdir` and `stylesheet` to assemble the path relative
 Let's revisit the broken scenario from the previous section and use `copycss` to reconcile the problem:
 
  $ asciidoctor -a stylesdir=css -a stylesheet=default.css \
- -a copycss=`pwd`/my-styles/my-stylesheet.css -a linkcss -D public document.adoc
+ -a copycss=`pwd`/my-styles/my-stylesheet.css -a linkcss -D public my-document.adoc
 
 Asciidoctor copies the stylesheet from the absolute path specified by the `copycss` attribute to the path [.path]_public/css/default.css_ and links to it using the path [.path]_css/default.css_.
 Notice that we even changed the name of the folder and stylesheet file in the output.
diff --git a/docs/modules/html-backend/pages/index.adoc b/docs/modules/html-backend/pages/index.adoc
index 2e556ed4..b9d89a91 100644
--- a/docs/modules/html-backend/pages/index.adoc
+++ b/docs/modules/html-backend/pages/index.adoc
@@ -11,44 +11,52 @@ Asciidoctor's default output format is HTML.
 
 In this section, we'll create a sample document, then process and convert it with Asciidoctor's built-in HTML converter.
 
-. Create an AsciiDoc file like the one below
-. Save the file as [.path]_my-sample.adoc_
+=== Create and save an AsciiDoc document
 
-[source,asciidoc]
+. To follow along with the steps below, use your own AsciiDoc file or copy the contents of <<ex-my-doc>> into a new plaintext file.
++
+.my-document.adoc
+[source#ex-my-doc,asciidoc]
 ----
-include::example$mysample.adoc[]
+include::example$my-document.adoc[tags=title;body]
 ----
 
-To convert [.path]_my-sample.adoc_ to HTML from the command line:
+. Make sure to save the file with the _.adoc_ file extension.
 
-. 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
+=== Convert an AsciiDoc document to HTML
 
-//^
+To convert [.path]_my-document.adoc_ to HTML from the command line:
 
- $ asciidoctor my-sample.adoc
+. Open a terminal.
+. Switch to the directory that contains the [.path]_my-document.adoc_ document
+. Call the Asciidoctor processor with the `asciidoctor` command, followed by the name of the document.
++
+--
+ $ asciidoctor my-document.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_.
-
+. You won't see any messages printed to the console.
+Type `ls` to view the files in the directory or navigate to the directory in a file manager.
+You should see a new file named [.path]_my-document.html_.
++
+--
  $ ls
- my-sample.adoc  my-sample.html
+ my-document.adoc  my-document.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.
+. Open [.path]_my-document.html_ in your web browser.
 Your document should look like the image below.
++
+--
+image::my-document.png[]
 
-====
-#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.
+The document's text, titles, and link are styled by the default Asciidoctor stylesheet, which is embedded in the HTML output.
+As a result, you could save [.path]_my-document.html_ to any computer and it will look the same.
+--
 
 [#xhtml]
 == Generate XHTML
@@ -59,7 +67,7 @@ To use the XHTML converter, assign `xhtml` or `xhtml5` to the `backend` option.
 .Produce XHTML using the xhtml5 backend option
 [source,console]
 ----
-asciidoctor -b xhtml5 document.adoc
+$ asciidoctor -b xhtml5 my-document.adoc
 ----
 
 To produce XHTML instead of HTML when using converter templates, set the `htmlsyntax` attribute to `xml` in addition to the backend option:
@@ -67,7 +75,7 @@ To produce XHTML instead of HTML when using converter templates, set the `htmlsy
 .Produce XHTML using custom templates
 [source,console]
 ----
-asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml document.adoc
+$ asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml my-document.adoc
 ----
 
 .Black Box Decoded: XHTML and htmlsyntax
diff --git a/docs/modules/html-backend/pages/manage-images.adoc b/docs/modules/html-backend/pages/manage-images.adoc
index 38b69aae..94323a93 100644
--- a/docs/modules/html-backend/pages/manage-images.adoc
+++ b/docs/modules/html-backend/pages/manage-images.adoc
@@ -3,22 +3,31 @@
 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.
+== Embed images with the data-uri attribute
 
- $ asciidoctor -a data-uri my-sample.adoc
+As an alternative, you can embed the images directly into the document by setting the `data-uri` document attribute.
 
+.data-uri attribute set in document header
 [source,asciidoc]
 ----
-include::example$mysample-data-uri.adoc[]
+include::example$my-document.adoc[tag=title]
+:imagesdir: my-images
+:data-uri:
+include::example$my-document.adoc[tags=body;image]
 ----
 
-====
-#fix ex#
-//image::mysample-data-uri.png[]
-====
+You can also set `data-uri` using the API or CLI (shown here):
+
+ $ asciidoctor -a data-uri my-document.adoc
+
+When you view the HTML file in your browser, you should see the image displayed in the page.
+
+image::my-document-with-data-uri.png[]
+
+== allow-uri-read attribute
 
 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
+ $ asciidoctor -a data-uri -a allow-uri-read my-document.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/stylesheet-modes.adoc b/docs/modules/html-backend/pages/stylesheet-modes.adoc
index 8b2fdd90..5379ed38 100644
--- a/docs/modules/html-backend/pages/stylesheet-modes.adoc
+++ b/docs/modules/html-backend/pages/stylesheet-modes.adoc
@@ -32,23 +32,21 @@ If the `linkcss` document attribute is set, the converter will take this hint to
 The `linkcss` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
+.linkcss attribute set in document header
 [source,asciidoc]
 ----
-= My First Experience with the Dangers of Documentation
+include::example$my-document.adoc[tag=title]
 :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.
+include::example$my-document.adoc[tag=body]
 ----
 
 You can also set `linkcss` using the API or CLI (shown here):
 
- $ asciidoctor -a linkcss document.adoc
+ $ asciidoctor -a linkcss my-document.adoc
 
-In either case, if you inspect the `<head>` tag in the output file [.path]_document.html_, you'll see that the HTML links to the stylesheet.
+In either case, if you inspect the `<head>` tag in the output file [.path]_my-document.html_, you'll see that the HTML links to the stylesheet.
 
+.my-document.html
 [source,html]
 ----
 <link rel="stylesheet" href="./asciidoctor.css">
@@ -69,7 +67,7 @@ When using the default stylesheet, Asciidoctor writes the CSS to the file [.path
 If you specify a custom stylesheet, Asciidoctor will copy that file instead, retaining the name of the file.
 This utility works even if you specify an xref:cli:output-file.adoc[output file in a different directory] from the source file.
 
-.A shared responsiblity
+.A shared responsibility
 ****
 While the converter handles the task of embedding or linking to the stylesheet file, it's the processor itself (not the converter) that handles copying the stylesheet.
 ****
@@ -78,9 +76,15 @@ If the safe mode is secure, Asciidoctor will not copy the stylesheet file and, t
 
 Let's revisit the previous example:
 
- $ asciidoctor -a linkcss document.adoc
+ $ asciidoctor -a linkcss my-document.adoc
+
+After running this command, the stylesheet file [.path]_asciidoctor.css_ is copied to the same directory as the generated HTML file [.path]_my-document.html_.
+Type `ls` to view the files in the directory.
+You should see a file named [.path]_asciidoctor.css_.
+
+ $ ls
+ asciidoctor.css  my-document.adoc  my-document.html
 
-After running this command, you should see the stylesheet file [.path]_asciidoctor.css_ adjacent to the HTML file [.path]_document.html_.
 When you view the HTML file in your browser, you should observe that the default stylesheet is applied.
 
 === To copy or not to copy
@@ -93,21 +97,18 @@ To prevent Asciidoctor from copying the stylesheet independent of safe mode, uns
 The `copycss` document attribute must be unset by the end of the header to be effective.
 One way to do that is to unset the attribute in the document header:
 
+.copycss attribute unset in document header
 [source,asciidoc]
 ----
-= My First Experience with the Dangers of Documentation
+include::example$my-document.adoc[tag=title]
 :linkcss:
 :!copycss:
-
-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.
+include::example$my-document.adoc[tag=body]
 ----
 
 You can also unset `copycss` using the API or CLI (shown here):
 
- $ asciidoctor -a linkcss -a copycss! document.adoc
+ $ asciidoctor -a linkcss -a copycss! my-document.adoc
 
 In either case, if you inspect the output directory, you will see that the stylesheet file [.path]_asciidoctor.css_ is missing (unless it was already there).
 
@@ -117,15 +118,15 @@ We'll see the `copycss` attribute come up again on the xref:custom-stylesheet.ad
 == Disable the stylesheet
 
 The stylesheet is effectively disabled when generating embedded HTML, since the embedded HTML does not include the `<head>` tag.
-If you don't want the converter to include a stylesheet in the standalone HTML, unset the `stylesheet` document attribute:
+If you don't want the converter to include a stylesheet in the standalone HTML, unset the `stylesheet` attribute using the CLI.
 
- $ asciidoctor -a stylesheet! document.adoc
+ $ asciidoctor -a stylesheet! my-document.adoc
 
 The reason you have to unset the `stylesheet` attribute is because it is set by default (to an empty value).
 When the `stylesheet` attribute is set, but empty, the HTML converter uses the default stylesheet.
 By unsetting this attribute, we're telling the converter not to use a stylesheet at all.
 
-When you view the generated HTML file, [.path]_document.html_, you'll see bare HTML without any styles applied, as shown here:
+When you view the generated HTML file, [.path]_my-document.html_, you'll see bare HTML without any styles applied, as shown here:
 
 image::no-stylesheet.png[]
 
-- 
cgit v1.2.3


From 8c616bb8cc7a3e5797381bc7dd637c1c8422a599 Mon Sep 17 00:00:00 2001
From: Sarah White <graphitefriction@gmail.com>
Date: Tue, 8 Dec 2020 14:31:56 -0700
Subject: update DocBook index.adoc with new example and XML snippet

---
 docs/modules/docbook-backend/pages/index.adoc | 72 +++++++++++++--------------
 1 file changed, 35 insertions(+), 37 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/docbook-backend/pages/index.adoc b/docs/modules/docbook-backend/pages/index.adoc
index b6e5c184..b2bf6fc7 100644
--- a/docs/modules/docbook-backend/pages/index.adoc
+++ b/docs/modules/docbook-backend/pages/index.adoc
@@ -14,14 +14,25 @@ To use the DocBook converter, assign `docbook` or `docbook5` to the `backend` op
 
 == 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`.
+. To follow along with the steps below, use your own AsciiDoc file or copy the contents of <<ex-my-doc>> into a new plain text file.
++
+.my-document.adoc
+[source#ex-my-doc,asciidoc]
+----
+include::html-backend:example$my-document.adoc[tags=title;body]
+----
 
- $ asciidoctor -b docbook mysample.adoc
+. Make sure to save the file with the _.adoc_ file extension.
 
-A new XML document, named [.path]_mysample.xml_, will now be present in the current directory.
+. To convert the [.path]_my-document.adoc_ document to DocBook 5.0 format, call the processor with the backend flag set to `docbook`.
 
+ $ asciidoctor -b docbook my-document.adoc
+
+. A new XML document, named [.path]_my-document.xml_, will now be present in the current directory.
++
+--
  $ ls
- mysample.adoc  mysample.html  mysample.xml
+ my-document.adoc  my-document.xml
 
 Here's a snippet of the XML generated by the DocBook converter.
 
@@ -29,40 +40,27 @@ Here's a snippet of the XML generated by the DocBook converter.
 [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>
+<?asciidoc-toc?>
+<?asciidoc-numbered?>
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
+<info>
+<title>The Dangers of Wolpertingers</title>
+<date>2020-12-08</date>
+</info>
+<simpara>Don&#8217;t worry about gumberoos or splintercats.
+Something far more fearsome plagues the days, nights, and inbetweens.
+Wolpertingers.</simpara>
+<section xml:id="_origins">
+<title>Origins</title>
+<simpara>Wolpertingers are <link xl:href="https://en.wikipedia.org/wiki/Wolpertinger">ravenous beasts</link>.</simpara>
+</section>
 </article>
 ----
+--
 
-On Linux, you can view the DocBook file with {url-yelp}[Yelp^].
-
- $ yelp mysample.xml
+. On Linux, you can view the DocBook file with {url-yelp}[Yelp^].
++
+ $ yelp my-document.xml
 
 The DocBook converter produces output that is compliant to the DocBook 5.0 specification.
 
@@ -80,7 +78,7 @@ If you're using the Asciidoctor API, you can generate a DocBook document directl
 .Generate DocBook output from the API
 [source,ruby]
 ----
-Asciidoctor.convert_file 'mysample.adoc', backend: 'docbook'
+Asciidoctor.convert_file 'my-document.adoc', backend: 'docbook'
 ----
 
-If you need to output DocBook 4.5, you may find the community-supported {url-docbook45}[DocBook 4.5 Converter] useful.
+If you need to output DocBook 4.5, you may find the community-supported {url-docbook45}[DocBook 4.5 Converter^] useful.
-- 
cgit v1.2.3


From 717a1cbd6b7c9af192325b76d96ae5e86aeeb595 Mon Sep 17 00:00:00 2001
From: Sarah White <graphitefriction@gmail.com>
Date: Fri, 18 Dec 2020 16:45:39 -0700
Subject: update listing syntax for commands

---
 docs/modules/ROOT/pages/localization-support.adoc |  4 +---
 docs/modules/html-backend/pages/index.adoc        | 10 ++--------
 2 files changed, 3 insertions(+), 11 deletions(-)

(limited to 'docs/modules')

diff --git a/docs/modules/ROOT/pages/localization-support.adoc b/docs/modules/ROOT/pages/localization-support.adoc
index 054dd96a..5a357f33 100644
--- a/docs/modules/ROOT/pages/localization-support.adoc
+++ b/docs/modules/ROOT/pages/localization-support.adoc
@@ -28,9 +28,7 @@ When converting to DocBook, you can rely on the DocBook toolchain to translate (
 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
-----
+ $ 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^].
 
diff --git a/docs/modules/html-backend/pages/index.adoc b/docs/modules/html-backend/pages/index.adoc
index b9d89a91..f3097f83 100644
--- a/docs/modules/html-backend/pages/index.adoc
+++ b/docs/modules/html-backend/pages/index.adoc
@@ -65,18 +65,12 @@ As a result, you could save [.path]_my-document.html_ to any computer and it wil
 To use the XHTML converter, assign `xhtml` or `xhtml5` to the `backend` option.
 
 .Produce XHTML using the xhtml5 backend option
-[source,console]
-----
-$ asciidoctor -b xhtml5 my-document.adoc
-----
+ $ asciidoctor -b xhtml5 my-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 my-document.adoc
-----
+ $ asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml my-document.adoc
 
 .Black Box Decoded: XHTML and htmlsyntax
 ****
-- 
cgit v1.2.3