This project is a factory for stylesheets that can be used to style the HTML generated by an AsciiDoc processor (specifically the html5 backend). In addition to being a general purpose AsciiDoc stylesheet generator, it is used to generate the default stylesheet that is bundled with Asciidoctor.
The stylesheets in this project 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 friendly and mobile friendly.
To setup the project, make sure you have Ruby, RubyGems and, optionally, Bundler. Next, run Bundler to install the required gems:
$ bundle install
That command is equivalent to executing:
$ gem install --version '0.12.7' compass $ gem install --version '4.3.2' zurb-foundation
Once you have the gems installed, you can build the stylesheets.
To build the stylesheets, simply run:
$ compass compile
The stylesheets are compiled from the Sass source files in the sass/ folder and written to the stylesheets/ folder. You can then reference the stylesheets in stylesheets/ from your HTML file.
First, create a sample AsciiDoc file, such as:
= Introduction to AsciiDoc Doc Writer <[email protected]> A preface about http://asciidoc.org[AsciiDoc]. == First Section * item 1 * item 2 [source,ruby] puts "Hello, World!"
Tip
|
Alternatively, you can use this README as an example. |
Then, use AsciiDoc or Asciidoctor to generate HTML that uses one of the stylesheets from the stylesheets/ directory:
$ asciidoctor -a stylesheet=./stylesheets/asciidoctor.css sample.adoc
If you want to activate syntax highlighting in the code, add this argument:
-a source-highlighter=highlightjs
Now just browse to sample.html in your browser and checkout the result!
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
Themes go in the sass/ folder. To create a new theme (e.g., 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 customizations
-
- 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";
Note
|
You don’t have to include the underscore prefix when importing files. |
Note
|
The awesome-icons component is only applicable to HTML generated by Asciidoctor >= 0.1.2 with the icons attribute set to awesome. |
You can add any explicit customizations 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.
Happy theming!