Using gitbook to generate the documentation
Last updated
Was this helpful?
Last updated
Was this helpful?
There is a good documentation available on
but it is a little bit older so here are some additional steps you need to do.
There is also an issue with a lot of the features of the newer version of Gitbook. This is for example embedded URL or this Hint even. This will cause the cli version of gitbook to fail. For example
will cause Template render error: ( ..../SnowWhite/this-and-that/using-gitbook-to-generate-the-documentation.md) [Line 7, Column 2] unknown block tag: embed make: * [build] Error 1
All in all I didn't pursue this further due to the above mentioned issues at the moment but I kept it here. It might be useful to others.
You need:
Xcode
brew
git
make
To be able to install npm and node you need to change some rights on the filesystem first:
If you than run the install of npm and node you will find that node will not work afterwards as it requires access to /usr/local/include.
At least in my case the directory didn't exist so I created it and took over.
and than you can install node and npm
So now you can start with gitbook-cli
You start the installation with
but you are not done yet.
Now you need to finish the gitbook install with
After some time you can check with
which version you have installed.
Install Calibre after downloading it from above URL
Now link the ebook-convert tool to the right place
If you use the make file which comes with this repo you can now do:
Build static HTML.
Build PDF.
Build epub for iDevice.
Build mobi for Kindle.
Review result at local.
Clean the environment
And now we just need to configure Github to show the documentation on Github Pages.
Before you can configure github so, make sure that you already have a /docs folder in your repository.
Go to the Settings of your repository.
Now scroll down to Github Pages and select master branch /docs folder.
After that pick a theme you would like to use. I went with the minimal theme.
Now you should be able to publish your documentation to Github Pages.
If you want to have epub, pdf etc versions of the documentation read further, if not jump ahead to
gitbook requires a commandline tool from to create epub, pdf or mobi versions of the documentation.