What is Gitbook?

GitBook is a modern documentation platform where teams can document everything from products to internal knowledge-bases and APIs.

Checkout the demos below to see how documentations look like with Gitbook:

• https://richdayandnight.github.io/tutorial-gitbook-learning-how-to-learn/
• http://npm.github.io/installation-setup-docs/installing/a-note-on-permissions.html

Why do this? Isn't gitbook already deprecated?

Yes, the first version of Gitbook is no longer maintained. The Gitbook team shifted focus to creating a beautiful online editor that allows you to instantly deploy pages using the https://<username>.gitbook.io/<gitbook_name> pattern, which is great! I totally recommend this if you just want to deploy pages and make them available to public similar to sharing a public google doc. They also provide 10 free spaces (they refer to a Gitbook as a Space).

Getting back to the 'Why do this' let me list this down my reasons (feel free to skip this part if you want to jump right into the process)

• You can get/implement features listed in their paid tier without paying.

• You own the built static pages and you can host these anywhere you want (ex. github pages, heroku, netlify, online web hosting platforms, etc.)
• It's fun. Personally, I had fun tinkering with the whole deployment process.

Process:

Requirements: You will need 3 tools

1. ✅ A Github account
2. ✅ NPM (Node package manager)
3. ✅ Gitbook-cli
4. ✅ Gitbook Editor (optional)

Reference:

Refer to my github repository, if ever you get lost in the steps.

Steps:

1. Create a Git repo

• Click on this to lead you to your personal create repo page

2. Clone repo to local

git clone https://github.com/richdayandnight/tutorial-gitbook-learning-how-to-learn.git

3. Install NPM

Go here https://www.npmjs.com/get-npm to find instructions

4. Install gitbook-cli

npm install -g gitbook-cli

• Check if gitbook-cli is successfully installed by gitbook help
• If gitbook is not recognized as a command you might want to check out your permissions. I encountered this issue and what solved this for me is adding export PATH="$PATH:$HOME/.npm-global/bin" to my ~/.bashrc file and loaded the changes with source ~/.bashrc

5. Create your gitbook

cd tutorial-gitbook-learning-how-to-learn/
gitbook init

The current directory should now contain a README.md and SUMMARY.md. To see how this would look like run:gitbook serve

Notice how there's a new folder created on our root named _book. This will contain the static web pages that we can not only host through github pages, but also any other hosting service online.

6. Import files

For this sample gitbook tutorial, I copied my notes from the Learning How to Learn Course I recently took to our root working directory. (link to notes: https://github.com/richdayandnight/data-science-notebook/tree/master/learning-how-to-learn)

Edit the SUMMARY.md file to link to other markdown files

# Summary
* [Introduction](README.md)
* [Week 1](week1.md)
* [Week 2](week2.md)
* [Week 3](week3.md)
* [Week 4](week4.md)
* [Summary](Summary of Learning How to Learn.md)

7. Add .gitignore

A sample Gitbook .gitignore template is found here. Copy the file and add it to your repo.

8. Push all of this to your master branch

git add -A && git commit -m "first commit"
git push -u origin master

9. There are two ways we can deploy our static site to github pages (I use the latter method in this tutorial [9.2])

9.1 Run an sh script to automate creation of gh-pages

9.2 Manually create a gh-pages branch and Create a gulp task to automate

A. Create gh-pages branch, switch to gh-pages, push gh-pages branch to github repo, and switch again to master branch.

git branch gh-pages
git checkout gh-pages
git push -u origin gh-pages
git checkout master

B. npm init to initialize project (add package.json that will contain our dependencies) and run yarn add gulp gulp-gh-pages gulp-load-plugins --save-dev to install dependencies

npm init
yarn add gulp gulp-gh-pages gulp-load-plugins --save-dev

C. Create a gulpfile.js on the root directory of our repo

D. Run gulp publish to deploy your static web pages to github pages.

gulp publish

10. Check your deployed Gitbook

You can see on your Github repository that a new environment is up.

Head over the environment and then, click view deployment.

Your deployed gitbook will have the url pattern:

https://<username>/<repo-name>

Output

Click here to see the deployed Gitbook on Github

Bonus:

• Install gitbook editor — after Gitbook shifted to their online platform they stopped the updates on their offline editor found here: https://github.com/GitbookIO/editor-legacy. The last update was 5 years ago.

I tried installing the latest release and got this UI.

It functions well and has some nifty features like 1-click preview server (thunder icon on the upper right). However, this editor is a WYSIWYM editor and I was looking for WYSIWYG one. I know this existed at some point because I saw screenshots of it while looking through blogs, but I can't seem to find where to download the updated version.

After scouring the internet, I was able to find the updated version at Sourceforge.net. Download the gitbook-editor, extract it, and open opt/gitbook-editor/editor file. This will run the editor (My OS is Ubuntu 16.04 and it worked for me). If I'm not mistaken, this might be the last latest version of the offline editor the Gitbook team released.

This is more like it!

Extra Notes/ Possible next steps:

• Configure (edit book.json) https://gitbookio.gitbooks.io/documentation/format/configuration.html
• Install plugins. I can't find a master list of gitbook plugins since all other blogs point to http://plugins.gitbook.com/ (which returns a page not found). To find plugins, I just resorted to searching the npm site the keywords gitbook plugin.
• If you know R Markdown you might also want to checkout bookdown. It borrows GitBook's style to create elegant and appealing HTML book pages.