Stylesheet Modes
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 default stylesheet or a custom stylesheet. This page covers the document attributes that control how the stylesheet is applied.
The HTML converter will only apply a stylesheet when generating a standalone HTML document.
That’s because the stylesheet goes inside the HTML <head> element, and the converter only generates that element for standalone output.
|
Embed the stylesheet
When the safe mode is server or lower, the default behavior of the HTML converter is to read the stylesheet file, enclose its contents in a <style> element, and embed it directly into the <head> element 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 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 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 link to the stylesheet instead of embedding it.
To link to the stylesheet, the converter uses a <link> element specialized by the rel="stylesheet" attribute.
The href attribute will reference the stylesheet using a relative path.
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:
= The Dangers of Wolpertingers
:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger
:linkcss:
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].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> element in the output file my-document.html, you’ll see that the HTML links to the stylesheet.
<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 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 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 output file in a different directory from the source file.
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 asciidoctor.css is copied to the same directory as the generated HTML file my-document.html.
Type ls to view the files in the directory.
You should see a file named 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:
= The Dangers of Wolpertingers
:url-wolpertinger: https://en.wikipedia.org/wiki/Wolpertinger
:linkcss:
:!copycss:
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].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 asciidoctor.css is missing (unless it was already there).
We’ll see the copycss attribute come up again on the custom stylesheet page as a means of overriding the location of the stylesheet to copy.
Disable the stylesheet
The stylesheet is effectively disabled when generating embedded HTML, since the embedded HTML does not include the <head> element.
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, my-document.html, you’ll see bare HTML without any styles applied, as shown here:
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.