72. Stylesheet Factory

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 only compatible with Asciidoctor 0.1.2 and greater.

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

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

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

72.2. Creating a 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.

72.3. Applying a Stylesheet

Let’s practice applying a stylesheet to a simple AsciiDoc file.

  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.

72.4. 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 inspect the mysample.html document, you should see that the stylesheet is embedded in the converted document.

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.

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