From c3c7ddbda681cc8f44832b0549bb623d3eace748 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Wed, 18 Nov 2020 15:53:10 -0700 Subject: rearchitect modules and filenames and drop asciidoctor folder under docs --- .../html-backend/examples/mysample-data-uri.adoc | 17 ++++ .../html-backend/examples/mysample-link.adoc | 13 +++ .../examples/mysample-stylesdir-link.adoc | 15 ++++ .../html-backend/examples/mysample-stylesdir.adoc | 14 ++++ .../html-backend/examples/mysample-stylesheet.adoc | 13 +++ docs/modules/html-backend/examples/mysample.adoc | 12 +++ docs/modules/html-backend/examples/wrap.adoc | 17 ++++ docs/modules/html-backend/nav.adoc | 9 ++ .../html-backend/pages/apply-code-stylesheets.adoc | 27 ++++++ .../html-backend/pages/apply-stylesheet.adoc | 97 ++++++++++++++++++++++ docs/modules/html-backend/pages/favicon.adoc | 48 +++++++++++ docs/modules/html-backend/pages/index.adoc | 81 ++++++++++++++++++ docs/modules/html-backend/pages/manage-images.adoc | 24 ++++++ .../html-backend/pages/manage-stylesheets.adoc | 46 ++++++++++ .../html-backend/pages/skip-front-matter.adoc | 30 +++++++ .../html-backend/pages/verbatim-line-wrap.adoc | 40 +++++++++ 16 files changed, 503 insertions(+) create mode 100644 docs/modules/html-backend/examples/mysample-data-uri.adoc create mode 100644 docs/modules/html-backend/examples/mysample-link.adoc create mode 100644 docs/modules/html-backend/examples/mysample-stylesdir-link.adoc create mode 100644 docs/modules/html-backend/examples/mysample-stylesdir.adoc create mode 100644 docs/modules/html-backend/examples/mysample-stylesheet.adoc create mode 100644 docs/modules/html-backend/examples/mysample.adoc create mode 100644 docs/modules/html-backend/examples/wrap.adoc create mode 100644 docs/modules/html-backend/nav.adoc create mode 100644 docs/modules/html-backend/pages/apply-code-stylesheets.adoc create mode 100644 docs/modules/html-backend/pages/apply-stylesheet.adoc create mode 100644 docs/modules/html-backend/pages/favicon.adoc create mode 100644 docs/modules/html-backend/pages/index.adoc create mode 100644 docs/modules/html-backend/pages/manage-images.adoc create mode 100644 docs/modules/html-backend/pages/manage-stylesheets.adoc create mode 100644 docs/modules/html-backend/pages/skip-front-matter.adoc create mode 100644 docs/modules/html-backend/pages/verbatim-line-wrap.adoc (limited to 'docs/modules/html-backend') diff --git a/docs/modules/html-backend/examples/mysample-data-uri.adoc b/docs/modules/html-backend/examples/mysample-data-uri.adoc new file mode 100644 index 00000000..ec32d03e --- /dev/null +++ b/docs/modules/html-backend/examples/mysample-data-uri.adoc @@ -0,0 +1,17 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger +:imagesdir: myimages +:data-uri: + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +[.left.text-center] +image::wolpertinger.jpg[Wolpertinger] + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/mysample-link.adoc b/docs/modules/html-backend/examples/mysample-link.adoc new file mode 100644 index 00000000..e24aeea9 --- /dev/null +++ b/docs/modules/html-backend/examples/mysample-link.adoc @@ -0,0 +1,13 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger +:linkcss: + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc b/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc new file mode 100644 index 00000000..bb56b9e2 --- /dev/null +++ b/docs/modules/html-backend/examples/mysample-stylesdir-link.adoc @@ -0,0 +1,15 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger +:stylesdir: mystylesheets/ +:stylesheet: mystyles.css +:linkcss: + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/mysample-stylesdir.adoc b/docs/modules/html-backend/examples/mysample-stylesdir.adoc new file mode 100644 index 00000000..452e7f5c --- /dev/null +++ b/docs/modules/html-backend/examples/mysample-stylesdir.adoc @@ -0,0 +1,14 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger +:stylesdir: mystylesheets/ +:stylesheet: mystyles.css + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/mysample-stylesheet.adoc b/docs/modules/html-backend/examples/mysample-stylesheet.adoc new file mode 100644 index 00000000..b1cc475c --- /dev/null +++ b/docs/modules/html-backend/examples/mysample-stylesheet.adoc @@ -0,0 +1,13 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger +:stylesheet: mystyles.css + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/mysample.adoc b/docs/modules/html-backend/examples/mysample.adoc new file mode 100644 index 00000000..0a00ca64 --- /dev/null +++ b/docs/modules/html-backend/examples/mysample.adoc @@ -0,0 +1,12 @@ += My First Experience with the Dangers of Documentation +:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger + +In my world, we don't have to worry about mutant, script-injecting warlocks. +No. +We have something far worse. +We're plagued by Wolpertingers. + +== Origins + +You may not be familiar with these {url-wolpertinger}[ravenous beasts], +but, trust me, they'll eat your shorts and suck the loops from your code. diff --git a/docs/modules/html-backend/examples/wrap.adoc b/docs/modules/html-backend/examples/wrap.adoc new file mode 100644 index 00000000..3f877d7d --- /dev/null +++ b/docs/modules/html-backend/examples/wrap.adoc @@ -0,0 +1,17 @@ +// tag::nowrap[] +[source%nowrap,java] +---- +public class ApplicationConfigurationProvider extends HttpConfigurationProvider +{ + @Override + public Configuration getConfiguration(ServletContext context) + { + return ConfigurationBuilder.begin() + .addRule() + .when(Direction.isInbound().and(Path.matches("/{path}"))) + .perform(Log.message(Level.INFO, "Client requested path: {path}")) + .where("path").matches(".*"); + } +} +---- +// end::nowrap[] diff --git a/docs/modules/html-backend/nav.adoc b/docs/modules/html-backend/nav.adoc new file mode 100644 index 00000000..aa1054cb --- /dev/null +++ b/docs/modules/html-backend/nav.adoc @@ -0,0 +1,9 @@ +* xref:index.adoc[] +** xref:manage-stylesheets.adoc[] +** xref:apply-code-stylesheets.adoc[] +** xref:apply-stylesheet.adoc[] +** xref:favicon.adoc[] +** xref:manage-images.adoc[] +** xref:favicon.adoc[] +** xref:verbatim-line-wrap.adoc[] +** xref:skip-front-matter.adoc[] diff --git a/docs/modules/html-backend/pages/apply-code-stylesheets.adoc b/docs/modules/html-backend/pages/apply-code-stylesheets.adoc new file mode 100644 index 00000000..42be39cb --- /dev/null +++ b/docs/modules/html-backend/pages/apply-code-stylesheets.adoc @@ -0,0 +1,27 @@ += Apply CodeRay or Pygments Stylesheets +// um anchor: hl-css +// html-code-styles.adoc, included in convert-documents and the user-manual. + +Asciidoctor can embed the stylesheet for the CodeRay or Pygments syntax highlighters. + +== Requirements + +First, make sure the appropriate library is installed on your system. +See xref:integrations:rouge.adoc[], xref:integrations:coderay.adoc[], or xref:integrations:pygments.adoc[] for installation instructions. +Next, set the xref:asciidoc:verbatim:source-highlighter.adoc[source-highlighter attribute] and assign it the value that corresponds to the library you installed. + +[#coderay] +== CodeRay + +If the `source-highlighter` attribute is `coderay` and the `coderay-css` attribute is `class`, the CodeRay stylesheet is: + +* _embedded_ by default +* _copied_ to the file [.path]_asciidoctor-coderay.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set + +[#pygments] +== Pygments + +If the `source-highlighter` attribute is `pygments` and the `pygments-css` attribute is `class`, the Pygments stylesheet is: + +* _embedded_ by default +* _copied_ to the file [.path]_asciidoctor-pygments.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set diff --git a/docs/modules/html-backend/pages/apply-stylesheet.adoc b/docs/modules/html-backend/pages/apply-stylesheet.adoc new file mode 100644 index 00000000..e645e664 --- /dev/null +++ b/docs/modules/html-backend/pages/apply-stylesheet.adoc @@ -0,0 +1,97 @@ += Apply a Custom Stylesheet +//// +apply-theme.adoc, included in: +- user-manual +- produce-custom-themes-using-asciidoctor-stylesheet-factory +//// + +A custom stylesheet can be stored in the same directory as your document or in a separate directory. +Like the default stylesheet, you can have the output document link to your custom stylesheet or embed it. + +If the stylesheet is in the same directory as your document, you can apply it when converting your document to HTML from the CLI. + + $ asciidoctor -a stylesheet=my-styles.css my-sample.adoc + +. Save your custom stylesheet in the same directory as [.path]_my-sample.adoc_ +. Call the `asciidoctor` processor +. Set `-a` (`--attribute`) and `stylesheet` +. Assign the stylesheet file's name to the `stylesheet` attribute +. Enter your document file's name. + +Alternatively, let's set the `stylesheet` attribute in the header of [.path]_my-sample.adoc_. + +[source,asciidoc] +---- +include::example$mysample-stylesheet.adoc[] +---- + +==== +#fix ex# +//image::mysample-stylesheet.png[] +==== + +When your document and the stylesheet are stored in different directories, you need to tell Asciidoctor where to look for the stylesheet in relation to your document. +Asciidoctor uses the relative or absolute path you assign to the `stylesdir` attribute to find the stylesheet. +Let's move [.path]_my-styles.css_ into [.path]_my-documents/my-stylesheets_. +Our AsciiDoc document, [.path]_my-sample.adoc_, is saved in the [.path]_my-documents_ directory. + +[source,asciidoc] +---- +include::example$mysample-stylesdir.adoc[] +---- + +After processing [.path]_my-sample.adoc_, its HTML output ([.path]_my-sample.html_), which includes the embedded [.path]_my-styles.css_ stylesheet, is created in the [.path]_my-documents_ directory. + +==== +#fix ex# +//image::mysample-stylesdir-dir.png[] +==== + +You can also set `stylesdir` in the CLI. + + $ asciidoctor -a stylesdir=my-stylesheets/ -a stylesheet=my-styles.css my-sample.adoc + +If you don't want to embed the [.path]_my-styles.css_ stylesheet into your HTML output, make sure to set `linkcss`. + +[source,asciidoc] +---- +include::example$mysample-stylesdir-link.adoc[] +---- + +After your document is converted, notice that a copy of [.path]_my-styles.css_ was not created in the [.path]_my-documents_ directory. +Unlike when you link to the default Asciidoctor stylesheet, any custom stylesheets you link to are not copied to the directory where your output is saved. + +[#style-nested] +.Stylesheets and processing multiple nested documents +**** +When you are xref:cli:process-multiple-files.adoc[running Asciidoctor once across a nested set of documents], it's currently not possible to specify a single relative path for the `stylesdir` attribute that would work for all of the documents. +This is because the relative depth of the stylesheet's location differs for the documents in the subdirectories. +One way to solve this problem is to maintain the path to `stylesdir` in each document. + +Let's say you have three AsciiDoc documents saved in the following directory structure: + +.... +/my-documents + a.adoc + b.adoc + /my-nested-documents + c.adoc + /my-stylesheets +.... + +For [.path]_a.adoc_ and [.path]_b.adoc_, set `stylesdir` to: + +[source,asciidoc] +---- +:stylesdir: my-stylesheets +---- + +For [.path]_c.adoc_, set `stylesdir` to: + +[source,asciidoc] +---- +:stylesdir: ../my-stylesheets +---- + +If you're serving your documents from a webserver, you can solve this problem by providing an absolute path to the stylesheet. +**** diff --git a/docs/modules/html-backend/pages/favicon.adoc b/docs/modules/html-backend/pages/favicon.adoc new file mode 100644 index 00000000..34a8f15d --- /dev/null +++ b/docs/modules/html-backend/pages/favicon.adoc @@ -0,0 +1,48 @@ += Add a Favicon + +When using Asciidoctor to generate a standalone HTML document (i.e., the `header_footer` option is `true`), you can instruct the processor to include a link to a favicon by setting the favicon attribute in the document header. + +[source,asciidoc] +---- += Document Title +:favicon: +---- + +By default, the processor will add a link reference of type "icon" that refers to a file named _favicon.ico_ (relative to the HTML document): + +[source,html] +---- + +---- + +This reference gets added inside the HTML `` 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] +---- + +---- + +Notice the mimetype is automatically set based on the file extension of the image. + +The value of the `iconsdir` attribute is not prepend to the favicon path as it is with icons in the content. +If you want this directory to be included in the favicon path, you must reference it explicitly: + +[source,asciidoc] +---- +:favicon: {iconsdir}/favicon.png +---- + +TIP: If you're converting a set of AsciiDoc files in multiple directories for the purpose of making a website, and the favicon is located in a shared location, you'll likely want to use a forward slash (`/`) at the beginning of the favicon path. + +If you're looking for more control over how the favicon is declared, you should use a xref:ROOT:docinfo.adoc#head[head docinfo file]. +Keep in mind that if you add an icon link in a head docinfo file and also set the favicon attribute, you'll end up with two icon links in the generated HTML document. diff --git a/docs/modules/html-backend/pages/index.adoc b/docs/modules/html-backend/pages/index.adoc new file mode 100644 index 00000000..5c562bdb --- /dev/null +++ b/docs/modules/html-backend/pages/index.adoc @@ -0,0 +1,81 @@ += Generate HTML from AsciiDoc +:navtitle: Generate HTML + +== HTML 5 converter + +Asciidoctor's default output format is HTML. + +`html5`:: HTML 5 markup styled with CSS3. + +== Generate HTML using the html5 converter + +In this section, we'll create a sample document, then process and convert it with Asciidoctor's `html5` converter. + +. Create an AsciiDoc file like the one below +. Save the file as [.path]_my-sample.adoc_ + +[source,asciidoc] +---- +include::example$mysample.adoc[] +---- + +To convert [.path]_my-sample.adoc_ to HTML from the command line: + +. Open a console +. Switch to the directory that contains the [.path]_my-sample.adoc_ document +. Call the Asciidoctor processor with the `asciidoctor` command, followed by the name of the document you want to convert + +//^ + + $ asciidoctor my-sample.adoc + +Remember, Asciidoctor's default converter is html5, so it isn't necessary to specify it with the `-b` command. + +You won't see any messages printed to the console. +If you type `ls` or view the directory in a file manager, there is a new file named [.path]_my-sample.html_. + + $ ls + my-sample.adoc my-sample.html + +Asciidoctor derives the name of the output document from the name of the input document. + +Open [.path]_my-sample.html_ in your web browser. +Your document should look like the image below. + +==== +#fix ex# +//image::mysample.png[] +==== + +The document's text, titles, and link is styled by the default Asciidoctor stylesheet, which is embedded in the HTML output. +As a result, you could save [.path]_my-sample.html_ to any computer and it will look the same. + +[#xhtml] +== Generate XHTML + +To convert AsciiDoc to XHTML, set the backend to `xhtml5`. + +.Produce XHTML using the built-in HTML converter +[source,console] +---- +asciidoctor -b xhtml5 document.adoc +---- + +To produce XHTML instead of HTML when using converter templates, set the `htmlsyntax` attribute to `xml` in addition to the backend option: + +.Produce XHTML using custom templates +[source,console] +---- +asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml document.adoc +---- + +.Black Box Decoded: XHTML and htmlsyntax +**** +XHTML output is a special mode of the built-in HTML5 converter. +It is activated by prefixing the backend value with `x` (e.g., `xhtml` or `xhtml5`). +This hint implicitly assigns the `htmlsyntax` attribute to the value `xml`, which normally has the value `html`. + +For all other converters, the `htmlsyntax` attribute is not set explicitly. +If you want a converter template that's written in Slim or Haml to output XHTML instead of the default HTML, you simply need to set the `htmlsyntax` attribute to `xml` explicitly. +Asciidoctor will pass on this preference to the Slim or Haml template engine by setting the `:format` option to `:html5`. +**** diff --git a/docs/modules/html-backend/pages/manage-images.adoc b/docs/modules/html-backend/pages/manage-images.adoc new file mode 100644 index 00000000..38b69aae --- /dev/null +++ b/docs/modules/html-backend/pages/manage-images.adoc @@ -0,0 +1,24 @@ += Manage Images + +Images are not embedded in the HTML output by default. +If you have image references in your document, you'll have to save the image files in the same directory as your converted document. + +As an alternative, you can embed the images directly into the document by setting the `data-uri` document attribute. + + $ asciidoctor -a data-uri my-sample.adoc + +[source,asciidoc] +---- +include::example$mysample-data-uri.adoc[] +---- + +==== +#fix ex# +//image::mysample-data-uri.png[] +==== + +If the target of one or more images in the document is a URI, you must also set the `allow-uri-read` attribute securely and run Asciidoctor in `SECURE` mode or less. + + $ asciidoctor -a data-uri -a allow-uri-read my-sample.adoc + +The same is true when converting the document to PDF using Asciidoctor PDF, even if the `allow-uri-read` attribute is not set (since the behavior is implied). diff --git a/docs/modules/html-backend/pages/manage-stylesheets.adoc b/docs/modules/html-backend/pages/manage-stylesheets.adoc new file mode 100644 index 00000000..aa6042b3 --- /dev/null +++ b/docs/modules/html-backend/pages/manage-stylesheets.adoc @@ -0,0 +1,46 @@ += Manage Stylesheets + +== What is the default stylesheet? + +Asciidoctor comes bundled with a stylesheet, named [.path]_asciidoctor.css_. +It uses this stylesheet for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes. +This stylesheet is applied by default unless you tell Asciidoctor to use another stylesheet. +See xref:html-backend:apply-stylesheet.adoc[] to learn about the default and custom stylesheet options. + +== Embed a stylesheet + +When you generate a document with the `html5` backend, the [.path]_asciidoctor.css_ stylesheet is embedded into the HTML output by default when the safe mode is less than `SECURE`. +If your stylesheet is being linked to when you expect it to be embedded, lower the safe mode (`safe` is the recommend value). + +== Link to a stylesheet + +You can link to the stylesheet instead of embedding it. +This is the mandatory behavior when the safe mode is `SECURE`. + +To have your document link to the stylesheet, set the `linkcss` attribute in the document's header. + +[source,asciidoc] +---- +include::example$mysample-link.adoc[] +---- + +You can also set `linkcss` with the CLI. + + $ asciidoctor -a linkcss my-sample.adoc + +Now, when you view the directory, you should see the file [.path]_asciidoctor.css_ in addition to [.path]_my-sample.adoc_ and [.path]_my-sample.html_. +The `linkcss` attribute automatically copies [.path]_asciidoctor.css_ to the output directory. +Additionally, you can inspect [.path]_my-sample.html_ in your browser and see `` inside the `` tags. + +==== +#fix ex# +//image::mysample-link.png[] +==== + +== Don't apply a stylesheet + +If you don't want any styles applied to the HTML output of your document, unset the `stylesheet` attribute. + + $ asciidoctor -a stylesheet! my-sample.adoc + +One of Asciidoctor's strengths is the ease in which you can swap the default stylesheet for your own xref:apply-stylesheet.adoc[custom stylesheet]. diff --git a/docs/modules/html-backend/pages/skip-front-matter.adoc b/docs/modules/html-backend/pages/skip-front-matter.adoc new file mode 100644 index 00000000..0eb065d5 --- /dev/null +++ b/docs/modules/html-backend/pages/skip-front-matter.adoc @@ -0,0 +1,30 @@ += Skip Front Matter + +== Front matter for static site generators + +Many static site generators (i.e., Jekyll, Middleman) rely on [.term]*front matter* added to the top of the document to determine how to convert the content. +Front matter typically starts on the first line of a file and is bounded by block delimiters (e.g., `+---+`). + +Here's an example of a document that contains front matter: + +[source,asciidoc] +---- +--- <.> +layout: default <.> +--- <.> += Document Title + +content +---- +<.> Front matter opening delimiter +<.> Front matter data +<.> Front matter closing delimiter + +The static site generator removes these lines before passing the document to the AsciiDoc processor to be converted. +Outside of the tool, however, these extra lines can throw off the processor. + +== skip-front-matter option + +If the `skip-front-matter` option is set via the API or CLI (e.g., `-a skip-front-matter`), Asciidoctor will recognize the front matter and consume it before parsing the document. +Asciidoctor stores the content it removes in the `front-matter` attribute to make it available for integrations. +Asciidoctor also removes front matter when reading xref:asciidoc:directives:include.adoc[include files]. diff --git a/docs/modules/html-backend/pages/verbatim-line-wrap.adoc b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc new file mode 100644 index 00000000..f38b7daa --- /dev/null +++ b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc @@ -0,0 +1,40 @@ += Verbatim Block Line Wrapping + +The default Asciidoctor stylesheet wraps long lines in verbatim blocks by applying the CSS `white-space: pre-wrap` and `word-wrap: break-word`. +The lines are wrapped at word boundaries, similar to how most text editors wrap lines. +This prevents horizontal scrolling which some users considered a greater readability problem than line wrapping. + +However, this behavior is configurable because there are times when you don't want the lines in listing and literal blocks to wrap. + +== Prevent line wrapping + +There are two ways to prevent lines from wrapping so that horizontal scrolling is used instead: + +* `nowrap` block option +* unset the `prewrap` document attribute (on by default) + +You can use the `nowrap` option on literal or listing blocks to prevent lines from being wrapped in the HTML. + +// FIXME this section is creating broken AsciiDoc!! +.Listing block with nowrap option syntax +.... +include::example$wrap.adoc[tag=nowrap] +.... + +When the nowrap option is used, the `nowrap` class is added to the `
` element.
+This class changes the CSS to `white-space: pre` and `word-wrap: normal`.
+
+.Result: Listing block with nowrap option applied
+include::example$wrap.adoc[tag=nowrap]
+
+To prevent lines from wrapping globally, unset the `prewrap` attribute on the document.
+
+.Disable prewrap globally (thus, enabling nowrap)
+[source]
+----
+:prewrap!:
+----
+
+When the prewrap attribute is unset, the `nowrap` class is added to any `
` elements.
+
+Now, you can use the line wrapping strategy that works best for you and your readers.
-- 
cgit v1.2.3


From a313298c205b18b9e2c71926401f50146a3bccc5 Mon Sep 17 00:00:00 2001
From: Dan Allen 
Date: Thu, 19 Nov 2020 01:17:31 -0700
Subject: add :standalone option to Ruby API options; list :header_footer as
 deprecated alias

---
 docs/modules/html-backend/pages/favicon.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs/modules/html-backend')

diff --git a/docs/modules/html-backend/pages/favicon.adoc b/docs/modules/html-backend/pages/favicon.adoc
index 34a8f15d..a6400aff 100644
--- a/docs/modules/html-backend/pages/favicon.adoc
+++ b/docs/modules/html-backend/pages/favicon.adoc
@@ -1,6 +1,6 @@
 = Add a Favicon
 
-When using Asciidoctor to generate a standalone HTML document (i.e., the `header_footer` option is `true`), you can instruct the processor to include a link to a favicon by setting the favicon attribute in the document header.
+When using Asciidoctor to generate a standalone HTML document (i.e., the `standalone` option is `true`), you can instruct the processor to include a link to a favicon by setting the favicon attribute in the document header.
 
 [source,asciidoc]
 ----
-- 
cgit v1.2.3


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

---
 docs/modules/html-backend/nav.adoc                 |  4 +-
 .../html-backend/pages/apply-code-stylesheets.adoc | 27 ------
 .../html-backend/pages/apply-stylesheet.adoc       | 97 ----------------------
 .../html-backend/pages/custom-stylesheets.adoc     | 97 ++++++++++++++++++++++
 docs/modules/html-backend/pages/index.adoc         |  2 +-
 .../html-backend/pages/manage-stylesheets.adoc     | 11 ++-
 .../pages/source-highlighting-stylesheets.adoc     | 27 ++++++
 7 files changed, 132 insertions(+), 133 deletions(-)
 delete mode 100644 docs/modules/html-backend/pages/apply-code-stylesheets.adoc
 delete mode 100644 docs/modules/html-backend/pages/apply-stylesheet.adoc
 create mode 100644 docs/modules/html-backend/pages/custom-stylesheets.adoc
 create mode 100644 docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc

(limited to 'docs/modules/html-backend')

diff --git a/docs/modules/html-backend/nav.adoc b/docs/modules/html-backend/nav.adoc
index aa1054cb..396b226a 100644
--- a/docs/modules/html-backend/nav.adoc
+++ b/docs/modules/html-backend/nav.adoc
@@ -1,7 +1,7 @@
 * xref:index.adoc[]
 ** xref:manage-stylesheets.adoc[]
-** xref:apply-code-stylesheets.adoc[]
-** xref:apply-stylesheet.adoc[]
+** xref:source-highlighting-stylesheets.adoc[]
+** xref:custom-stylesheets.adoc[]
 ** xref:favicon.adoc[]
 ** xref:manage-images.adoc[]
 ** xref:favicon.adoc[]
diff --git a/docs/modules/html-backend/pages/apply-code-stylesheets.adoc b/docs/modules/html-backend/pages/apply-code-stylesheets.adoc
deleted file mode 100644
index 42be39cb..00000000
--- a/docs/modules/html-backend/pages/apply-code-stylesheets.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-= Apply CodeRay or Pygments Stylesheets
-// um anchor: hl-css
-// html-code-styles.adoc, included in convert-documents and the user-manual.
-
-Asciidoctor can embed the stylesheet for the CodeRay or Pygments syntax highlighters.
-
-== Requirements
-
-First, make sure the appropriate library is installed on your system.
-See xref:integrations:rouge.adoc[], xref:integrations:coderay.adoc[], or xref:integrations:pygments.adoc[] for installation instructions.
-Next, set the xref:asciidoc:verbatim:source-highlighter.adoc[source-highlighter attribute] and assign it the value that corresponds to the library you installed.
-
-[#coderay]
-== CodeRay
-
-If the `source-highlighter` attribute is `coderay` and the `coderay-css` attribute is `class`, the CodeRay stylesheet is:
-
-* _embedded_ by default
-* _copied_ to the file [.path]_asciidoctor-coderay.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set
-
-[#pygments]
-== Pygments
-
-If the `source-highlighter` attribute is `pygments` and the `pygments-css` attribute is `class`, the Pygments stylesheet is:
-
-* _embedded_ by default
-* _copied_ to the file [.path]_asciidoctor-pygments.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set
diff --git a/docs/modules/html-backend/pages/apply-stylesheet.adoc b/docs/modules/html-backend/pages/apply-stylesheet.adoc
deleted file mode 100644
index e645e664..00000000
--- a/docs/modules/html-backend/pages/apply-stylesheet.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-= Apply a Custom Stylesheet
-////
-apply-theme.adoc, included in:
-- user-manual
-- produce-custom-themes-using-asciidoctor-stylesheet-factory
-////
-
-A custom stylesheet can be stored in the same directory as your document or in a separate directory.
-Like the default stylesheet, you can have the output document link to your custom stylesheet or embed it.
-
-If the stylesheet is in the same directory as your document, you can apply it when converting your document to HTML from the CLI.
-
- $ asciidoctor -a stylesheet=my-styles.css my-sample.adoc
-
-. Save your custom stylesheet in the same directory as [.path]_my-sample.adoc_
-. Call the `asciidoctor` processor
-. Set `-a` (`--attribute`) and `stylesheet`
-. Assign the stylesheet file's name to the `stylesheet` attribute
-. Enter your document file's name.
-
-Alternatively, let's set the `stylesheet` attribute in the header of [.path]_my-sample.adoc_.
-
-[source,asciidoc]
-----
-include::example$mysample-stylesheet.adoc[]
-----
-
-====
-#fix ex#
-//image::mysample-stylesheet.png[]
-====
-
-When your document and the stylesheet are stored in different directories, you need to tell Asciidoctor where to look for the stylesheet in relation to your document.
-Asciidoctor uses the relative or absolute path you assign to the `stylesdir` attribute to find the stylesheet.
-Let's move [.path]_my-styles.css_ into [.path]_my-documents/my-stylesheets_.
-Our AsciiDoc document, [.path]_my-sample.adoc_, is saved in the [.path]_my-documents_ directory.
-
-[source,asciidoc]
-----
-include::example$mysample-stylesdir.adoc[]
-----
-
-After processing [.path]_my-sample.adoc_, its HTML output ([.path]_my-sample.html_), which includes the embedded [.path]_my-styles.css_ stylesheet, is created in the [.path]_my-documents_ directory.
-
-====
-#fix ex#
-//image::mysample-stylesdir-dir.png[]
-====
-
-You can also set `stylesdir` in the CLI.
-
- $ asciidoctor -a stylesdir=my-stylesheets/ -a stylesheet=my-styles.css my-sample.adoc
-
-If you don't want to embed the [.path]_my-styles.css_ stylesheet into your HTML output, make sure to set `linkcss`.
-
-[source,asciidoc]
-----
-include::example$mysample-stylesdir-link.adoc[]
-----
-
-After your document is converted, notice that a copy of [.path]_my-styles.css_ was not created in the [.path]_my-documents_ directory.
-Unlike when you link to the default Asciidoctor stylesheet, any custom stylesheets you link to are not copied to the directory where your output is saved.
-
-[#style-nested]
-.Stylesheets and processing multiple nested documents
-****
-When you are xref:cli:process-multiple-files.adoc[running Asciidoctor once across a nested set of documents], it's currently not possible to specify a single relative path for the `stylesdir` attribute that would work for all of the documents.
-This is because the relative depth of the stylesheet's location differs for the documents in the subdirectories.
-One way to solve this problem is to maintain the path to `stylesdir` in each document.
-
-Let's say you have three AsciiDoc documents saved in the following directory structure:
-
-....
-/my-documents
-  a.adoc
-  b.adoc
-  /my-nested-documents
-    c.adoc
-  /my-stylesheets
-....
-
-For [.path]_a.adoc_ and [.path]_b.adoc_, set `stylesdir` to:
-
-[source,asciidoc]
-----
-:stylesdir: my-stylesheets
-----
-
-For [.path]_c.adoc_, set `stylesdir` to:
-
-[source,asciidoc]
-----
-:stylesdir: ../my-stylesheets
-----
-
-If you're serving your documents from a webserver, you can solve this problem by providing an absolute path to the stylesheet.
-****
diff --git a/docs/modules/html-backend/pages/custom-stylesheets.adoc b/docs/modules/html-backend/pages/custom-stylesheets.adoc
new file mode 100644
index 00000000..1cc20d2a
--- /dev/null
+++ b/docs/modules/html-backend/pages/custom-stylesheets.adoc
@@ -0,0 +1,97 @@
+= Apply a Custom Stylesheet
+////
+apply-theme.adoc, included in:
+- user-manual
+- produce-custom-themes-using-asciidoctor-stylesheet-factory
+////
+
+A custom stylesheet can be stored in the same directory as your document or in a separate directory.
+Like the xref:manage-stylesheets.adoc[default stylesheet], you can have the output document link to or embed your custom stylesheet.
+
+If the stylesheet is in the same directory as your document, you can apply it when converting your document to HTML from the CLI.
+
+ $ asciidoctor -a stylesheet=my-styles.css my-sample.adoc
+
+. Save your custom stylesheet in the same directory as [.path]_my-sample.adoc_
+. Call the `asciidoctor` processor
+. Set `-a` (`--attribute`) and `stylesheet`
+. Assign the stylesheet file's name to the `stylesheet` attribute
+. Enter your document file's name.
+
+Alternatively, let's set the `stylesheet` attribute in the header of [.path]_my-sample.adoc_.
+
+[source,asciidoc]
+----
+include::example$mysample-stylesheet.adoc[]
+----
+
+====
+#fix ex#
+//image::mysample-stylesheet.png[]
+====
+
+When your document and the stylesheet are stored in different directories, you need to tell Asciidoctor where to look for the stylesheet in relation to your document.
+Asciidoctor uses the relative or absolute path you assign to the `stylesdir` attribute to find the stylesheet.
+Let's move [.path]_my-styles.css_ into [.path]_my-documents/my-stylesheets_.
+Our AsciiDoc document, [.path]_my-sample.adoc_, is saved in the [.path]_my-documents_ directory.
+
+[source,asciidoc]
+----
+include::example$mysample-stylesdir.adoc[]
+----
+
+After processing [.path]_my-sample.adoc_, its HTML output ([.path]_my-sample.html_), which includes the embedded [.path]_my-styles.css_ stylesheet, is created in the [.path]_my-documents_ directory.
+
+====
+#fix ex#
+//image::mysample-stylesdir-dir.png[]
+====
+
+You can also set `stylesdir` in the CLI.
+
+ $ asciidoctor -a stylesdir=my-stylesheets/ -a stylesheet=my-styles.css my-sample.adoc
+
+If you don't want to embed the [.path]_my-styles.css_ stylesheet into your HTML output, make sure to set `linkcss`.
+
+[source,asciidoc]
+----
+include::example$mysample-stylesdir-link.adoc[]
+----
+
+After your document is converted, notice that a copy of [.path]_my-styles.css_ was not created in the [.path]_my-documents_ directory.
+Unlike when you link to the default Asciidoctor stylesheet, any custom stylesheets you link to are not copied to the directory where your output is saved.
+
+[#style-nested]
+.Stylesheets and processing multiple nested documents
+****
+When you are xref:cli:process-multiple-files.adoc[running Asciidoctor once across a nested set of documents], it's currently not possible to specify a single relative path for the `stylesdir` attribute that would work for all of the documents.
+This is because the relative depth of the stylesheet's location differs for the documents in the subdirectories.
+One way to solve this problem is to maintain the path to `stylesdir` in each document.
+
+Let's say you have three AsciiDoc documents saved in the following directory structure:
+
+....
+/my-documents
+  a.adoc
+  b.adoc
+  /my-nested-documents
+    c.adoc
+  /my-stylesheets
+....
+
+For [.path]_a.adoc_ and [.path]_b.adoc_, set `stylesdir` to:
+
+[source,asciidoc]
+----
+:stylesdir: my-stylesheets
+----
+
+For [.path]_c.adoc_, set `stylesdir` to:
+
+[source,asciidoc]
+----
+:stylesdir: ../my-stylesheets
+----
+
+If you're serving your documents from a webserver, you can solve this problem by providing an absolute path to the stylesheet.
+****
diff --git a/docs/modules/html-backend/pages/index.adoc b/docs/modules/html-backend/pages/index.adoc
index 5c562bdb..be3c9ec3 100644
--- a/docs/modules/html-backend/pages/index.adoc
+++ b/docs/modules/html-backend/pages/index.adoc
@@ -9,7 +9,7 @@ Asciidoctor's default output format is HTML.
 
 == Generate HTML using the html5 converter
 
-In this section, we'll create a sample document, then process and convert it with Asciidoctor's `html5` converter.
+In this section, we'll create a sample document, then process and convert it with Asciidoctor's built-in HTML converter.
 
 . Create an AsciiDoc file like the one below
 . Save the file as [.path]_my-sample.adoc_
diff --git a/docs/modules/html-backend/pages/manage-stylesheets.adoc b/docs/modules/html-backend/pages/manage-stylesheets.adoc
index aa6042b3..781c736e 100644
--- a/docs/modules/html-backend/pages/manage-stylesheets.adoc
+++ b/docs/modules/html-backend/pages/manage-stylesheets.adoc
@@ -3,13 +3,12 @@
 == What is the default stylesheet?
 
 Asciidoctor comes bundled with a stylesheet, named [.path]_asciidoctor.css_.
-It uses this stylesheet for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes.
-This stylesheet is applied by default unless you tell Asciidoctor to use another stylesheet.
-See xref:html-backend:apply-stylesheet.adoc[] to learn about the default and custom stylesheet options.
+The built-in HTML converter uses this stylesheet for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes.
+Asciidoctor applies this stylesheet by default unless you tell Asciidoctor to use another stylesheet.
 
 == Embed a stylesheet
 
-When you generate a document with the `html5` backend, the [.path]_asciidoctor.css_ stylesheet is embedded into the HTML output by default when the safe mode is less than `SECURE`.
+When you generate a document using the built-in HTML converter, the [.path]_asciidoctor.css_ stylesheet is embedded into the HTML output by default when the xref:ROOT:safe-modes.adoc[safe mode] is less than `SECURE`.
 If your stylesheet is being linked to when you expect it to be embedded, lower the safe mode (`safe` is the recommend value).
 
 == Link to a stylesheet
@@ -37,10 +36,10 @@ Additionally, you can inspect [.path]_my-sample.html_ in your browser and see `<
 //image::mysample-link.png[]
 ====
 
-== Don't apply a stylesheet
+== Disable a stylesheet
 
 If you don't want any styles applied to the HTML output of your document, unset the `stylesheet` attribute.
 
  $ asciidoctor -a stylesheet! my-sample.adoc
 
-One of Asciidoctor's strengths is the ease in which you can swap the default stylesheet for your own xref:apply-stylesheet.adoc[custom stylesheet].
+One of Asciidoctor's strengths is the ease in which you can swap the default stylesheet for your own xref:custom-stylesheets.adoc[custom stylesheet].
diff --git a/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc b/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc
new file mode 100644
index 00000000..0b9ad08a
--- /dev/null
+++ b/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc
@@ -0,0 +1,27 @@
+= Embed a CodeRay or Pygments Stylesheet
+// um anchor: hl-css
+// html-code-styles.adoc, included in convert-documents and the user-manual.
+
+Asciidoctor can embed the stylesheet for the CodeRay or Pygments syntax highlighters.
+
+== Requirements
+
+First, make sure the appropriate library is installed on your system.
+See xref:source-highlighters:rouge.adoc[], xref:source-highlighters:coderay.adoc[], or xref:source-highlighters:pygments.adoc[] for installation instructions.
+Next, set the xref:asciidoc:verbatim:source-highlighter.adoc[source-highlighter attribute] and assign it the value that corresponds to the library you installed.
+
+[#coderay]
+== CodeRay
+
+If the `source-highlighter` attribute is `coderay` and the `coderay-css` attribute is `class`, the CodeRay stylesheet is:
+
+* _embedded_ by default
+* _copied_ to the file [.path]_asciidoctor-coderay.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set
+
+[#pygments]
+== Pygments
+
+If the `source-highlighter` attribute is `pygments` and the `pygments-css` attribute is `class`, the Pygments stylesheet is:
+
+* _embedded_ by default
+* _copied_ to the file [.path]_asciidoctor-pygments.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set
-- 
cgit v1.2.3


From b31306f6bab06f5acf8e5f1b55204e7f4092e973 Mon Sep 17 00:00:00 2001
From: Dan Allen 
Date: Fri, 20 Nov 2020 18:20:47 -0700
Subject: document the default stylesheet

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

(limited to 'docs/modules/html-backend')

diff --git a/docs/modules/html-backend/images/default-stylesheet.png b/docs/modules/html-backend/images/default-stylesheet.png
new file mode 100644
index 00000000..4584a510
Binary files /dev/null and b/docs/modules/html-backend/images/default-stylesheet.png differ
diff --git a/docs/modules/html-backend/images/no-stylesheet.png b/docs/modules/html-backend/images/no-stylesheet.png
new file mode 100644
index 00000000..77e880ad
Binary files /dev/null and b/docs/modules/html-backend/images/no-stylesheet.png differ
diff --git a/docs/modules/html-backend/nav.adoc b/docs/modules/html-backend/nav.adoc
index 396b226a..39e212c5 100644
--- a/docs/modules/html-backend/nav.adoc
+++ b/docs/modules/html-backend/nav.adoc
@@ -1,4 +1,5 @@
 * xref:index.adoc[]
+** xref:default-stylesheet.adoc[]
 ** xref:manage-stylesheets.adoc[]
 ** xref:source-highlighting-stylesheets.adoc[]
 ** xref:custom-stylesheets.adoc[]
diff --git a/docs/modules/html-backend/pages/default-stylesheet.adoc b/docs/modules/html-backend/pages/default-stylesheet.adoc
new file mode 100644
index 00000000..57a1737a
--- /dev/null
+++ b/docs/modules/html-backend/pages/default-stylesheet.adoc
@@ -0,0 +1,188 @@
+////
+.TODO
+* add more xrefs
+* screenshot showing it in action (we need a good example document for when we need to make these screenshots)
+* link to themes based on the default stylesheet
+////
+= Default Stylesheet
+
+When you use the HTML converter to generate a standalone HTML document, Asciidoctor includes a default stylesheet to make the HTML it produces look great right out of the box.
+This, in turn, gets you up and running quickly by giving you a result to preview or publish without having to do any additional work.
+
+Keep in mind that the default stylesheet that Asciidoctor provides is just that, _a default_.
+If you don't like its appearance, you can customize it or replace it with a different once.
+
+This page covers why the default is necessary, how to apply it, and how to build on it so you don't have to create a stylesheet from scratch.
+
+== Why provide a default?
+
+As previously stated, a default stylesheet is included to provide a nice out-of-the-box experience.
+But there's more to it.
+There are elements of AsciiDoc that require stylesheet support.
+
+One example is to honor *built-in roles*, such as `text-center`.
+In order for a role to take effect, it needs a companion CSS class in the stylesheet.
+To satisfy the expectations of a built-in role, a stylesheet is required.
+
+Another example is to implement *list marker styles*.
+AsciiDoc allows you to specify the marker for a list using a block style (e.g., `loweralpha`).
+However, HTML does not apply these markers by default.
+Rather, it's something that the stylesheet provides.
+
+The default stylesheet also applies *borders and shading to table cells* to support all combinations of the frame, grid, and stripes attributes.
+
+Yet another example is the *TOC position*.
+To position the TOC on the left or right requires help from the stylesheet to change the layout of the page so the TOC appears as a sidebar.
+It's the stylesheet that handles that task.
+
+In order for the AsciiDoc experience to be complete when generating HTML, a stylesheet is required.
+The default stylesheet not only completes this experience, but also serves as a reference for the styles a custom stylesheet must provide.
+
+=== Web fonts
+
+The default stylesheet ensures that the same fonts are selected across all platforms.
+
+By default, the browser relies on system fonts.
+But system fonts vary widely by platform, so users end up getting a very different experience.
+That's where web fonts come in.
+
+When the default stylesheet is used, the converter adds additional HTML to load open source fonts from Google Fonts.
+The default stylesheet, in turn, specifies a preference for these fonts.
+
+The web fonts used by the default stylesheet are as follows:
+
+Noto Serif:: body text (default)
+Open Sans:: headings
+Droid Sans Mono:: monospaced phrases and verbatim blocks
+
+Loading and preferring these web fonts ensures everyone sees the same result.
+
+== Usage
+
+When generating HTML, there's nothing special you need to do to apply the default stylesheet.
+Asciidoctor automatically embeds it in the `` of the generated HTML when you run the `asciidoctor` command.
+
+ $ asciidoctor document.adoc
+
+Since no stylesheet is specified, Asciidoctor uses the stylesheet (located at [.path]_data/stylesheets/asciidoctor.css_ inside the installed gem).
+When you view the generated HTML file, [.path]_document.html_, you'll see styled HTML, as shown here:
+
+image::default-stylesheet.png[]
+
+When using the API, Asciidoctor links to the stylesheet by default instead of embedding it.
+Yet, it does not copy the stylesheet to the output directory (it needs to be placed there separately).
+If it's not already there, the browser will not be able to find the stylesheet.
+To solve this problem, set the safe mode to server or lower (e.g., server, safe, or unsafe) and Asciidoctor will embed the default stylesheet, like when using the `asciidoctor` command.
+
+[source,ruby]
+----
+require 'asciidoctor'
+
+Asciidoctor.convert_file 'document.adoc', safe: :safe
+----
+
+== Disable the default stylesheet
+
+If you don't want Asciidoctor to include the default stylesheet, unset the `stylesheet` attribute:
+
+ $ asciidoctor -a stylesheet! document.adoc
+
+When you view the generated HTML file, [.path]_document.html_, you'll see bare HTML without any styles applied, as shown here:
+
+image::no-stylesheet.png[]
+
+== Disable or modify the web fonts
+
+When the default stylesheet is used, the converter adds a `` 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 <> 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 <> 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 `` 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 `
+----
+
+Now tell Asciidoctor to look for and load the docinfo file using the `docinfo` attribute:
+
+ $ asciidoctor -a docinfo=shared document.adoc
+
+The `