search

asciidoctor / asciidoctor-stylesheet-factory

!DEPRECATED! This was the utility project for producing the default stylesheet for the HTML converter in Asciidoctor. The source of the default stylesheet now lives in the main Asciidoctor repository.
Other
175 stars 87 forks source link

readme

= 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 color@0.11.4 csscolormin@0.0.5 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:

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 doc@example.com

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

== First Section

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

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!