Using GitBook with GitLab

This article is the start of a series about working with GitBook. It will show how to set up a Windows machine to create and build GitBooks locally.

The following structure will guide through the article:

  1. Install NodeJS on Windows
  2. Install Git on Windows
  3. Install gitbook from the command line
  4. Create a new GitBook from the command line
  5. Build the book and serve it in the browser

GitBook is a very handy tool to produce book-like learning material. After successfully giving a workshop at #OERcamp16 in Berlin last month, I decided to dive deeper into GitBook and share my experience with the world.

GitBook on Windows

Linux/UNIX systems are a bit easier to use with the modern development stuff like Node, Git and the command line. A real challenge always is: Getting things done on a Windows machine! I tried and it works. Let’s see how.

1. Install NodeJS on Windows

We will need NodeJS and npm to install the gitbook commandline software that generates the HTML, PDF, ePub and mobi formats. Browse to the NodeJS homepage and download the MSI Installer for your system. Install.

2. Install Git on Windows

There are two reasons we have to install Git on the Windows machine: First is, the GitBook Editor only connects to the GitBook website and fetches remote books from there to be edited locally. If we later want to work on a remote book that is hosted on GitLab we first have to clone it and then import it into the GitBook Editor. This procedure is the same on Linux and Mac. Second reason for installing Git is that we will need a real command line to generate our books later on.

Download the Git version for your Windows system and install with the following options:

Afterwards, you’ll find the Git Bash and the Git GUI in the context menu of every folder in Explorer.

3. Install gitbook from the command line

To complete our tool belt we finally need to install the gitbook software. The Node Package Manager (npm) makes it easy. Open the Git Bash and type:

npm install gitbook-cli -g

4. Create a new GitBook from the command line

Before we move on to the remote site, let’s check out what’s possible with our new tools. We are now able to write and build a GitBook with just a simple text editor. No other stuff neccessary! To try this out we prepare some stuff first:

In Git Bash, move to your home directory:

cd

Now navigate into the Downloads folder. You can certainly do this in any other folder as well.

cd Downloads

Create a new directory:

mkdir testbook

Navigate into this new directory:

cd testbook

After this little preparation we can initialize a new GitBook:

gitbook init

Listing the directory’s content we see what we’ve got:

ls -la
drwxr-xr-x 1 duerkop 197121  0 Mrz 15 14:06 ./
drwxr-xr-x 1 duerkop 197121  0 Mrz 15 13:55 ../
-rw-r--r-- 1 duerkop 197121 15 Mrz 15 14:06 README.md
-rw-r--r-- 1 duerkop 197121 10 Mrz 15 14:06 SUMMARY.md

These two files are the only ones neccessary to start with! If you want to have a look inside them go ahead and use your favorite text editor.

As a book might contain plugins we now have to install all the dependencies with

gitbook install

To generate the book we simply type:

gitbook build

This will create a folder _book that contains the static HTML site. To see the result in the browser and watch for contant changes of the book we type:

gitbook serve

Now we can open the HTML book in the browser at http://localhost:4000!