You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
94 lines
3.2 KiB
94 lines
3.2 KiB
4 years ago
|
////
|
||
|
|
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.
|
||
|
|
****
|