= giblish Generate docs from asciidoc files in a git repo image::https://travis-ci.com/rillbert/giblish.svg?branch=master[build status] == 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 some handy tools for easier navigation of the resulting files. The tools include: * An index page listing all rendered documents with clickable links * Document ids - Note: the implementation of this is giblish-specific and thus you need to render your adoc files using giblish to make this work as intended. 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 sourc 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). * A (stripped-down but nonetheless useful) text-search of your documents (requires that you view your docs via a web-server. * 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 uses the awesome *asciidoctor* and *asciidoctor-pdf* projects under the hood. Thank you @mojavelinux and others for making these brilliant tools available!! == Installation gem install giblish == Some random notes When using giblish for generating docs the following applies: * giblish *will overwrite* files with the same name in the destination directory. * make sure that the git working tree and index of the source git repo are clean when generating docs from a git repo. * 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. == Usage Examples .Get available options ==== giblish -h ==== .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. ==== .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 `` dir. An index page named `index.html` is generated in each `my_dst_root/` dir. An index page named `index.html` is generated in each `my_dst_root/` dir. An index page named `index.pdf` is generated in each `my_dst_root/