Manage Stylesheets

Asciidoctor comes bundled with a stylesheet, named asciidoctor.css. It uses this stylesheet for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes.

Embed a stylesheet

When you generate a document with the html5 backend, the 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).

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.

= 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.

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 asciidoctor.css in addition to my-sample.adoc and my-sample.html. The linkcss attribute automatically copies asciidoctor.css to the output directory. Additionally, you can inspect my-sample.html in your browser and see <link rel="stylesheet" href="./asciidoctor.css"> inside the <head> tags.

fix ex

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 custom stylesheet.