Stylesheets

On this page, you’ll learn:

How to apply a theme.
How to customize the default stylesheet.

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 via the API:

import { convertFile } from '@asciidoctor/core'

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

Via the CLI:

$ asciidoctor -a stylesheet=styles.css file.adoc

Alternatively, 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.

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

Customizing the default stylesheet

The default Asciidoctor stylesheet source is available in the asciidoctor/asciidoctor repository. You can use it as a reference or a starting point for your own theme.

The Asciidoctor project no longer maintains a stylesheet factory or official alternative themes. Community-shared themes can be found online, but they are not officially supported.

There are two common approaches to customization:

Override specific rules

The stylesheet attribute replaces the default Asciidoctor stylesheet entirely. To keep the default styles and only override specific rules, you have two options:

Use CSS @import at the top of your stylesheet to pull in the default one first, then add your overrides below:

@import "https://cdn.jsdelivr.net/npm/@asciidoctor/core/data/asciidoctor-default.css";

/* your overrides below */
h1, h2, h3 { font-family: Georgia, serif; }

tAlternatively, use a docinfo file to inject a <link> tag in the document <head> without writing any JavaScript. Create a file named docinfo.html next to your document and add your <link> tag:

<link rel="stylesheet" href="overrides.css">

This keeps the default stylesheet in place and loads your override stylesheet on top of it. See the Docinfo files documentation^ for the full list of naming conventions and placement options.

Start from the default stylesheet

Copy the default stylesheet and modify it directly. This gives you full control but means you are responsible for keeping up with upstream changes.