Produce Custom Themes Using the Asciidoctor Stylesheet Factory

> Asciidoctor > Asciidoctor Documentation >

The Asciidoctor stylesheet factory is where themes are developed for styling your documents. Specifically, these stylesheets can be used to quickly customize the look and feel of HTML 5 documents generated by Asciidoctor.

To view the Asciidoctor themes in action, visit the theme showcase.

The Asciidoctor stylesheet factory is currently only compatible with Asciidoctor 0.1.2 and greater.

Setting up the factory

The stylesheets in the Asciidoctor stylesheet factory are built using Compass, a CSS authoring framework that uses Sass to generate CSS files. The styles and components are generated by Foundation 4, an awesome and flexible CSS component framework that ensures your stylesheet is cross-browser and mobile friendly.

Install the gems

In order to build the stylesheets, you must download the Asciidoctor stylesheet factory repository and install the Compass and Foundation gems.

  1. Download or clone the Asciidoctor stylesheet factory repository.

    It does not matter where you save the project on your system.

  2. Make sure you have Ruby and RubyGems installed, and, ideally, Bundler.

  3. Run Bundler to install the Compass and Foundation gems.

    $ bundle install

    The previous bundle command is equivalent to the following two commands:

    $ gem install compass --version 0.12.2
$ gem install zurb-foundation --version 4.3.2

    You don’t need to execute these gem install commands if you use Bundler.

Once you have the gems installed, you can build the stylesheets.

Build the stylesheets

To build the stylesheets:

  1. Navigate to the Asciidoctor stylesheet factory directory on your system.

  2. Run Compass’s compile command.

    $ compass compile

The stylesheets are compiled from the Sass source files in the sass/ folder and written to the stylesheets/ folder. You can reference the stylesheets in stylesheets/ from your HTML file.

Applying a stylesheet to HTML

Let’s practice applying a stylesheet to a simple AsciiDoc file. If you’re unfamiliar with the general commands needed to render and style a document created with the AsciiDoc syntax, you may want to review the How Do I Render My Document guide before proceeding.

  1. Create an AsciiDoc file like the one below.

  2. Save the file as mysample.adoc.

= Introduction to AsciiDoc
Doc Writer <doc@example.com>

A preface about http://asciidoc.org[AsciiDoc].

== First Section

* item 1
* item 2

[source,ruby]
puts "Hello, World!"

Next, you’ll use the Asciidoctor processor to generate HTML and apply a stylesheet to it from the stylesheets/ directory.

Generate an HTML document

Now it’s time to pick the stylesheet you want to apply to your content when it is rendered. In your file browser, navigate to the stylesheets/ directory. Or, using a console, change to the stylesheets/ directory and list the available stylesheets using the ls command.

$ ls
Console output of ls command
asciidoctor.css  foundation-lime.css    iconic.css       riak.css
colony.css       foundation-potion.css  maker.css        rubygems.css
foundation.css   golo.css               readthedocs.css

Let’s apply the colony.css stylesheet to the sample document.

  1. Navigate to the directory where you saved mysample.adoc.

  2. Call the asciidoctor processor.

  3. Specify the stylesheet you want applied with the stylesheet attribute.

  4. Tell the processor where the specified stylesheet is located with the stylesdir attribute.

    $ asciidoctor -a stylesheet=colony.css -a stylesdir=../stylesheets mysample.adoc

Open a browser, navigate to mysample.html and checkout the result!

If you prefer to link the colony.css stylesheet to the generated HTML output, set the linkcss attribute when you render the document.

$ asciidoctor -a linkcss -a stylesheet=colony.css -a stylesdir=../stylesheets mysample.adoc

If you inspect the mysample.html document, you should see that the stylesheet is linked to the rendered document.

<link rel="stylesheet" href="../stylesheets/colony.css">
Stylesheet images

The Golo, Maker, and Riak themes include image assets. To apply these themes to your document correctly, the applicable images must be copied into the same directory as the generated output.

For example, to apply the maker.css stylesheet to mysample.adoc:

  1. Copy body-bh.png from the images/maker/ directory into the output directory.

  2. Call the stylesheet and styledir attributes.

    $ asciidoctor -a stylesheet=maker.css -a stylesdir=../stylesheets mysample.adoc

Navigate to mysample.html in your browser. The body-bh.png image should add a graph paper-like background to your generated output.

External preview

You may want to preview sample HTML files on another computer or device. To do that, you need to serve them through a web server. You can quickly serve HTML files in the root directory of the project using the following command:

Using Python
$ python -m SimpleHTTPServer 4242

or

Using Ruby >= 1.9.3
$ ruby -run -e httpd . -p 4242

Create a custom theme

You can create your own themes to apply to your documents.

Themes go in the sass/ folder. To create a new theme, let’s call it hipster, start by creating two new files:

sass/hipster.scss

  • Imports the theme settings, which includes default variables and resets

  • Imports the AsciiDoc components

  • Defines any explicit customization

sass/settings/_hipster.scss

  • Sets variables that customize Foundation 4 and the AsciiDoc CSS components

Here’s a minimal version of sass/hipster.scss:

@import "settings/hipster";
@import "components/asciidoc";
@import "components/awesome-icons";
You don’t have to include the underscore prefix when importing files.
The awesome-icons component is only applicable to HTML generated by Asciidoctor > 0.1.2 with the icons attribute set to font.

You can add any explicit customization below the import lines.

The variables you can set in sass/settings/_hipster.scss are a combination of the Foundation 4 built-in global settings and global settings and imports for the AsciiDoc components.

Once you’ve created your custom theme, it’s time to apply it to your document.

Apply a custom theme

A custom stylesheet can be stored in the same directory as your document or in a separate directory. And, like the default stylesheet, you can link your document to your custom stylesheet or embed it. If the stylesheet is in the same directory as your document, you can apply it when rendering your document to HTML from the CLI.

$ asciidoctor -a stylesheet=mystyles.css mysample.adoc

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

= My First Experience with the Dangers of Documentation
: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 http://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.
mysample stylesheet

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.

= My First Experience with the Dangers of Documentation
: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 http://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.

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

mysample stylesdir dir

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.

= My First Experience with the Dangers of Documentation
: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 http://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.

After your document is rendered, 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.

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:

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

Happy theming!

Resources and help

Now that you have applied a custom theme to your AsciiDoc document, you may want to learn more about the AsciiDoc syntax and the growing variety of integrations, backends, and customizations the Asciidoctor project is developing.

Need an overview of the AsciiDoc syntax?

Want to dive deep into all of Asciidoctor’s features?

Interested in writing your next presentation with Asciidoctor?

Additional guides are listed on the Documentation page. Also, don’t forget to join the Asciidoctor mailing list, where you can ask questions and leave comments.