Using gitbook to generate the documentation

Installing gitbook-cli on OSX Catalina

There is a good documentation available on GitHub

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 {% embed url="https://github.com/chusiang/how-to-build-the-gitbook-with-gitbook-cli" caption="" %} 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.

Prerequisites

You need:

• Xcode

• brew

• git

• make

Prepare Node Install

To be able to install npm and node you need to change some rights on the filesystem first:

sudo chown -R $(whoami) /usr/local/share/man/man3 /usr/local/share/man/man5 /usr/local/share/man/man7
chmod u+w /usr/local/share/man/man3 /usr/local/share/man/man5 /usr/local/share/man/man7

brew will tell you that this is needed if you run it without these rights and you can just copy / paste it in the terminal if you want.

If you then run the install of npm and node you will find that node will not work afterward 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.

sudo mkdir /usr/local/include
sudo chown $(whoami) /usr/local/include

and then you can install node and npm

brew install node npm

So now you can start with gitbook-cli

Gitbook-Cli Install

You start the installation with

sudo npm install -g gitbook-cli

but you are not done yet.

Now you need to finish the gitbook install with

gitbook install

After some time you can check with

$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

which version you have installed.

If you want to have epub, pdf etc versions of the documentation read further, if not jump ahead to Creating the Documentation with a make file

Epub, PDF and mobi Versions

gitbook requires a commandline tool from Calibre to create epub, pdf or mobi versions of the documentation.

Install Calibre after downloading it from above URL

Now link the ebook-convert tool to the right place

ln -s /Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin/

Creating the Documentation with a make file

If you use the make file which comes with this repo you can now do:

1. Build static HTML.

    $ make

2. Build PDF.

    $ make pdf

3. Build epub for iDevice.

    $ make epub

4. Build mobi for Kindle.

    $ make mobi

5. Review result at local.

    $ make review

6. Clean the environment

    $ make clean

Configuring Github to show your documentation on Github Pages

And now we just need to configure Github to show the documentation on Github Pages.

Before you can configure GitHub, make sure that you already have a /docs folder in your repository.

Go to the Settings of your repository.

Repository Settings

Now scroll down to Github Pages and select master branch /docs folder.

Github Pages Source Configuration

After that pick a theme you would like to use. I went with the minimal theme.

GitHub Pages Theme

Now you should be able to publish your documentation to Github Pages.