Purpose

giblish is used to convert a source directory tree containing AsciiDoc files to a destination directory tree containing the corresponding html or pdf files and add a handy index page for the converted files.

If the source directory tree is part of a git repository, giblish can generate separate html/pdf trees for branches and/or tags that match a user specified regexp (see examples below).

Dependencies and credits

Giblish is basically a wrapper (with some extra candy) around the awesome asciidoctor and asciidoctor-pdf projects. Thank you @mojavelinux and others for making these brilliant tools available!!

Installation

gem install giblish

Usage Examples

Example 1. Get available options

giblish -h

Example 2. Giblish 'hello world'

giblish my_src_root my_dst_root

The above will convert all .adoc or .ADOC files under the dir my_src_root to html and place the resulting files under the my_dst_root dir. An index page named index.html is generated in the my_dst_root dir containing links and some info about the converted files.

The default asciidoctor css will be used in the html conversion.

Example 3. Using a different css

giblish -r ./path/to/my/resources -s mylayout my_src_root my_dst_root

The above will convert all .adoc or .ADOC files under the dir my_src_root to html and place the resulting files under the my_dst_root dir. An index page named index.html is generated in the my_dst_root dir containing links and some info about the converted files.

A css named mylayout.css must be found in the dir <working_dir/path/to/my/resources/css. The resulting html files will link to this css. Fonts and images used from the css must be found under <working_dir/path/to/my/resources/fonts and <working_dir/path/to/my/resources/images respectively.

Example 4. Generate docs from multiple git branches

giblish -g "feature" my_src_root my_dst_root

The above will check-out all branches matching the regexp "feature" and convert the .adoc or .ADOC files under the dir my_src_root to html and place the resulting files under the my_dst_root/<branch_name> dir.

An index page named index.html is generated in each my_dst_root/<branch_name dir containing links and some info about the converted files.

A summary page containing links to all branches will be generated directly in the my_dst_root dir.