giblish 0.7.0 → 0.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c845d2e0c00221f3474469a435157b178894d2af53f8e316f4a555d9480643c6
-  data.tar.gz: a1e5204459599f4d270342d0e8bcf72ee4d36b8440b2ff8499b2428fc543972d
+  metadata.gz: 19bcb7fd2f476219f4f104e6e86a8688a3729225444e18d8c0c67e9288a42835
+  data.tar.gz: 2c1d85d59fe970d2fd5739fc1e1f2aa3099d128514bea3e3d8fb810205b11491
 SHA512:
-  metadata.gz: 1c498054328dca32d192d16e7bbfea061417d7835e3ab80e86c998c1e705701cfef9d0ebdfd39cbfef23b954d56fb0d5e111b110def298fb96eddd7c6cecdd41
-  data.tar.gz: f8c52b147ff9a8134fb0829b69eb48cdade6518840253cf5e9b5ef66ea439a2b26d0d14a20b20a3b84b76c63408c59a52dab0363495f951da51d784d5b5b2335
+  metadata.gz: d56e1b40199396e95ad66f9a1f319ff42efd6aac68db62e3e9c5b8ff593ef79f6e155999ad83fce8666c04e8f674dd8c073b305e0a33d5dde738c04a4f09fb4a
+  data.tar.gz: df30010468ce07b912cb4d2f75e66db05a3396452d15436e52b18516408b9b67b052829520d149c0c101be12615752a4fcfb4ef0950aecef91eb990132cc34c9

data/README.adoc

@@ -0,0 +1 @@
+./docs/README.adoc

data/Rakefile

@@ -1,4 +1,3 @@
-require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|

data/docs/README.adoc

@@ -0,0 +1,388 @@
+= 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 <<usage_examples>>.
+
+=== 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:://<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 the `css`, `fonts` and `images` directories found under
+   `<working_dir>/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
+   `<working_dir>/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/<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.
+
+=== Publish the asciidoctor.org documents with text search
+
+giblish can be used to generate html docs suitable for serving via a web
+server (e.g. Apache). You can use the cgi script included in the giblish
+gem to provide text search capabilities.
+
+Here is an example of how to publish the docs in the official asciidoctor.org git
+repo to a web server, including index pages and text search.
+
+NOTE: No consideration has been taken to how permissions are set up on the web server.
+Just running the below commands as-is on e.g.a standard apache set-up will bail out
+with 'permission denied' errors.
+
+==== Generating the html documents
+
+The example assumes that you have one machine where you generate the documents and another
+machine that runs a web server to which you have ssh access.
+
+The generated docs shall be accessible via _www.example.com/adocorg/with_search_
+
+You need to provide two pieces of deployment info to giblish when generating the documents:
+
+ * the uri path where to access the deployed docs (/adocorg/with_search in this example)
+ * the path in the local file system on the web server where the search data can be accessed
+   (/var/www/html/site_1/adocorg/with_search in this example)
+
+The following commands will generate the asciidoctor.org documentation and deploy the result
+to the web server.
+
+ . Clone the asciidoctor doc repo to your development machine
++
+ git clone https://github.com/asciidoctor/asciidoctor.org.git
+
+ . Generate the html documentation with the correct deployment info
++
+ giblish -j '^.*_include.*' -m -mp /var/www/html/site_1/adocorg/with_search -w /adocorg/with_search -g master --index-basename "myindex" asciidoctor.org/docs ./generated_docs
++
+Explanation of the parameters and arguments::
+ * *pass:[-j '^.*_include.*']* - exclude everything in the __include_ directory. (the
+                                 asciidoctor.org repo stores partial docs here).
+ * *-m* - assemble the necessary search data to support text search and include this data as part of
+          the generated documents.
+ * *-mp /var/www/html/site_1/adocorg/with_search* - the file system path on the deployment machine where
+                                                    the search data is located
+ * *-w /adocorg/with_search* - the uri path to the deployed docs
+ * *-g master* - publish all git branches that matches the regexp 'master' (i.e. only the 'master'
+                 branch).
+ * *--index-basename "myindex"* - change the default name (index) that giblish uses for the generated
+                                  index page. This is needed since asciidoctor.org contains an
+                                  "index.adoc" file that would otherwise be overwritten by giblish.
+ * *asciidoctor.org/docs* - the root of the source document tree.
+ * *./generated_docs* - a temporary storage for the generated html docs on the local system.
++
+
+ . Copy the generated files to the web server
+
+ scp -r ./generated_docs rillbert@my.web.server.org:/var/www/adocorg/with_search/.
++
+
+
+==== Copy the text search script to the web server
+
+This only needs to be done once (or if a new version of giblish breaks the currently used API).
+
+IMPORTANT: The current version of giblish expects the script to be found at the URI path
+`/cgi-bin/giblish-search.cgi`. This might be customizable in future versions but is currently
+hard-coded. Thus, if your web-server serves pages at www.mywebsite.com, the search script must be
+accessible at www.mywebsite.com/cgi-bin/giblish-search.cgi
+
+ . Find the server side script that implements text search that is included with
+   giblish
+
+ gem which giblish
++
+
+In my case this returns `/var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib/giblish.rb`. This means that I will find the script in the same directory, i.e. `/var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib`.
+
+ . Copy the server side script to the /cgi-bin dir on the web server. In this example the cgi-bin dir
+   is configured to be /var/www/cgi-bin
++
+ scp /var/lib/ruby/gems/2.4.0/gems/giblish-0.5.2/lib/giblish-search.rb rillbert@my.web.server.org:/var/www/cgi-bin/giblish-search.cgi
+
+////
+
+If you
+combine this with a server side git hook that invokes this script after push,
+you will have a way of auto publish your latest documents and/or documents at
+specific git tags. A document management system including nice index pages and
+text search capabilities
+
+=== Generate html from giblish git repo using giblish css
+
+Assuming you have cloned this git repo to `~/github/giblish` you can do:
+
+ giblish -g "master" -r ~/github/giblish/resources ~/github/giblish my_dst_root
+
+The above will check-out all branches matching the regexp "master" 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.
+====
+
+.Generate pdf from giblish git repo using the giblish pdf theme
+====
+Assuming you have cloned this git repo to `~/github/giblish` you can do:
+
+ giblish -f pdf -g "master" -r ~/github/giblish/resources ~/github/giblish my_dst_root
+
+The above will check-out all branches matching the regexp "master" and convert
+the .adoc or .ADOC files under the dir `my_src_root` to pdf and place the
+resulting files under the `my_dst_root/<branch_name>` dir.
+
+An index page named `index.pdf` 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.
+====
+////
+

data/docs/setup_server.adoc

@@ -1,67 +1,202 @@
-= Setup web site powered by giblish
+= Publish asciidoc docs in git repos using giblish
 :imagesdir: setup_server_assets
 :numbered:
+:toc:
 
 == Purpose
 
-To describe how to setup a web site with documents automatically generated from a git repo.
+To describe how to use giblish as a tool for creating a static web site with documents that are automatically generated each time a contributer push changes to a git repo.
 
-== Toolchain
+If you want to dive straight in and setup one of the scenarios below, jump to <<setup_instructions>>, otherwise read on for some examples and considerations.
 
- * git
- * giblish
- * git server side hooks to kick-off the document rendering after a git push.
- * a tool that can execute scripts after a git push. *Jenkins* is used in this instruction. Some advantages over calling giblish directly from a git hook:
- ** the document rendering is asynchronous to the git push from the client.
- ** the script executed by Jenkins (the 'pipeline' in Jenkis lingo) can be stored and versioned in the same git repo as the documents to be rendered.
- * a web server to publish the rendered html documents.
+=== Example usages
 
-=== Sequence for rendering documents
+TBD
 
-The following image shows how the sequence from user commit to rendered documents.
+== Two deployment scenarios
 
-image::Render Documents.png[]
+This text covers two deployment scenarios; one using a git hook together with a simple (well) shell script, and one using a git hook together with Jenkins.
+
+They have both been tested on Linux servers (Ubuntu). Most of the tools and scripts should work on a Windows server as well but might need some tweaking and is, again, not tested.
+
+=== Git hook and shell script
+
+This requires the least number of installed components to work. An overview of the scenario is given below.
+
+.Deploy using git hook and shell script
+image::deploy_with_hooks.svg[]
+
+The components needed on the server are:
+
+Master Repo::
+The common (bare) git repo used by all content writers to push updates to. This repo needs to be setup with a server-side hook (_post-receive_) that are executed by git after each push to the repository.
+
+Staging Repo::
+A git repo that mirrors the _Master Repo_ and fulfills two functions:
+
+ . provide a checked-out working tree with the source files (adoc files).
+ . provide a script that uses giblish to publish the adoc files in the working tree as HTML files that reside at a place in the file system where the web server can access them.
+
+Web Server::
+Apache, Ngnix or other web server that provides clients with HTML pages located somewhere on the file system on the server (eg under /var/www/... )
+
+==== Considerations
+
+Possible advantages::
+ * it has few dependencies on external tools, only git, giblish and a web server are needed for this to work.
+ * giblish provides templates for both the `post-receive` hook and the `publish_html` script that can be tailored to your specific setup quite easily.
+
+Possible drawbacks::
+ * The hook and publish scripts provided with giblish runs syncronously at each push from a _Doc Writer_ to the _Master Repo_. The time it takes to generate the HTML docs from the adoc source will thus be added to each push to the _Master Repo_.
+ * You need to manually setup the _Staging Repo_ on the server and this is a bit more 'hackish' than letting a build orchestrator tool implement a proper 'build' of your documents. You might for example end up with race conditions if two pushes to the _Master Repo_ are done close in time.
+ * The `publish_html` script provided with giblish only uses the currently checked-out branch on the _Staging Repo_ (typically 'master') to generate the HTML docs. It is non-trivial to add multiple-branch generation to the provided script.
+
+=== Using Jenkins / git hook combo
+
+This setup adds a Jenkins (or similar build orchestrator) installation so it is more tools to setup but offer more flexibility and performance. It is also more robust and thus more 'production friendly'.
+
+If you are already doing some kind of development, chances are that you already have this kind of setup as a CI pipeline.
+
+.Deploy using Jenkins
+image::deploy_with_jenkins.svg[]
+
+The components needed on the server are:
+
+Master Repo::
+The common (bare) git repo used by all content writers to push updates to. This repo needs to be setup with a server-side hook (_post-receive_) that are executed by git after each push to the repository.
+
+Jenkins instance::
+A running instance of Jenkins and one or more defined build jobs that use giblish to build the HTML documents.
+
+Web Server::
+Apache, Ngnix or other web server that provides clients with HTML pages located somewhere on the file system on the server (eg under /var/www/... )
+
+==== Considerations
 
-=== Sequence for viewing documents
+Possible advantages::
+ * Using Jenkins enables a lot of flexibility and scaleability. You can setup multiple jenkins agents to increase performance, you can define many build jobs where each job builds either a particular branch from a particular git repo or many branches from one or many repos.
 
-This is just the standard way of accessing a web site. The html page served by the web server will be the latest generated html page.
+Possible drawbacks::
+ * You need to be familiar with, and maintain, the Jenkins instance.
 
-image::View Documents.png[]
+[[setup_instructions]]
+== Setup instructions
 
-== Server requirements
+Follow the instructions below to get this running on your server.
 
-The server that will render the documents need the following tools installed:
+=== Some preliminary notes
 
- * git
- * giblish
+Permissions and security::
+These instructions does not give any advice on setting up permissions in a way that is suitable for your use case. You should however, give this an appropriate amount of consideration. You need to set the permissions so that the relevant tools and scripts can perform their expected tasks without constituting security vulnerabilities on your server. You might want to consider setting up specific user accounts/groups to achieve this but this is outside the scope of this text.
 
-The server that runs Jenkins will (of course) need Jenkins installed.
+Server side git hooks::
+git supports several hooks that are executed at different points in the sequence of committing and pushing changes to a repository. This feature is used in both scenarios below to provide the trigger for generating the HTML document. For details on git hooks see https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[this doc].
 
-=== Setup server for both Jenkins and doc rendering on Ubuntu 16.04
+[[common_setup]]
+=== Initial setup
 
-The easiest setup is to use the same server to run Jenkins and to render the documents. For an Ubuntu 16.04 installation, you can install the needed tools as follows:
+These steps are common to both deployment scenarios.
 
- * install git `sudo apt install git`
- * install Jenkins See https://www.digitalocean.com/community/tutorials/how-to-install-jenkins-on-ubuntu-16-04[this doc].
- * install giblish `sudo gem install giblish`
+giblish setup::
+ . Install ruby on the _Server_ (a version no more than 18 months old)
+ . Install giblish on the _Server_ using `gem install giblish`
 
+git and gitrepo setup::
+ . Install git on the _Server_.
+ . Setup the *bare* _Master Repo_ on the _Server_ by either.
+ .. Copy a bare repo you already use to the _Server_ file system.
+ .. Init a new repo using `git init --bare <your_repo_name>` somewhere on the _Server_ file system.
++
+NOTE: If you start with an empty, bare, _Master Repo_ on the _Server_, it is a good idea to directly clone it to your local machine, commit some content to the 'master' branch and push the result back to the _Master Repo_. An empty, bare repo does not even contain a 'master' branch from the start and this can lead to some edge cases that complicate things.
 
-== server side git hooks
+ . Setup the _Staging Repo_ on the _Server_ by cloning the _Master Repo_ to a suitable folder in the _Server_ file system, ex:
++
+.Setup a staging repo in your home folder on the _Server_
+====
+ cd ~
+ git clone file:///usr/local/master_repo.git
+====
 
-git supports hooks in several parts of the sequence of getting changes ommitted and pushed to a remote repo. For details on git hooks see https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[this doc]. See <<post-update-hook>> An example of a `post-update` hook that triggers Jenkins
+=== Setup the git hook and shell script scenario
 
+First, follow the steps described in <<common_setup>>. Then proceed with the steps below.
+
+script setup::
+ . Find out where the template scripts for the `post-receive` and the `publish_html.sh` scripts are located by running `gem which giblish`. Strip of the `lib/giblish.rb` from the end of the returned path and `cd` to the resulting folder. There should be a subfolder named `scripts` under which you can find the template scripts somewhere.
++
+.Installation on Ubuntu 16.04
+====
+On a server running Ubuntu 16.04, `gem which giblish` returns:
+
+ /var/lib/gems/2.6.0/gems/giblish-0.7.0/lib/giblish.rb
+
+and the template scripts can thus be found somewhere under
+
+ /var/lib/gems/2.6.0/gems/giblish-0.7.0/scripts
+====
+
+ . Copy the `publish_html.sh` script to a suitable folder in your _local repo_ on your _local machine_ (e.g. under `<your_local_repo_root>/scripts`).
+ . Tweak the configuration variables in the script to fit your use case.
+ . Commit and push script to the _Master Repo_ on the _Server_.
+ . Copy the `post-receive` script to the `hooks` folder in your bare _Master Repo_.
+ . Tweak the configuration variables of the copy to suite your use case.
+ . Set the execute permission using `chmod +x post-receive`
+
+stylesheet setup::
+The template scripts assume that the the css used to style the generated HTML is located under `<repo_root>/scripts/resources/css` and is called `giblish.css`. To enable a styling of your liking, either create this folder/css file in your repo at that exact place or tweak the `html_publish.sh` script to use another location/css file name for the styling.
+
+other tweaking::
+You can tweak the `publish_html.sh` script to use other features of giblish/asciidoctor, such as docid's, docinfo support and others. To do this, change the flags and arguments used to invoke giblish from the `publish_html.sh` script accordingly.
+
+=== Setup the git hook and Jenkins scenario
+
+First, follow the steps described in <<common_setup>>. Then proceed with the steps below.
+
+TBD
+
+==== Sequence for generating documents
+
+The following image shows how the sequence from user commit to generated documents.
+
+.Sequence diagram for generating docs from adoc
+image::Render Documents.png[]
 
 [appendix]
-[[post-update-hook]]
-== post-update hook
+== Scripts
+
+.The giblish `publish_html.sh` template script
+[%collapsible]
+====
+[source,bash]
+----
+include::../scripts/publish_html.sh[]
+----
+====
+
+.The giblish `post-receive` template git hook
+[%collapsible]
+====
+[source,bash]
+----
+include::../scripts/hooks/post-receive[]
+----
+====
+
+=== post-update hook
 
 Below is an example of a `post-update` hook that triggers Jenkins jobs after a push to a git repo. This hook should be installed on the server side git repository to trigger Jenkins builds
 
 .Example of a git hook triggering Jenkins builds
+[%collapsible]
+====
+[source,bash]
 ----
 include::../docgen/scripts/githook_examples/post-update.example[]
 ----
+====
 
-== Jenkins pipeline script
+=== Jenkins pipeline script
 
 Below is a very basic example of a Jenkins pipeline that triggers giblish to render html and pdf documents located in a specific directory in a git repository.
+
+TBD