Stylesheets

On this page, you’ll learn:

  • How to apply a theme.

Applying a theme

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

asciidoctor.convertFile('file.adoc', { 'attributes': { 'stylesheet': 'styles.css' } })

  1. Save your custom stylesheet in the same directory as file.adoc

  2. Call the asciidoctor processor

  3. Set the attribute 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 file.adoc.

= Title
:stylesheet: styles.css

Welcome to the preamble of this page!

== First section

This is a paragraph with a https://asciidoctor.org/[link].

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

= Title
:stylesdir: stylesheets/
:stylesheet: styles.css

Welcome to the preamble of this page!

== First section

This is a paragraph with a https://asciidoctor.org/[link].

After processing file.adoc, its HTML output (file.html), which includes the embedded styles.css stylesheet, is created in the docs/ directory.

You can also set stylesdir in the API.

asciidoctor.convertFile('file.adoc', { 'attributes': { 'stylesdir': 'stylesheets/', 'stylesheet': 'styles.css' } })

If you don’t want to embed the styles.css stylesheet into your HTML output, make sure to set linkcss.

= Title
:linkcss:
:stylesdir: stylesheets/
:stylesheet: styles.css

Welcome to the preamble of this page!

== First section

This is a paragraph with a https://asciidoctor.org/[link].

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