////
Custom Themes
Applying a theme

This document is included in:

- user-manual
- produce-custom-themes-using-asciidoctor-stylesheet-factory
////

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=mystyles.css mysample.adoc

. Save your custom stylesheet in the same directory as `mysample.adoc`
. Call the `asciidoctor` processor
. Set `-a` (`--attribute`) and `stylesheet`
. Assign the stylesheet file's name to the `stylesheet` attribute
. Enter your document file's name.

Alternatively, let's set the `stylesheet` attribute in the header of `mysample.adoc`.

----
include::mysample-stylesheet.adoc[]
----

====
image::mysample-stylesheet.png[]
====

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 `mystyles.css` into `mydocuments/mystylesheets/`.
Our AsciiDoc document, `mysample.adoc`, is saved in the `mydocuments/` directory.

----
include::mysample-stylesdir.adoc[]
----

After processing `mysample.adoc`, its HTML output (`mysample.html`), which includes the embedded `mystyles.css` stylesheet, is created in the `mydocuments/` directory.

====
image::mysample-stylesdir-dir.png[]
====

You can also set `stylesdir` in the CLI.

 $ asciidoctor -a stylesdir=mystylesheets/ -a stylesheet=mystyles.css mysample.adoc

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

----
include::mysample-stylesdir-link.adoc[]
----

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

[#style-nest-doc]
.Stylesheets and processing multiple nested documents
****
When you are <<user-manual.adoc#process-multiple-source-files-from-the-cli,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:

----
/mydocuments
  a.adoc
  b.adoc
  /mynesteddocuments
    c.adoc
  /mystylesheets
----

For `a.adoc` and `b.adoc`, set `stylesdir` to:

----
:stylesdir: mystylesheets
----

For `c.adoc`, set `stylesdir` to:

----
:stylesdir: ../mystylesheets
----

If you're serving your documents from a webserver, you can solve this problem by providing an absolute path to the stylesheet.
****