rewrite the pages that cover stylesheet modes and applying a custom stylesheet; reorder pages in nav

5 files changed, 350 insertions, 167 deletions

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