asciidoctor-stylesheet-factory

asciidoctor-stylesheet-factory copied to clipboard

= Asciidoctor stylesheet factory Dan Allen :toc: :source: https://github.com/asciidoctor/asciidoctor-stylesheet-factory

The purpose of this project is to generate the default stylesheet that gets bundled with Asciidoctor gem. The default stylesheet is configured by the [.path]sass/asciidoctor.scss file and the files it includes. Although the project can be used to generate additional themes, those themes are not maintained.

== Themes for download

This project does not offer pre-built stylesheet themes you can use with your Asciidoctor projects. And there is no official CDN for Asciidoctor stylesheets.

If you're looking for additional themes, check out the https://github.com/darshandsoni/asciidoctor-skins[Asciidoctor Skins] project. That project offers numerous pre-built stylesheets based on the default stylesheet that you can download and use locally.

== Foundation

The stylesheets in this project are built using http://compass-style.org[Compass], a CSS authoring framework that uses http://sass-lang.com[Sass] to generate CSS files. The styles and components are generated by http://foundation.zurb.com[Foundation 4], an awesome and flexible CSS component framework that ensures your stylesheet is cross-browser friendly and mobile friendly.

== Setup and compilation

To setup the project, make sure you have Ruby, RubyGems and, optionally Node and Bundler. Next, run Bundler to install the required gems:

$ bundle

That command is equivalent to executing:

$ gem install --version '0.12.7' compass $ gem install --version '4.3.2' zurb-foundation

Then run npm to install the required Node modules:

$ npm i

That command is equivalent to executing:

$ npm i [email protected] [email protected] cssshrink

Once you have the gems and Node modules installed, you can build the stylesheets.

== Build the default stylesheet

The main purpose of this repository is to build the default stylesheet. The default stylesheet is generated using the [.path]build-stylesheet.sh command.

To run this command, you need the following programs:

• bundler
• cssshrink
• cat
• sed
• ruby

Once those are installed, run the command as follows:

$ ./build-stylesheet.sh

This command will create asciidoctor.css and asciidoctor.min.css in the root of this project.

== Build the other stylesheets

To build the stylesheets, simply run:

$ compass compile

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

== Create sample documents

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 [.path]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 [.path]sample.html in your browser and checkout the result!

== 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:

python -m SimpleHTTPServer 4242

== Create a new theme

Themes go in the [.path]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 [.path]sass/hipster.scss:

[source,scss]

@import "settings/hipster"; @import "components/asciidoc"; @import "components/awesome-icons";

NOTE: You don't have to include the underscore prefix when importing files.

You can add any explicit customizations below the import lines.

The variables you can set in [.path]_sass/settings/hipster.scss are a combination of the {source}/blob/master/sass/settings/_settings.scss.dist[Foundation 4 built-in global settings] and {source}/blob/master/sass/settings/_defaults.scss[global settings and imports for the AsciiDoc components].

Happy theming!