asciidoctor / Asciidoctor Stylesheet Factory
Labels
Projects that are alternatives of or similar to Asciidoctor Stylesheet Factory
= 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!