rearchitect modules and filenames and drop asciidoctor folder under docs

103 files changed, 267 insertions, 482 deletions

diff --git a/docs/asciidoctor/antora.yml b/docs/antora.yml
index 56398b25..04f1af56 100644
--- a/docs/asciidoctor/antora.yml
+++ b/docs/antora.yml
@@ -19,8 +19,11 @@ asciidoc:
 nav:
 - modules/ROOT/nav-top.adoc
 - modules/install/nav.adoc
-- modules/ROOT/nav-get-started.adoc
-- modules/backends/nav.adoc
+- modules/get-started/nav.adoc
+- modules/ROOT/nav-converters.adoc
+- modules/html-backend/nav.adoc
+- modules/docbook-backend/nav.adoc
+- modules/manpage-backend/nav.adoc
 - modules/cli/nav.adoc
 - modules/api/nav.adoc
 - modules/ROOT/nav-safe-modes.adoc
@@ -31,4 +34,3 @@ nav:
 - modules/ROOT/nav-lang.adoc
 - modules/ROOT/nav-errors.adoc
 - modules/migrate/nav.adoc
-- modules/ROOT/nav-project.adoc
diff --git a/docs/asciidoctor/modules/ROOT/nav-get-started.adoc b/docs/asciidoctor/modules/ROOT/nav-get-started.adoc
deleted file mode 100644
index 827304ad..00000000
--- a/docs/asciidoctor/modules/ROOT/nav-get-started.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-* Get Started with Asciidoctor
-** xref:convert-asciidoc-file.adoc[]
-** xref:core-concepts.adoc[]
-** xref:converters.adoc[]
diff --git a/docs/asciidoctor/modules/ROOT/nav-project.adoc b/docs/asciidoctor/modules/ROOT/nav-project.adoc
deleted file mode 100644
index 579b3efd..00000000
--- a/docs/asciidoctor/modules/ROOT/nav-project.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-* About Asciidoctor
-//.Asciidoctor Project and Community
-** xref:project/release-schedule.adoc[]
-** xref:project/license-and-authors.adoc[]
diff --git a/docs/asciidoctor/modules/ROOT/pages/core-concepts.adoc b/docs/asciidoctor/modules/ROOT/pages/core-concepts.adoc
deleted file mode 100644
index fb72e356..00000000
--- a/docs/asciidoctor/modules/ROOT/pages/core-concepts.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-= Core Concepts
-
-Asciidoctor parses AsciiDoc documents and then uses a converter to generate the output format of your choice, such as HTML, DocBook, or PDF.
-During this process, Asciidoctor applies its default stylesheet or the stylesheet you provide.
-
-== 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 comes with built-in HTML, DocBook, and manual page (man page) converters.
-You can also plug in EPUB, PDF, LaTeX, HTML slide deck, and static website converters.
-See xref:converters.adoc[] for descriptions of all of the supported converters.
-
-== What's the default stylesheet?
-
-Asciidoctor comes with a stylesheet that's applied to the output of the built-in converters.
-This stylesheet is applied by default unless you tell Asciidoctor to use another stylesheet.
-See xref:backends:html/apply-stylesheet.adoc[] to learn about the default and custom stylesheet options.
diff --git a/docs/asciidoctor/modules/ROOT/pages/project/license-and-authors.adoc b/docs/asciidoctor/modules/ROOT/pages/project/license-and-authors.adoc
deleted file mode 100644
index c9d5e5a1..00000000
--- a/docs/asciidoctor/modules/ROOT/pages/project/license-and-authors.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-= License
-//License and Contributors
-:url-license: {url-org}/asciidoctor/blob/master/LICENSE
-:mojavelinux: https://github.com/mojavelinux
-:erebor: https://github.com/erebor
-:lightguard: https://github.com/lightguard
-:nickh: https://github.com/nickh
-:graphitefriction: https://github.com/graphitefriction
-:contributors: https://github.com/asciidoctor/asciidoctor/graphs/contributors
-:gitscm-next: https://github.com/github/gitscm-next
-:seed-contribution: https://github.com/github/gitscm-next/commits/master/lib/asciidoc.rb
-
-== License
-
-Copyright (C) 2012-2020 Dan Allen, Sarah White, and Ryan Waldron.
-Free use of this software is granted under the terms of the MIT License.
-
-See the {url-license}[LICENSE^] file for details.
-
-== Authors and Contributors
-
-*Asciidoctor* was written by Dan Allen, Sarah White, Ryan Waldron, Jason Porter, Nick Hengeveld and many other contributors.
-
-The initial code from which Asciidoctor emerged was written by Nick Hengeveld to process the git man pages for the Git project site.
-Refer to the commit history of asciidoc.rb to view the initial contributions.
-
-*AsciiDoc* was written by Stuart Rackham and has received contributions from many other individuals.
-
-// TODO fill in this section and enable
-// Thanks, acknowledgments, and credits
-
-////
-Put links back in when reorganized
-
-*Asciidoctor* was written by {mojavelinux}[Dan Allen], {graphitefriction}[Sarah White], {erebor}[Ryan Waldron], {lightguard}[Jason Porter], {nickh}[Nick Hengeveld] and {contributors}[many other contributors].
-
-The initial code from which Asciidoctor emerged was written by {nickh}[Nick Hengeveld] to process the git man pages for the {gitscm-next}[Git project site].
-Refer to the commit history of {seed-contribution}[asciidoc.rb] to view the initial contributions.
-
-*AsciiDoc* was written by Stuart Rackham and has received contributions from many other individuals.
-////
diff --git a/docs/asciidoctor/modules/ROOT/pages/project/release-schedule.adoc b/docs/asciidoctor/modules/ROOT/pages/project/release-schedule.adoc
deleted file mode 100644
index 6ad8674b..00000000
--- a/docs/asciidoctor/modules/ROOT/pages/project/release-schedule.adoc
+++ /dev/null
@@ -1,77 +0,0 @@
-= Asciidoctor Release Schedule
-:navtitle: Release Schedule
-
-Each major release line of Asciidoctor is typically supported for one year after it enters general availability (GA).
-Dates are formatted as year/month/day.
-
-[%autowidth]
-|===
-|Release Line |Latest Release |Status |GA |Maintenance |EOL
-
-|Asciidoctor 2.x
-|{release-version}
-|Active
-|2019/03/22
-|TBD
-|TBD
-
-|Asciidoctor 1.5.8
-|1.5.8
-|EOL
-|2018/05/02
-|2019/04/22
-|2019/12/31
-|===
-
-General Availability (GA):: A release line, such as Asciidoctor 2.x, enters general availability on the date the initial, final major version (e.g., Asciidoctor 2.0.0) of the software is released and available for download.
-
-Active:: Release line is being actively improved and supported.
-
-Maintenance:: Once a release line enters its maintenance period, only its most recent minor version will receive critical security patch releases.
-A release line starts this phase 30 days after the next major release line goes GA.
-
-End of Life (EOL):: The date after which the release line no longer receives support or releases.
-
-== Version policy
-
-Asciidoctor began semantic versioning with the release of Asciidoctor 2.0.0.
-Each Asciidoctor release is versioned *major.minor.patch*.
-
-Major::
-Major releases occur when there are substantial changes in functionality or when new functionality breaks backwards compatibility.
-Releases within the same major release line will maintain API compatibility.
-
-Minor::
-Minor releases add new features, improvements to existing features, and fixes that maintain backwards compatibility.
-
-Patch::
-Patch releases fix bugs and maintain backwards compatibility.
-Only the latest minor release of a major release line will receive patches.
-Patch releases happen as needed depending on the urgency of the fix.
-
-Prerelease::
-Major and minor releases may include prerelease versions (major.minor.patch-alpha.n | -beta.n | -rc.n).
-Once a release candidate (rc) has been thoroughly tested, the stable release will be published.
-
-The information on this page is believed to be accurate as of the date of publication, but updates and revisions may be posted periodically and without notice.
-
-////
-== 1.5.8 Version Policy
-
-Any Asciidoctor versions prior to Asciidoctor 2.0.0 may introduce significant functionality changes and not be backwards compatible with previous versions.
-Bug fixes are only provided for the most recent version.
-
-|Asciidoctor 1.5.7
-|EOL
-|2018/05/02
-|2018/05/02
-|2018/12/31
-|2018/12/31
-
-|Asciidoctor 1.5.6.2
-|EOL
-|2017/07/23
-|2017/07/23
-|2018/05/02
-|2018/05/02
-////
diff --git a/docs/asciidoctor/modules/backends/nav.adoc b/docs/asciidoctor/modules/backends/nav.adoc
deleted file mode 100644
index 082db615..00000000
--- a/docs/asciidoctor/modules/backends/nav.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-* Backends and Output Formats
-** xref:html/convert-to-html.adoc[]
-*** xref:html/manage-images.adoc[]
-*** xref:html/manage-stylesheets.adoc[]
-*** xref:html/apply-code-stylesheets.adoc[]
-*** xref:html/wrap.adoc[]
-*** xref:html/create-stylesheet.adoc[]
-*** xref:html/apply-stylesheet.adoc[]
-*** xref:html/favicon.adoc[]
-*** xref:html/front-matter.adoc[]
-** xref:docbook/convert-to-docbook.adoc[]
-** xref:manpage/convert-to-man-page.adoc[]
diff --git a/docs/asciidoctor/modules/backends/pages/html/create-stylesheet.adoc b/docs/asciidoctor/modules/backends/pages/html/create-stylesheet.adoc
deleted file mode 100644
index bdda4d0a..00000000
--- a/docs/asciidoctor/modules/backends/pages/html/create-stylesheet.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-= Create a Custom Stylesheet
-:url-sass-settings: https://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/sass/settings/_settings.scss.dist
-:url-sass-defaults: https://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/sass/settings/_defaults.scss
-
-You can create your own themes to apply to your documents.
-
-Themes go in the [.path]_sass/_ folder.
-To create a new theme, let's call it `hipster`, start by creating two new files:
-
-[.path]_sass/hipster.scss_::
-  * Imports the theme settings, which includes default variables and resets
-  * Imports the AsciiDoc components
-  * Defines any explicit customization
-
-[.path]_sass/settings/_hipster.scss_::
-  * Sets variables that customize Foundation 4 and the AsciiDoc CSS components
-
-Here's a minimal version of [.path]_sass/hipster.scss_:
-
-[source,scss]
-----
-@import "settings/hipster";
-@import "components/asciidoc";
-@import "components/awesome-icons";
-----
-
-NOTE: You don't have to include the underscore prefix when importing files.
-
-//NOTE: The `awesome-icons` component is only applicable to HTML generated by Asciidoctor > 0.1.2 with the `icons` attribute set to `font`.
-
-You can add any explicit customization below the import lines.
-
-The variables you can set in [.path]_sass/settings/_hipster.scss_ are a combination of the {url-sass-settings}[Foundation 4 built-in global settings^] and {url-sass-defaults}[global settings and imports for the AsciiDoc components^].
-
-Once you've created your custom theme, it's time to xref:html/apply-stylesheet.adoc[apply it to your document].
diff --git a/docs/asciidoctor/modules/extensions/pages/register.adoc b/docs/asciidoctor/modules/extensions/pages/register.adoc
deleted file mode 100644
index b21ad41c..00000000
--- a/docs/asciidoctor/modules/extensions/pages/register.adoc
+++ /dev/null
@@ -1,102 +0,0 @@
-= Register 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 xref:register.adoc[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^].
-
-== 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.
-
-NOTE: There is currently no extension point for processing a built-in block, such as a normal paragraph.
-Look for that feature in a future Asciidoctor release.
-
-////
-See if this warning is still necessary:
-
-WARNING: The extension API in Asciidoctor is stable with the exception of inline macros.
-Since inline content is not parsed until the convert phase, the inline macro processor must return converted text (e.g., HTML) rather than an AST node.
-Once Asciidoctor is changed to https://github.com/asciidoctor/asciidoctor/issues/61[process inline content during the parse phase^], the inline macro processor will need to return an inline node.
-When that switch occurs, there will either be some sort of adapter or required migration for inline macro processors, but that has yet to be determined.
-
-However, the way extensions are implemented in AsciiDoc Python presents a number of problems:
-
-* They are challenging to write because they work at such a low-level (read as: nasty regular expressions).
-* They are fragile since they often rely on system commands to do anything significant.
-* They are hard to distribute due to the lack of integration with a formal distribution system.
-
-For now, you need to use the Asciidoctor API (not the CLI) in order to register the extensions and invoke Asciidoctor.
-Eventually, we'll be able to load extensions packaged in a RubyGem (Ruby) or JAR (Java) by scanning
-the LOAD_PATH (Ruby) or classpath (Java), respectively.
-We may also ship some built-in extensions that can be enabled using an attribute named `extensions`, similar to how Markdown processors work.
-
-TIP: For those of you on the JVM, yes, you can write extensions in Java.
-We've prototyped it and it works.
-We're still sorting out a few technical challenges and documentation to make it completely smooth, but we'll get there.
-For details, follow the discussion in issue {issue-ref}/79[#79].
-////
diff --git a/docs/asciidoctor/modules/install/pages/install.adoc b/docs/asciidoctor/modules/install/pages/install.adoc
deleted file mode 100644
index ed308478..00000000
--- a/docs/asciidoctor/modules/install/pages/install.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-= 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.
-
-=== Linux package managers
-
-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.
-
-* https://pkgs.alpinelinux.org/packages?name=asciidoctor[Alpine Linux (asciidoctor)]
-* https://www.archlinux.org/packages/?name=asciidoctor[Arch Linux (asciidoctor)]
-* https://packages.debian.org/sid/asciidoctor[Debian (asciidoctor)]
-* https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Fedora (asciidoctor)]
-* https://software.opensuse.org/package/rubygem-asciidoctor[OpenSUSE (rubygem-asciidoctor)]
-* https://packages.ubuntu.com/search?keywords=asciidoctor[Ubuntu (asciidoctor)]
-
-If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, see the <<gem-install,gem installation instructions>>.
-
-However, some Linux distributions don't have the latest version of Asciidoctor packaged immediately after a new Asciidoctor gem is released.
-If you need the latest version of Asciidoctor immediately, you'll have to use the `gem` command.
-You'll also use the gem command to install a xref:gem.adoc#pre-release[pre-release version of Asciidoctor].
diff --git a/docs/asciidoctor/modules/install/pages/upgrade.adoc b/docs/asciidoctor/modules/install/pages/upgrade.adoc
deleted file mode 100644
index 50c86269..00000000
--- a/docs/asciidoctor/modules/install/pages/upgrade.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-= Upgrade Asciidoctor
-
-[#upgrade-on-linux]
-== Upgrade 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.
-
-=== Alpine Linux
-
-On Alpine Linux, update the Asciidoctor package using:
-
- $ sudo apk add -u asciidoctor
-
-=== 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
-
-[#upgrade-on-macos]
-== Upgrade on macOS with Homebrew
-
-include::partial$upgrade-on-macos.adoc[]
-
-[#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.
-
-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/asciidoctor/modules/install/partials/upgrade-on-macos.adoc b/docs/asciidoctor/modules/install/partials/upgrade-on-macos.adoc
deleted file mode 100644
index ab2fc9c1..00000000
--- a/docs/asciidoctor/modules/install/partials/upgrade-on-macos.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-To upgrade the gem, open a terminal and type:
-
- $ brew update
- $ brew upgrade asciidoctor
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/asciidoctor/modules/ROOT/nav-docinfo.adoc b/docs/modules/ROOT/nav-docinfo.adoc
index dd0e50db..dd0e50db 100644
--- a/docs/asciidoctor/modules/ROOT/nav-docinfo.adoc
+++ b/docs/modules/ROOT/nav-docinfo.adoc
diff --git a/docs/asciidoctor/modules/ROOT/nav-errors.adoc b/docs/modules/ROOT/nav-errors.adoc
index 5c15a194..5c15a194 100644
--- a/docs/asciidoctor/modules/ROOT/nav-errors.adoc
+++ b/docs/modules/ROOT/nav-errors.adoc
diff --git a/docs/asciidoctor/modules/ROOT/nav-lang.adoc b/docs/modules/ROOT/nav-lang.adoc
index 278dbd67..278dbd67 100644
--- a/docs/asciidoctor/modules/ROOT/nav-lang.adoc
+++ b/docs/modules/ROOT/nav-lang.adoc
diff --git a/docs/asciidoctor/modules/ROOT/nav-safe-modes.adoc b/docs/modules/ROOT/nav-safe-modes.adoc
index be07ed4d..be07ed4d 100644
--- a/docs/asciidoctor/modules/ROOT/nav-safe-modes.adoc
+++ b/docs/modules/ROOT/nav-safe-modes.adoc
diff --git a/docs/asciidoctor/modules/ROOT/nav-top.adoc b/docs/modules/ROOT/nav-top.adoc
index 626f552c..98431ff5 100644
--- a/docs/asciidoctor/modules/ROOT/nav-top.adoc
+++ b/docs/modules/ROOT/nav-top.adoc
@@ -1,2 +1,2 @@
-* xref:whats-new.adoc[]
 * xref:features.adoc[]
+* xref:whats-new.adoc[]
diff --git a/docs/asciidoctor/modules/ROOT/pages/attributes-and-safe-modes.adoc b/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
index 4d28d210..4d28d210 100644
--- a/docs/asciidoctor/modules/ROOT/pages/attributes-and-safe-modes.adoc
+++ b/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
diff --git a/docs/asciidoctor/modules/ROOT/pages/converters.adoc b/docs/modules/ROOT/pages/converters.adoc
index 30a16af3..9340f9f0 100644
--- a/docs/asciidoctor/modules/ROOT/pages/converters.adoc
+++ b/docs/modules/ROOT/pages/converters.adoc
@@ -1,11 +1,17 @@
-= Choose a Converter
+= 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 web publishing 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.
+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.
 
-Converter:: Generates a specific output format from AsciiDoc.
 Each converter is mapped to a name that you specify using the `-b` (`--backend`) command line option or `backend` API option.
 
 == Built-in converters
@@ -16,16 +22,19 @@ HTML::
 The HTML 5 converter (`html` or `html5`) generates HTML 5 styled with CSS3.
 This is the converter Asciidoctor uses by default.
 
-xref:backends:html/convert-to-html.adoc#xhtml[XHTML]::
-The XHTML variant (`xhtml` or `xhtml5`) of the HTML 5 converter.
+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:backends:docbook/convert-to-docbook.adoc[DocBook]::
-The DocBook 5.0 converter (`docbook` or `docbook5`) generates DocBook 5.0 XML.
+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:backends:manpage/convert-to-man-page.adoc[Man page]::
-The man page converter (`manpage`) generates manual pages for software used on Unix and Unix-like operating systems.
+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.
 
-== Document and book converters
+== 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`).
 
@@ -37,18 +46,6 @@ 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.
 
-////
-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).
-////
-
-== HTML slide deck converters
-
 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^].
@@ -58,6 +55,14 @@ 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
@@ -65,11 +70,6 @@ Requires https://github.com/asciidoctor/asciidoctor-bespoke[Asciidoctor Bespoke^
 * Antora
 ////
 
-== Next
-
-* Learn how to use the xref:cli:cli.adoc[Asciidoctor command line interface].
-* xref:convert-asciidoc-file.adoc[Convert your first AsciiDoc file to HTML] using the default converter.
-
 // TODO describe the role of template converters (e.g., asciidoctor-backends)
 
 ////
diff --git a/docs/asciidoctor/modules/ROOT/pages/docinfo.adoc b/docs/modules/ROOT/pages/docinfo.adoc
index 2c2cc28c..2c2cc28c 100644
--- a/docs/asciidoctor/modules/ROOT/pages/docinfo.adoc
+++ b/docs/modules/ROOT/pages/docinfo.adoc
diff --git a/docs/asciidoctor/modules/ROOT/pages/errors-and-warnings.adoc b/docs/modules/ROOT/pages/errors-and-warnings.adoc
index 9b3c2dee..9b3c2dee 100644
--- a/docs/asciidoctor/modules/ROOT/pages/errors-and-warnings.adoc
+++ b/docs/modules/ROOT/pages/errors-and-warnings.adoc
diff --git a/docs/asciidoctor/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc
index f5ed7914..f5ed7914 100644
--- a/docs/asciidoctor/modules/ROOT/pages/features.adoc
+++ b/docs/modules/ROOT/pages/features.adoc
diff --git a/docs/asciidoctor/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index 7a110928..637ce9f3 100644
--- a/docs/asciidoctor/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -40,8 +40,8 @@ Asciidoctor.convert_file \
   'document.adoc', safe: :safe
 ----
 
-|See xref:cli:cli.adoc[] to learn more about this interface.
-|See xref:api:overview.adoc[] to learn more about this interface.
+|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
@@ -87,7 +87,7 @@ Building atop AsciidoctorJ, there are also plugins that integrate Asciidoctor in
 
 === JavaScript
 
-Thanks to xref:asciidoctorjs::index.adoc[Asciidoctor.js], Asciidoctor can also be used in 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.
diff --git a/docs/asciidoctor/modules/ROOT/pages/language-support.adoc b/docs/modules/ROOT/pages/language-support.adoc
index 4af521ff..4af521ff 100644
--- a/docs/asciidoctor/modules/ROOT/pages/language-support.adoc
+++ b/docs/modules/ROOT/pages/language-support.adoc
diff --git a/docs/asciidoctor/modules/ROOT/pages/safe-modes.adoc b/docs/modules/ROOT/pages/safe-modes.adoc
index 78844585..3e06f836 100644
--- a/docs/asciidoctor/modules/ROOT/pages/safe-modes.adoc
+++ b/docs/modules/ROOT/pages/safe-modes.adoc
@@ -1,9 +1,9 @@
-= Security Modes
+= 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 modes
+== Safe mode levels
 
 `UNSAFE`::
 A safe mode level that disables any security features enforced by Asciidoctor.
diff --git a/docs/asciidoctor/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc
index 5d643834..2ca77a17 100644
--- a/docs/asciidoctor/modules/ROOT/pages/whats-new.adoc
+++ b/docs/modules/ROOT/pages/whats-new.adoc
@@ -1,5 +1,7 @@
-= What's New in Asciidoctor {page-component-version}
+//= 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:
 
diff --git a/docs/asciidoctor/modules/api/nav.adoc b/docs/modules/api/nav.adoc
index fc672bfd..25a3a937 100644
--- a/docs/asciidoctor/modules/api/nav.adoc
+++ b/docs/modules/api/nav.adoc
@@ -1,6 +1,6 @@
-* xref:overview.adoc[]
+* xref:index.adoc[]
 ** xref:convert-strings.adoc[]
 ** xref:generate-html-toc.adoc[]
 ** xref:load-templates.adoc[]
 ** xref:set-safe-mode.adoc[]
-** xref:api-options.adoc[]
+** xref:options.adoc[]
diff --git a/docs/asciidoctor/modules/api/pages/convert-strings.adoc b/docs/modules/api/pages/convert-strings.adoc
index 1f4a102a..1f4a102a 100644
--- a/docs/asciidoctor/modules/api/pages/convert-strings.adoc
+++ b/docs/modules/api/pages/convert-strings.adoc
diff --git a/docs/asciidoctor/modules/api/pages/generate-html-toc.adoc b/docs/modules/api/pages/generate-html-toc.adoc
index c53a538b..c53a538b 100644
--- a/docs/asciidoctor/modules/api/pages/generate-html-toc.adoc
+++ b/docs/modules/api/pages/generate-html-toc.adoc
diff --git a/docs/asciidoctor/modules/api/pages/overview.adoc b/docs/modules/api/pages/index.adoc
index 5c909faa..5c909faa 100644
--- a/docs/asciidoctor/modules/api/pages/overview.adoc
+++ b/docs/modules/api/pages/index.adoc
diff --git a/docs/asciidoctor/modules/api/pages/load-templates.adoc b/docs/modules/api/pages/load-templates.adoc
index 487ecd57..487ecd57 100644
--- a/docs/asciidoctor/modules/api/pages/load-templates.adoc
+++ b/docs/modules/api/pages/load-templates.adoc
diff --git a/docs/asciidoctor/modules/api/pages/api-options.adoc b/docs/modules/api/pages/options.adoc
index e0674494..5a498567 100644
--- a/docs/asciidoctor/modules/api/pages/api-options.adoc
+++ b/docs/modules/api/pages/options.adoc
@@ -1,4 +1,4 @@
-= Ruby API Options
+= API Options
 
 [cols="15m,15,15,15,15"]
 |===
diff --git a/docs/asciidoctor/modules/api/pages/set-safe-mode.adoc b/docs/modules/api/pages/set-safe-mode.adoc
index dcf13af6..dcf13af6 100644
--- a/docs/asciidoctor/modules/api/pages/set-safe-mode.adoc
+++ b/docs/modules/api/pages/set-safe-mode.adoc
diff --git a/docs/asciidoctor/modules/cli/nav.adoc b/docs/modules/cli/nav.adoc
index 31b30411..4e7bdbf9 100644
--- a/docs/asciidoctor/modules/cli/nav.adoc
+++ b/docs/modules/cli/nav.adoc
@@ -1,6 +1,6 @@
-* xref:cli.adoc[Process AsciiDoc Using the CLI]
+* xref:index.adoc[]
 ** xref:output-file.adoc[]
-** xref:io-piping.adoc[]
 ** xref:process-multiple-files.adoc[]
+** xref:io-piping.adoc[]
 ** xref:set-safe-mode.adoc[]
-** xref:cli-options-and-parameters.adoc[]
+** xref:options.adoc[]
diff --git a/docs/asciidoctor/modules/cli/pages/cli.adoc b/docs/modules/cli/pages/index.adoc
index 19cb82b8..6451af8c 100644
--- a/docs/asciidoctor/modules/cli/pages/cli.adoc
+++ b/docs/modules/cli/pages/index.adoc
@@ -1,5 +1,6 @@
-= Command Line Interface Basics
-:url-manpage: {url-project}/man/asciidoctor
+= 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
@@ -13,15 +14,16 @@ To confirm that Asciidoctor is available, execute:
 
 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>
+ $ 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:cli-options-and-parameters.adoc[] describes the available Asciidoctor CLI options and parameters.
+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:
 
diff --git a/docs/asciidoctor/modules/cli/pages/io-piping.adoc b/docs/modules/cli/pages/io-piping.adoc
index 686006dc..9b9eb5ce 100644
--- a/docs/asciidoctor/modules/cli/pages/io-piping.adoc
+++ b/docs/modules/cli/pages/io-piping.adoc
@@ -1,4 +1,4 @@
-= Piping Content Through the CLI
+= 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.
diff --git a/docs/asciidoctor/modules/cli/pages/cli-options-and-parameters.adoc b/docs/modules/cli/pages/options.adoc
index 980b2f8c..4c4a2236 100644
--- a/docs/asciidoctor/modules/cli/pages/cli-options-and-parameters.adoc
+++ b/docs/modules/cli/pages/options.adoc
@@ -1,4 +1,4 @@
-= CLI Options and Parameters
+= CLI Options
 // um anchor: appendix#cli-options
 // DO NOT EDIT THIS FILE
 // Copy the content from asciidoctor/man/asciidoctor.adoc
diff --git a/docs/asciidoctor/modules/cli/pages/output-file.adoc b/docs/modules/cli/pages/output-file.adoc
index 5867a201..5867a201 100644
--- a/docs/asciidoctor/modules/cli/pages/output-file.adoc
+++ b/docs/modules/cli/pages/output-file.adoc
diff --git a/docs/asciidoctor/modules/cli/pages/process-multiple-files.adoc b/docs/modules/cli/pages/process-multiple-files.adoc
index 777ef853..0d565b77 100644
--- a/docs/asciidoctor/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: If you process multiple nested AsciiDoc files at once and applying a custom stylesheet, you'll need to xref:backends:html/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:apply-stylesheet.adoc#style-nested[manage the stylesheet's location].
diff --git a/docs/asciidoctor/modules/cli/pages/set-safe-mode.adoc b/docs/modules/cli/pages/set-safe-mode.adoc
index b3450397..31110060 100644
--- a/docs/asciidoctor/modules/cli/pages/set-safe-mode.adoc
+++ b/docs/modules/cli/pages/set-safe-mode.adoc
@@ -1,4 +1,5 @@
 = 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:
diff --git a/docs/asciidoctor/modules/tooling/nav.adoc b/docs/modules/docbook-backend/nav.adoc
index 31f850ee..31f850ee 100644
--- a/docs/asciidoctor/modules/tooling/nav.adoc
+++ b/docs/modules/docbook-backend/nav.adoc
diff --git a/docs/asciidoctor/modules/backends/pages/docbook/convert-to-docbook.adoc b/docs/modules/docbook-backend/pages/index.adoc
index eb9dd15a..c6ef9962 100644
--- a/docs/asciidoctor/modules/backends/pages/docbook/convert-to-docbook.adoc
+++ b/docs/modules/docbook-backend/pages/index.adoc
@@ -1,10 +1,14 @@
-= Convert AsciiDoc to DocBook
+= 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.
-//Since the AsciiDoc syntax was designed with DocBook output in mind, the conversion is very good.
-//There's a corresponding DocBook element for each AsciiDoc element.
+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`.
 
diff --git a/docs/asciidoctor/modules/extensions/nav.adoc b/docs/modules/extensions/nav.adoc
index e0e67a46..e209f801 100644
--- a/docs/asciidoctor/modules/extensions/nav.adoc
+++ b/docs/modules/extensions/nav.adoc
@@ -1,4 +1,5 @@
-* xref:register.adoc[Extensions]
+* xref:index.adoc[]
+** xref:register.adoc[]
 ** xref:preprocessor.adoc[]
 ** xref:tree-processor.adoc[]
 ** xref:postprocessor.adoc[]
diff --git a/docs/asciidoctor/modules/extensions/pages/block-macro-processor.adoc b/docs/modules/extensions/pages/block-macro-processor.adoc
index df451c43..df451c43 100644
--- a/docs/asciidoctor/modules/extensions/pages/block-macro-processor.adoc
+++ b/docs/modules/extensions/pages/block-macro-processor.adoc
diff --git a/docs/asciidoctor/modules/extensions/pages/block-processor.adoc b/docs/modules/extensions/pages/block-processor.adoc
index d228642e..d228642e 100644
--- a/docs/asciidoctor/modules/extensions/pages/block-processor.adoc
+++ b/docs/modules/extensions/pages/block-processor.adoc
diff --git a/docs/asciidoctor/modules/extensions/pages/compound-block-processor.adoc b/docs/modules/extensions/pages/compound-block-processor.adoc
index 32dea0e4..32dea0e4 100644
--- a/docs/asciidoctor/modules/extensions/pages/compound-block-processor.adoc
+++ b/docs/modules/extensions/pages/compound-block-processor.adoc
diff --git a/docs/asciidoctor/modules/extensions/pages/docinfo-processor.adoc b/docs/modules/extensions/pages/docinfo-processor.adoc
index d5510c1a..d5510c1a 100644
--- a/docs/asciidoctor/modules/extensions/pages/docinfo-processor.adoc
+++ b/docs/modules/extensions/pages/docinfo-processor.adoc
diff --git a/docs/asciidoctor/modules/extensions/pages/include-processor.adoc b/docs/modules/extensions/pages/include-processor.adoc
index 8dbdd8e0..8dbdd8e0 100644
--- a/docs/asciidoctor/modules/extensions/pages/include-processor.adoc
+++ b/docs/modules/extensions/pages/include-processor.adoc
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/asciidoctor/modules/extensions/pages/inline-macro-processor.adoc b/docs/modules/extensions/pages/inline-macro-processor.adoc
index b8d88b0e..b8d88b0e 100644
--- a/docs/asciidoctor/modules/extensions/pages/inline-macro-processor.adoc
+++ b/docs/modules/extensions/pages/inline-macro-processor.adoc
diff --git a/docs/asciidoctor/modules/extensions/pages/postprocessor.adoc b/docs/modules/extensions/pages/postprocessor.adoc
index 712706ea..712706ea 100644
--- a/docs/asciidoctor/modules/extensions/pages/postprocessor.adoc
+++ b/docs/modules/extensions/pages/postprocessor.adoc
diff --git a/docs/asciidoctor/modules/extensions/pages/preprocessor.adoc b/docs/modules/extensions/pages/preprocessor.adoc
index c1e5a406..c1e5a406 100644
--- a/docs/asciidoctor/modules/extensions/pages/preprocessor.adoc
+++ b/docs/modules/extensions/pages/preprocessor.adoc
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/asciidoctor/modules/extensions/pages/tree-processor.adoc b/docs/modules/extensions/pages/tree-processor.adoc
index 050737ed..050737ed 100644
--- a/docs/asciidoctor/modules/extensions/pages/tree-processor.adoc
+++ b/docs/modules/extensions/pages/tree-processor.adoc
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/asciidoctor/modules/ROOT/pages/convert-asciidoc-file.adoc b/docs/modules/get-started/pages/index.adoc
index 89b0bee1..89b0bee1 100644
--- a/docs/asciidoctor/modules/ROOT/pages/convert-asciidoc-file.adoc
+++ b/docs/modules/get-started/pages/index.adoc
diff --git a/docs/asciidoctor/modules/backends/examples/mysample-data-uri.adoc b/docs/modules/html-backend/examples/mysample-data-uri.adoc
index ec32d03e..ec32d03e 100644
--- a/docs/asciidoctor/modules/backends/examples/mysample-data-uri.adoc
+++ b/docs/modules/html-backend/examples/mysample-data-uri.adoc
diff --git a/docs/asciidoctor/modules/backends/examples/mysample-link.adoc b/docs/modules/html-backend/examples/mysample-link.adoc
index e24aeea9..e24aeea9 100644
--- a/docs/asciidoctor/modules/backends/examples/mysample-link.adoc
+++ b/docs/modules/html-backend/examples/mysample-link.adoc
diff --git a/docs/asciidoctor/modules/backends/examples/mysample-stylesdir-link.adoc b/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc
index bb56b9e2..bb56b9e2 100644
--- a/docs/asciidoctor/modules/backends/examples/mysample-stylesdir-link.adoc
+++ b/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc
diff --git a/docs/asciidoctor/modules/backends/examples/mysample-stylesdir.adoc b/docs/modules/html-backend/examples/mysample-stylesdir.adoc
index 452e7f5c..452e7f5c 100644
--- a/docs/asciidoctor/modules/backends/examples/mysample-stylesdir.adoc
+++ b/docs/modules/html-backend/examples/mysample-stylesdir.adoc
diff --git a/docs/asciidoctor/modules/backends/examples/mysample-stylesheet.adoc b/docs/modules/html-backend/examples/mysample-stylesheet.adoc
index b1cc475c..b1cc475c 100644
--- a/docs/asciidoctor/modules/backends/examples/mysample-stylesheet.adoc
+++ b/docs/modules/html-backend/examples/mysample-stylesheet.adoc
diff --git a/docs/asciidoctor/modules/backends/examples/mysample.adoc b/docs/modules/html-backend/examples/mysample.adoc
index 0a00ca64..0a00ca64 100644
--- a/docs/asciidoctor/modules/backends/examples/mysample.adoc
+++ b/docs/modules/html-backend/examples/mysample.adoc
diff --git a/docs/asciidoctor/modules/backends/examples/wrap.adoc b/docs/modules/html-backend/examples/wrap.adoc
index 3f877d7d..3f877d7d 100644
--- a/docs/asciidoctor/modules/backends/examples/wrap.adoc
+++ b/docs/modules/html-backend/examples/wrap.adoc
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/asciidoctor/modules/backends/pages/html/apply-code-stylesheets.adoc b/docs/modules/html-backend/pages/apply-code-stylesheets.adoc
index 42be39cb..42be39cb 100644
--- a/docs/asciidoctor/modules/backends/pages/html/apply-code-stylesheets.adoc
+++ b/docs/modules/html-backend/pages/apply-code-stylesheets.adoc
diff --git a/docs/asciidoctor/modules/backends/pages/html/apply-stylesheet.adoc b/docs/modules/html-backend/pages/apply-stylesheet.adoc
index e645e664..e645e664 100644
--- a/docs/asciidoctor/modules/backends/pages/html/apply-stylesheet.adoc
+++ b/docs/modules/html-backend/pages/apply-stylesheet.adoc
diff --git a/docs/asciidoctor/modules/backends/pages/html/favicon.adoc b/docs/modules/html-backend/pages/favicon.adoc
index 34a8f15d..34a8f15d 100644
--- a/docs/asciidoctor/modules/backends/pages/html/favicon.adoc
+++ b/docs/modules/html-backend/pages/favicon.adoc
diff --git a/docs/asciidoctor/modules/backends/pages/html/convert-to-html.adoc b/docs/modules/html-backend/pages/index.adoc
index dedeb29d..5c562bdb 100644
--- a/docs/asciidoctor/modules/backends/pages/html/convert-to-html.adoc
+++ b/docs/modules/html-backend/pages/index.adoc
@@ -1,11 +1,14 @@
 = Generate HTML from AsciiDoc
+:navtitle: Generate HTML
 
-== Convert AsciiDoc to 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
@@ -48,7 +51,7 @@ The document's text, titles, and link is styled by the default Asciidoctor style
 As a result, you could save [.path]_my-sample.html_ to any computer and it will look the same.
 
 [#xhtml]
-== Convert AsciiDoc to XHTML
+== Generate XHTML
 
 To convert AsciiDoc to XHTML, set the backend to `xhtml5`.
 
diff --git a/docs/asciidoctor/modules/backends/pages/html/manage-images.adoc b/docs/modules/html-backend/pages/manage-images.adoc
index 38b69aae..38b69aae 100644
--- a/docs/asciidoctor/modules/backends/pages/html/manage-images.adoc
+++ b/docs/modules/html-backend/pages/manage-images.adoc
diff --git a/docs/asciidoctor/modules/backends/pages/html/manage-stylesheets.adoc b/docs/modules/html-backend/pages/manage-stylesheets.adoc
index cb3c64cb..aa6042b3 100644
--- a/docs/asciidoctor/modules/backends/pages/html/manage-stylesheets.adoc
+++ b/docs/modules/html-backend/pages/manage-stylesheets.adoc
@@ -1,7 +1,11 @@
 = 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
 
@@ -39,4 +43,4 @@ If you don't want any styles applied to the HTML output of your document, unset
 
  $ 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:html/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:apply-stylesheet.adoc[custom stylesheet].
diff --git a/docs/asciidoctor/modules/backends/pages/html/front-matter.adoc b/docs/modules/html-backend/pages/skip-front-matter.adoc
index f3e2b285..0eb065d5 100644
--- a/docs/asciidoctor/modules/backends/pages/html/front-matter.adoc
+++ b/docs/modules/html-backend/pages/skip-front-matter.adoc
@@ -1,6 +1,5 @@
-= Front Matter
+= Skip Front Matter
 
-[#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.
@@ -24,7 +23,8 @@ content
 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.
 
-// (as of 0.1.4)
-If the `skip-front-matter` attribute 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.
+== 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/asciidoctor/modules/backends/pages/html/wrap.adoc b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc
index f0391186..f38b7daa 100644
--- a/docs/asciidoctor/modules/backends/pages/html/wrap.adoc
+++ b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc
@@ -1,11 +1,13 @@
-= Wrap or Scroll
+= Verbatim Block Line Wrapping
 
-The default Asciidoctor stylesheet wraps long lines in listing and literal blocks by applying the CSS `white-space: pre-wrap` and `word-wrap: break-word`.
+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
diff --git a/docs/asciidoctor/modules/install/nav.adoc b/docs/modules/install/nav.adoc
index c2e389a1..afd431e0 100644
--- a/docs/asciidoctor/modules/install/nav.adoc
+++ b/docs/modules/install/nav.adoc
@@ -1,8 +1,6 @@
-* xref:install.adoc[]
+* xref:index.adoc[]
 ** xref:supported-platforms.adoc[]
 ** xref:gem.adoc[]
 ** xref:linux.adoc[]
 ** xref:macos.adoc[]
 ** xref:windows.adoc[]
-** xref:upgrade-requirements.adoc[]
-** xref:upgrade.adoc[]
diff --git a/docs/asciidoctor/modules/install/pages/gem.adoc b/docs/modules/install/pages/gem.adoc
index 28d1315b..af8b116f 100644
--- a/docs/asciidoctor/modules/install/pages/gem.adoc
+++ b/docs/modules/install/pages/gem.adoc
@@ -40,3 +40,28 @@ 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.
+
+== 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/asciidoctor/modules/install/pages/linux.adoc b/docs/modules/install/pages/linux.adoc
index 45f53039..a2b605f6 100644
--- a/docs/asciidoctor/modules/install/pages/linux.adoc
+++ b/docs/modules/install/pages/linux.adoc
@@ -55,3 +55,30 @@ 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/asciidoctor/modules/install/pages/macos.adoc b/docs/modules/install/pages/macos.adoc
index 3a455995..25a71919 100644
--- a/docs/asciidoctor/modules/install/pages/macos.adoc
+++ b/docs/modules/install/pages/macos.adoc
@@ -1,6 +1,8 @@
-= Install Asciidoctor on macOS
+= 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.
 
@@ -12,3 +14,10 @@ Open a terminal and type:
 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/asciidoctor/modules/install/pages/supported-platforms.adoc b/docs/modules/install/pages/supported-platforms.adoc
index 789a01d4..789a01d4 100644
--- a/docs/asciidoctor/modules/install/pages/supported-platforms.adoc
+++ b/docs/modules/install/pages/supported-platforms.adoc
diff --git a/docs/asciidoctor/modules/install/pages/windows.adoc b/docs/modules/install/pages/windows.adoc
index 638aff8d..ae25d23e 100644
--- a/docs/asciidoctor/modules/install/pages/windows.adoc
+++ b/docs/modules/install/pages/windows.adoc
@@ -1,4 +1,4 @@
-= Install Asciidoctor on Windows
+= Install on Windows
 
 To install Asciidoctor on Windows, you can use Chocolatey or Rubyinstaller.
 
diff --git a/docs/asciidoctor/modules/install/partials/success.adoc b/docs/modules/install/partials/success.adoc
index 228d2d75..8ad68700 100644
--- a/docs/asciidoctor/modules/install/partials/success.adoc
+++ b/docs/modules/install/partials/success.adoc
@@ -1,4 +1,4 @@
-If the gem installed successfully, its xref:cli:cli.adoc[command line interface (CLI)] will be available on your PATH.
+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
diff --git a/docs/asciidoctor/modules/integrations/nav.adoc b/docs/modules/integrations/nav.adoc
index b6d8da60..b6d8da60 100644
--- a/docs/asciidoctor/modules/integrations/nav.adoc
+++ b/docs/modules/integrations/nav.adoc
diff --git a/docs/asciidoctor/modules/integrations/pages/asciimath-gem.adoc b/docs/modules/integrations/pages/asciimath-gem.adoc
index 5d9e82d7..5d9e82d7 100644
--- a/docs/asciidoctor/modules/integrations/pages/asciimath-gem.adoc
+++ b/docs/modules/integrations/pages/asciimath-gem.adoc
diff --git a/docs/asciidoctor/modules/integrations/pages/coderay.adoc b/docs/modules/integrations/pages/coderay.adoc
index fdc97bc0..7a590b8a 100644
--- a/docs/asciidoctor/modules/integrations/pages/coderay.adoc
+++ b/docs/modules/integrations/pages/coderay.adoc
@@ -100,7 +100,7 @@ ORDERED_LIST_KEYWORDS = {
 ----
 ....
 
-See the xref:backends:html/apply-code-stylesheets.adoc#coderay[CodeRay stylesheet section] to learn about the `coderay-css` attribute.
+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/asciidoctor/modules/integrations/pages/highlightjs.adoc b/docs/modules/integrations/pages/highlightjs.adoc
index 17372031..17372031 100644
--- a/docs/asciidoctor/modules/integrations/pages/highlightjs.adoc
+++ b/docs/modules/integrations/pages/highlightjs.adoc
diff --git a/docs/asciidoctor/modules/integrations/pages/mathjax.adoc b/docs/modules/integrations/pages/mathjax.adoc
index b27c7928..b27c7928 100644
--- a/docs/asciidoctor/modules/integrations/pages/mathjax.adoc
+++ b/docs/modules/integrations/pages/mathjax.adoc
diff --git a/docs/asciidoctor/modules/integrations/pages/pygments.adoc b/docs/modules/integrations/pages/pygments.adoc
index 68785da0..9456955b 100644
--- a/docs/asciidoctor/modules/integrations/pages/pygments.adoc
+++ b/docs/modules/integrations/pages/pygments.adoc
@@ -49,7 +49,7 @@ 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:backends:html/apply-code-stylesheets.adoc#pygments[Pygments stylesheet section] to learn more about how the value `class` is handled.
+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::
diff --git a/docs/asciidoctor/modules/integrations/pages/rouge.adoc b/docs/modules/integrations/pages/rouge.adoc
index b6022864..b6022864 100644
--- a/docs/asciidoctor/modules/integrations/pages/rouge.adoc
+++ b/docs/modules/integrations/pages/rouge.adoc
diff --git a/docs/asciidoctor/modules/integrations/pages/stem.adoc b/docs/modules/integrations/pages/stem.adoc
index 809dfa16..809dfa16 100644
--- a/docs/asciidoctor/modules/integrations/pages/stem.adoc
+++ b/docs/modules/integrations/pages/stem.adoc
diff --git a/docs/asciidoctor/modules/integrations/pages/syntax-highlighters.adoc b/docs/modules/integrations/pages/syntax-highlighters.adoc
index a8354393..a8354393 100644
--- a/docs/asciidoctor/modules/integrations/pages/syntax-highlighters.adoc
+++ b/docs/modules/integrations/pages/syntax-highlighters.adoc
diff --git a/docs/asciidoctor/modules/backends/examples/manpage.adoc b/docs/modules/manpage-backend/examples/manpage.adoc
index c865d610..c865d610 100644
--- a/docs/asciidoctor/modules/backends/examples/manpage.adoc
+++ b/docs/modules/manpage-backend/examples/manpage.adoc
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/asciidoctor/modules/backends/pages/manpage/convert-to-man-page.adoc b/docs/modules/manpage-backend/pages/index.adoc
index e6fbe4bd..31386990 100644
--- a/docs/asciidoctor/modules/backends/pages/manpage/convert-to-man-page.adoc
+++ b/docs/modules/manpage-backend/pages/index.adoc
@@ -1,11 +1,14 @@
-= Convert AsciiDoc to Man Pages
+= 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 man page?
+== 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.
diff --git a/docs/asciidoctor/modules/migrate/examples/convert.groovy b/docs/modules/migrate/examples/convert.groovy
index 6dba705c..6dba705c 100644
--- a/docs/asciidoctor/modules/migrate/examples/convert.groovy
+++ b/docs/modules/migrate/examples/convert.groovy
diff --git a/docs/asciidoctor/modules/migrate/nav.adoc b/docs/modules/migrate/nav.adoc
index 9c624d30..6df6ade3 100644
--- a/docs/asciidoctor/modules/migrate/nav.adoc
+++ b/docs/modules/migrate/nav.adoc
@@ -1,4 +1,5 @@
 * Migration Guides
+** xref:upgrade.adoc[]
 ** xref:asciidoc-python.adoc[]
 ** xref:docbook-xml.adoc[]
 ** xref:markdown.adoc[]
diff --git a/docs/asciidoctor/modules/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc
index c18e26c4..c18e26c4 100644
--- a/docs/asciidoctor/modules/migrate/pages/asciidoc-python.adoc
+++ b/docs/modules/migrate/pages/asciidoc-python.adoc
diff --git a/docs/asciidoctor/modules/migrate/pages/confluence-xhtml.adoc b/docs/modules/migrate/pages/confluence-xhtml.adoc
index 744cf0f1..744cf0f1 100644
--- a/docs/asciidoctor/modules/migrate/pages/confluence-xhtml.adoc
+++ b/docs/modules/migrate/pages/confluence-xhtml.adoc
diff --git a/docs/asciidoctor/modules/migrate/pages/docbook-xml.adoc b/docs/modules/migrate/pages/docbook-xml.adoc
index 06cb5a96..06cb5a96 100644
--- a/docs/asciidoctor/modules/migrate/pages/docbook-xml.adoc
+++ b/docs/modules/migrate/pages/docbook-xml.adoc
diff --git a/docs/asciidoctor/modules/migrate/pages/markdown.adoc b/docs/modules/migrate/pages/markdown.adoc
index eab57dc3..eab57dc3 100644
--- a/docs/asciidoctor/modules/migrate/pages/markdown.adoc
+++ b/docs/modules/migrate/pages/markdown.adoc
diff --git a/docs/asciidoctor/modules/migrate/pages/ms-word.adoc b/docs/modules/migrate/pages/ms-word.adoc
index aea595c6..aea595c6 100644
--- a/docs/asciidoctor/modules/migrate/pages/ms-word.adoc
+++ b/docs/modules/migrate/pages/ms-word.adoc
diff --git a/docs/asciidoctor/modules/install/pages/upgrade-requirements.adoc b/docs/modules/migrate/pages/upgrade.adoc
index 7019bd3d..9ad2d9fa 100644
--- a/docs/asciidoctor/modules/install/pages/upgrade-requirements.adoc
+++ b/docs/modules/migrate/pages/upgrade.adoc
@@ -1,8 +1,8 @@
-= Before You Upgrade
+= 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:migrate:asciidoc-python.adoc[].
+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.
@@ -106,7 +106,7 @@ If you want to use the new Asciidoctor syntax, make sure to use `= Title` or exp
 
 == New features
 
-Visit xref:ROOT:whats-new.adoc[] for a complete list of new Asciidoctor and AsciiDoc features.
+Visit xref:ROOT:whats-new.adoc[] for a complete list of new Asciidoctor features.
 
 ////
 == Proposed changes for future versions
@@ -156,16 +156,3 @@ When it isn't feasibly to update your documents prior to upgrading Asciidoctor,
 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*.
 ////
-
-////
-== Next
-
-xref:upgrade.adoc#upgrade-on-linux[Upgrade on Linux]::
-Upgrade Asciidoctor using the package manager on many Linux distributions including Fedora, RHEL, Debian, Ubuntu, and Alpine Linux.
-
-xref:upgrade.adoc#upgrade-on-macos[Upgrade on macOS]::
-Upgrade Asciidoctor using Homebrew on macOS.
-
-xref:upgrade.adoc#gem-update[Upgrade using gem update]::
-Upgrade Asciidoctor using the `gem update` command.
-////
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/asciidoctor/modules/tooling/pages/index.adoc b/docs/modules/tooling/pages/index.adoc
index 2b573a82..2b573a82 100644
--- a/docs/asciidoctor/modules/tooling/pages/index.adoc
+++ b/docs/modules/tooling/pages/index.adoc