giblish

giblish converts a source directory tree containing AsciiDoc files to a destination directory tree containing the corresponding html or pdf files. It adds some handy tools for easier navigation of the resulting destination tree.

Two-liner conversion

# install giblish (requires a working ruby installation on the system)
gem install giblish
# convert all adoc files recursively under 'my/src' and place them (recursively) under "the/dest"
$ giblish my/src the/dest

Table of Contents

• 1. Examples
• 2. giblish features
• 3. Dependencies and credits
• 4. Installation
• 5. Document ids and the reference graph
• 6. Usage Examples
• 7. Contributing

1. Examples

Important

The examples below are not the official documentation for the corresponding projects.

Project	Link to example	Comment
The giblish documentation	here	The documentation of giblish (same as you find in GitHub).
Raspberry Pi documentation	example	The project’s official documentation site uses Jekyl for site generation, the link points to a mirror where some small tweaks to the docs were made to make them suitable for generation with giblish.
The old asciidoctor docs	example	An example of how giblish can generate the master branch of the old, deprecated official asciidoc.org documentation git repo.

2. giblish features

The features of giblish include:

• Simple conversion of whole document trees into both html and pdf.

• Customizable index pages that list all rendered documents with clickable links.

• Generate separate destination trees per branch in a git repo in one go (see examples below).

• Document ids - a (non-standard) way of referencing other documents in the same tree, you can use document ids to:

  • Reference one doc in the source tree from another doc without depending on file names or relative paths. The referenced doc can thus be moved within the source tree or change its file name and the reference will still be valid.

  • Validate doc id references during document rendering and thus be alerted to any invalid doc id references.

  • Let giblish generate a clickable graph of all document references (requires graphviz and the 'dot' tool).

• Text-search - a stripped-down, but nonetheless useful, text-search of your html documents. This requires that you publish your docs to a web-server and setup an application on that same web-server. giblish provides most of the scaffolding though.

3. Dependencies and credits

Giblish uses the awesome asciidoctor and asciidoctor-pdf projects under the hood. Thank you @mojavelinux and others for making these brilliant tools available!!

The official documentation of these tools as well as extensive information about the AsciiDoc syntax can be found at https://docs.asciidoctor.org

4. Installation

gem install giblish

Want to get started straight away? Go directly to the Usage Examples.

4.1. Some caveats

When using giblish for generating docs the following applies:

• giblish will overwrite files with the same name in the destination directory.

• giblish requires that the git working tree and index of the repo containing source documents are clean when generating documentation.

• giblish will make explicit check-outs of all the branches or tags that matches the selection criteria. The working dir of the source git repo will thus have the last branch that giblish checked-out as the current branch after doc generation.

5. Document ids and the reference graph

Note	This is a non-standard extension of asciidoc. If you use this feature, you will need to generate your documents using giblish to make this work as intended.

giblish extends the cross reference concept in asciidoc with a document id mechanism. To use this, you need to:

1. Add a :docid: entry in your document’s header section. The doc id can consist of up to 10 characters and must be unique within the set of documents generated by giblish.

2. Refer to a document using the syntax <<:docid:a_doc_id>> where a_doc_id is the doc id of a document in the same git repo.

3. Run giblish with the -d switch when generating documents.

Using doc ids makes it possible for giblish to do two things:

1. Make references from one document in the tree to another work even if one of the documents have been moved within the document source tree.

2. Produce a clickable 'map' of the generated documents where the different references are clearly seen. This feature require that the 'dot' tool, part of the graphwiz package is installed on the machine where giblish is run.

The use of the -d switch makes giblish parse the document twice, once to map up the doc ids and all references to them, once to actually generate the output documentation. Thus, you pay a performance penalty but this should not be a big inconvenience since the generation is quite fast in itself.

5.1. Example of using the docid feature

Consider that you have two documents located somewhere in the same folder tree, document one and document two. You could then use the docid feature of giblish to refer to one document from the other as in the example below.

Example document one

= Document one
:toc:
:numbered:
:docid: AB-001

== Purpose

To illustrate the use of doc id.

Example document two

= Document two
:toc:
:numbered:
:docid: AB-002

== Purpose

To illustrate the use of doc id. You can refer to document one as <<:docid:AB-001>>. This will display a clickable link with the doc id (AB-001 in this case).

You can use the same syntax as the normal asciidoc cross-ref but replace 'xref' with ':docid:' as shown below:

 * <<:docid:AB-002#purpose>> to refer to a specific section or anchor.
 * <<:docid:AB-002#purpose,The purpose section>> to refer to a specific section and display a specific text for the link.

The above reference will work even if either document changes location or file name as long as both documents are parsed by giblish in the same run.

6. Usage Examples

A number of use cases for giblish in increasing order of complexity.

6.1. Get available options

giblish -h

6.2. Giblish html 'hello world'

giblish my_src_root my_dst_root

• 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.

• generate an index page named index.html that contains links and some info about the converted files. The file is placed in the my_dst_root dir.

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

6.3. Giblish pdf 'hello world'

giblish -f pdf my_src_root my_dst_root

• convert all .adoc or .ADOC files under the dir my_src_root to pdf and place the resulting files under the my_dst_root dir.

• generate an index page named index.pdf that contains links and some info about the converted files. The file is placed in the my_dst_root dir.

The default asciidoctor pdf theme will be used in the pdf conversion.

6.4. Customize the index pages generated by giblish

Add a file idx_template.erb under a directory of your choice, in this example style_resources is used. An example of the available customization options is this file from the giblish test data set.

Invoke giblish with the resource directory set using the -r flag.

giblish -r style_resource my_src_root my_dst_root

Your erb template is used to generate the index page(es).

6.5. Using a custom css for the generated html

Generate html that can be browsed locally from file:://<my_dst_root>.

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

• 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.

• generate an index page named index.html that contains links and some info about the converted files. The file is placed in the my_dst_root dir.

• copy everything found under <working_dir>/path/to/my/resources to my_dst_root/web_assets

• link all generated html files to the mylayout.css found somewhere under /web_assets

6.6. Using a custom pdf theme for the generated pdfs

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

• convert all .adoc or .ADOC files under the dir my_src_root to pdf and place the resulting files under the my_dst_root dir. some info about the converted files. The file is placed in the my_dst_root dir.

• the pdfs will be rendered using the theme file named mylayout.yml found somewhere under <working_dir>/path/to/my/resources

6.7. Generate html from multiple git branches

giblish -g "feature" my_src_root my_dst_root

• check-out each branch matching the regexp "feature" in turn

• for each checked-out branch,

  • convert the .adoc or .ADOC files under the dir my_src_root to html.

  • place the resulting files under the my_dst_root/<branch_name> dir.

  • generate an index page named index.html that contains links and some info about the converted files. The file is placed in the my_dst_root/<branch_name dir.

• generate a summary page containing links to a all branches and place it in the my_dst_root dir.

7. Contributing

If you want to contribute to giblish, great :) Use the standard GitHub flow of forking the repo and submit a pull request.

Pull requests must meet the following to be considered for merging:

• Tests have been added for new or updated functionality

• The code has been linted using the standardrb tool.

  • The version of standardrb shall be the same as the one used in the target branch for the PR.

To develop on giblish, you:

1. Install ruby on your local machine (rbenv is a good choice for handling ruby installations)

2. Install necessary dependencies to install the ruby 'mathematica' gem, see eg https://github.com/gjtorikian/mathematical/blob/47041d5492cc7c5f04105031430fb44119406f49/script/install_linux_deps

3. Install graphviz

4. Clone or fork the repository

5. Run the bin/setup script from a bash prompt