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.|
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.
In order to build the stylesheets, you must download the Asciidoctor stylesheet factory repository and install the Compass and Foundation gems.
Download or clone the Asciidoctor stylesheet factory repository.
It does not matter where you save the project on your system.
Run Bundler to install the Compass and Foundation gems.
$ bundle install
bundlecommand 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 installcommands if you use Bundler.
Once you have the gems installed, you can build the stylesheets.
To build the stylesheets:
Navigate to the Asciidoctor stylesheet factory directory on your system.
$ 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.
Let’s practice applying a stylesheet to a simple AsciiDoc file. If you’re unfamiliar with the general commands needed to convert and style a document created with the AsciiDoc syntax, you may want to review the How Do I Convert My Document? guide before proceeding.
Create an AsciiDoc file like the one below.
Save the file as mysample.adoc.
= Introduction to AsciiDoc Doc Writer <firstname.lastname@example.org> 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.
Now it’s time to pick the stylesheet you want to apply to your content when it is rendered in the browser.
In your file navigator, navigate to the stylesheets/ directory.
Or, using a console, change to the stylesheets/ directory and list the available stylesheets using the
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.
Navigate to the directory where you saved mysample.adoc.
Specify the stylesheet you want applied with the
Tell the processor where the specified stylesheet is located with the
$ 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 convert 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 converted document.
<link rel="stylesheet" href="../stylesheets/colony.css">
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:
$ python -m SimpleHTTPServer 4242
$ ruby -run -e httpd . -p 4242
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:
Imports the theme settings, which includes default variables and resets
Imports the AsciiDoc components
Defines any explicit customization
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.|
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.
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
Assign the stylesheet file’s name to the
Enter your document file’s name.
Alternatively, let’s set the
stylesheet attribute in the header of
= 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 https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.
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.
Our AsciiDoc document,
mysample.adoc, is saved in the
= 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 https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.
mysample.adoc, its HTML output (
mysample.html), which includes the embedded
mystyles.css stylesheet, is created in the
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
= 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 https://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 converted, notice that a copy of
mystyles.css was not created in the
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.
The asciidoctor-skins repository has additional stylesheets that can be used to theme your AsciiDoc-based documentation. These stylesheets are specifically created for users who want to style their documents without having to dive into writing custom CSS. The stylesheets in asciidoctor-skins import the default stylesheet first, then overlay an alternate theme (in other words, a “skin”).
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?
Also, don’t forget to join the Asciidoctor mailing list, where you can ask questions and leave comments.