merge PR #3880

resolves #3861 import Asciidoctor docs from asciidoctor.org/docs

17 files changed, 819 insertions, 0 deletions

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/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/images/default-stylesheet.png b/docs/modules/html-backend/images/default-stylesheet.png
new file mode 100644
index 00000000..4584a510
--- /dev/null
+++ b/docs/modules/html-backend/images/default-stylesheet.png
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
--- /dev/null
+++ b/docs/modules/html-backend/images/my-document-with-data-uri.png
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
--- /dev/null
+++ b/docs/modules/html-backend/images/my-document.png
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..ffe779b8
--- /dev/null
+++ b/docs/modules/html-backend/images/no-stylesheet.png
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
--- /dev/null
+++ b/docs/modules/html-backend/images/wolpertinger.jpg
diff --git a/docs/modules/html-backend/nav.adoc b/docs/modules/html-backend/nav.adoc
new file mode 100644
index 00000000..e887d6da
--- /dev/null
+++ b/docs/modules/html-backend/nav.adoc
@@ -0,0 +1,10 @@
+* xref:index.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[]
+** xref:skip-front-matter.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..18591039
--- /dev/null
+++ b/docs/modules/html-backend/pages/custom-stylesheet.adoc
@@ -0,0 +1,200 @@
+= 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:
+
+.stylesheet attribute set in document header
+[source,asciidoc]
+----
+include::example$my-document.adoc[tag=title]
+:stylesheet: my-stylesheet.css
+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 my-document.adoc
+
+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 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.
+
+== 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:
+
+.stylesdir attribute set in document header
+[source,asciidoc]
+----
+include::example$my-document.adoc[tag=title]
+:stylesheet: my-stylesheet.css
+:stylesdir: my-styles
+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 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 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.
+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 my-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 my-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 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.
+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,asciidoc]
+----
+:stylesdir: my-styles
+----
+
+For [.path]_c.adoc_, set `stylesdir` to:
+
+[source,asciidoc]
+----
+: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/default-stylesheet.adoc b/docs/modules/html-backend/pages/default-stylesheet.adoc
new file mode 100644
index 00000000..3b1616ad
--- /dev/null
+++ b/docs/modules/html-backend/pages/default-stylesheet.adoc
@@ -0,0 +1,176 @@
+= Default Stylesheet
+
+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.
+
+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.
+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 (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.
+
+[source,ruby]
+----
+require 'asciidoctor'
+
+Asciidoctor.convert_file 'document.adoc', safe: :safe
+----
+
+== 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.
+
+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 how to apply a custom stylesheet, see xref:custom-stylesheet.adoc[].
diff --git a/docs/modules/html-backend/pages/favicon.adoc b/docs/modules/html-backend/pages/favicon.adoc
new file mode 100644
index 00000000..a6400aff
--- /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 `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]
+----
+= 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..f3097f83
--- /dev/null
+++ b/docs/modules/html-backend/pages/index.adoc
@@ -0,0 +1,84 @@
+= Generate HTML from AsciiDoc
+:navtitle: Generate HTML
+
+== HTML 5 converter
+
+Asciidoctor's default output format is HTML.
+
+`html`:: The HTML 5 converter (`html` or `html5`) generates HTML 5 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 built-in HTML converter.
+
+=== Create and save an AsciiDoc document
+
+. 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$my-document.adoc[tags=title;body]
+----
+
+. Make sure to save the file with the _.adoc_ file extension.
+
+=== Convert an AsciiDoc document to HTML
+
+To convert [.path]_my-document.adoc_ to HTML from the command line:
+
+. 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.
+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-document.adoc  my-document.html
+
+Asciidoctor derives the name of the output document from the name of the input document.
+--
+
+. Open [.path]_my-document.html_ in your web browser.
+Your document should look like the image below.
++
+--
+image::my-document.png[]
+
+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
+
+`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 xhtml5 backend option
+ $ 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
+ $ asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml my-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..94323a93
--- /dev/null
+++ b/docs/modules/html-backend/pages/manage-images.adoc
@@ -0,0 +1,33 @@
+= 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.
+
+== Embed images with the data-uri attribute
+
+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$my-document.adoc[tag=title]
+:imagesdir: my-images
+:data-uri:
+include::example$my-document.adoc[tags=body;image]
+----
+
+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-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/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/source-highlighting-stylesheets.adoc b/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc
new file mode 100644
index 00000000..447595ad
--- /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: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]
+== 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/stylesheet-modes.adoc b/docs/modules/html-backend/pages/stylesheet-modes.adoc
new file mode 100644
index 00000000..5379ed38
--- /dev/null
+++ b/docs/modules/html-backend/pages/stylesheet-modes.adoc
@@ -0,0 +1,135 @@
+= 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:
+
+.linkcss attribute set in document header
+[source,asciidoc]
+----
+include::example$my-document.adoc[tag=title]
+:linkcss:
+include::example$my-document.adoc[tag=body]
+----
+
+You can also set `linkcss` using the API or CLI (shown here):
+
+ $ asciidoctor -a linkcss my-document.adoc
+
+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">
+----
+
+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 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.
+****
+
+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 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
+
+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:
+
+.copycss attribute unset in document header
+[source,asciidoc]
+----
+include::example$my-document.adoc[tag=title]
+:linkcss:
+:!copycss:
+include::example$my-document.adoc[tag=body]
+----
+
+You can also unset `copycss` using the API or CLI (shown here):
+
+ $ 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).
+
+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` attribute using the CLI.
+
+ $ 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]_my-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.
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..a032a193
--- /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,asciidoc]
+----
+: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.