= giblish :idseparator:- :idprefix: :numbered: image::https://travis-ci.org/rillbert/giblish.svg?branch=master["Build Status", link="https://travis-ci.org/rillbert/giblish"] == 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 adds some handy tools for easier navigation of the resulting files. An example of how giblish can generate the master branch of the official asciidoc.org documentation git repo can be found at http://www.rillbert.se/adoc/examples/adocorg/master/myindex.html The added tools include: * An index page listing all rendered documents with clickable links. * A (stripped-down but nonetheless useful) text-search of your (html) 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). * 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 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). NOTE: giblish shall be considered stable from a usage perspective, please report bugs to the issue tracker. It's API however, is to be considered alpha, meaning that future versions may break the current usage of cmd line flags, generated artifacts, styling or other functionality. == 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 Want to get started straight away? Go directly to the <>. === 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. == Text search implementation The text search enables a user to search for a text string and receive matching sections in the documentation tree. giblish ties together the following three pieces to enable the text search: . the source text of all adoc files together with a JSON file that maps sections to their line numbers. ** giblish collects this 'search data' when it generates the html files to the destination directory. The JSON file and all adoc source files are copied to a well-known place in the destination tree (see below). . an html form somewhere on the rendered pages where the user can input search queries and initiate a search. ** giblish injects such an html form in the generated index page when the user specifies the '-m' switch. . a server side script that handles a user request to search the documents for a specific text string and presents the result to the user. ** this gem contains an implementation of such a server side script. It is intended to be run as a cgi script and requires ruby and grep to be installed on the server where it runs. === Search data and html form parameters giblish will copy all search data to a 'search_assets' dir just under the destination root. This is illustrated below. .When rendering documents from a git branch dst_root_dir |- branch_1_top_dir | |- index.html | |- file_1.html | |- dir_1 | | |- file2.html |- branch_2_top_dir |- branch_x_... |- web_assets |- search_assets | |- branch_1_top_dir | |- heading_index.json | |- file1.adoc | |- dir_1 | | |- file2.adoc | |- ... | |- branch_2_top_dir | | ... .When rendering documents not in a git branch dst_root_dir |- index.html |- file_1.html |- dir_1 | |- file2.html |... |- web_assets (only if a custom stylesheet is used...) |- search_assets | |- heading_index.json | |- file1.adoc | |- dir_1 | | |- file2.adoc | |- ... == 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: . 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. . Refer to a document using the syntax pass:[<<:docid:#DOC_ID#>>]. . Run giblish with the -d switch when generating documents. Using doc ids makes it possible for giblish to do two things: . Make the reference from one document to another work even if one of the documents have been moved within the source tree. . 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. === 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:: [source,asciidoc] ---- = Document one :toc: :numbered: :docid: D-001 == Purpose To illustrate the use of doc id. ---- Example document two:: [source,asciidoc] ---- = Document two :toc: :numbered: :docid: D-002 == Purpose To illustrate the use of doc id. You can refer to document one as <<:docid:D-001>>. This will display a clickable link with the doc id (D-001 in this case). You can basically follow the same syntax as the normal asciidoc cross-ref, such as: * <<:docid:D-002#purpose>> to refer to a specific section or anchor. * <<:docid:D-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. [[usage_examples]] == Usage Examples Here follows a number of usages for giblish in increasing order of complexity. === Get available options giblish -h === 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. === 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. === Using a custom css for the generated html Generate html that can be browsed locally from file:://. 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 the `css`, `fonts` and `images` directories found under `/path/to/my/resources` to `my_dst_root/web_assets` * link all generated html files to the css found at `/web_assets/css/mylayout.css` === 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. * 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 generated pdf will use the theme found at `/path/to/my/resources/themes/mylayout.yml` === 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/` 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. 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/