Apply a Custom Stylesheet

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
  1. Save your custom stylesheet in the same directory as my-sample.adoc

  2. Call the asciidoctor processor

  3. Set -a (--attribute) and stylesheet

  4. Assign the stylesheet file’s name to the stylesheet attribute

  5. Enter your document file’s name.

Alternatively, let’s set the stylesheet attribute in the header of my-sample.adoc.

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

fix ex

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 my-styles.css into my-documents/my-stylesheets. Our AsciiDoc document, my-sample.adoc, is saved in the my-documents directory.

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

After processing my-sample.adoc, its HTML output (my-sample.html), which includes the embedded my-styles.css stylesheet, is created in the my-documents directory.

fix ex

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 my-styles.css stylesheet into your HTML output, make sure to set linkcss.

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

After your document is converted, notice that a copy of my-styles.css was not created in the 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.

Stylesheets and processing multiple nested documents

When you are 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 a.adoc and b.adoc, set stylesdir to:

:stylesdir: my-stylesheets

For c.adoc, set stylesdir to:

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