GitBook: Write Books using Markdown on OpenShift

GitBook on OpenShift book picutre

GitBook is a tool for using Markdown to write books, which are converted to dynamic websites or exported to static formats like PDF. GitBook also integrates with Git and GitHub, adding a social element to the book creation process.

If you are exporting your book into an HTML page, interactive aspects are also embedable. At the time of this writing, the system provides support for quizzes and JavaScript exercises. However, the tool is fully open source and written using Node.js, so you are free to extend the functionality to meet your needs.

OpenShift platform

OpenShift is a Platform as a Service (PaaS) for hosting web applications. GitBook exports books into interactive HTML websites and those books can be hosted on OpenShift. OpenShift automatically provides all the capabilities that are boring and complicated to configure so you can concentrate on the book creation process.

To make OpenShift even easier for this purpose, I built a QuickStart for GitBook. With this QuickStart, OpenShift becomes a build server and creates a website for you as part of the deployment process. This releases you from installing all the necessary dependencies of GitBook on your machine to build the book into a presentable form.

The QuickStart is at Github. The README describes the basic steps needed to get started.

Example book

The book creation process and the GitBook specifics are out of the scope for this article. I will use an existing open-source book and deploy it to OpenShift.

There are several books that can be found on the homepage of the GitBook project. I quite like the JavaScript one and will use it as the example book. You can take a look at the JavaScript GitBook here.

In the top panel, you will see several icons. Starting on the left, there is a link to the GitHub repository the book resides in. You can use the second icon to hide/close the left drawer. Then there is an interactive search capability to provide quick navigation thorough the book. In the center is the book’s title.

On the right side, we can see again the close integration with GitHub. Finally, on the very right, social buttons provide a quick and easy way to share the book with your friends via various social networks.

Below the top panel, there is a contents overview on the left and the main space where the book contents are presented. On the left/right sides of the content are quick links to allow you to move to the previous/next chapter.

It’s a very simple, yet effective design.

Deploying GitBook on OpenShift

Let’s deploy the JavaScript book on OpenShift.

Before we start, you need an OpenShift account. Learn more about OpenShift and sign up for an account. The account is free and allows you to deploy three books (web applications) for free. If you squash multiple books into one application, then you can deploy even more ;).

First, let’s create a new OpenShift application. The QuickStart builds on top of the PHP-5.4 application cartridge. We don’t need PHP, but the cartridge provides a preconfigured Apache instance capable of serving our static content generated by the GitBook tool. Once the command to create the application has executed, we change into the new Git repository cloned during the app creation process.

rhc app create jsbook php-5.4 --from-code=
cd jsbook

Now that the application is created, let’s populate it with the book itself. I am using the JavaScript book as an example, but you are free to use whatever book you like — even the one you wrote!

git pull -s recursive -X theirs master

Now the code of the book is in the repository and the OpenShift parts are in place. The last required step is to change some configuration for the QuickStart. Open the file with a text editor and set the name of the GitHub repository for your book. In my case the file would look like this:

export GITHUB_REPO="GitbookIO/javascript"

That’s it. Now we deploy the book to OpenShift by committing the changes to your Git repository and pushing them to OpenShift.

git add .
git commit -m "My first book"
git push origin master

You will see the messages from the build process. Once the push finishes your book is ready. Access it using a web browser. In my case, the URL is:

The rhc app show also shows the URL for your app. The URL for your book will have the same form, but mjelen will be your namespace instead (you set this when you ran the command rhc setup).


Read more about GitBook in the documentation, where you will learn how to structure a book and get the best from the functionality provided by GitBook. This simple example shows how OpenShift hides the complexity of building websites and allows you to focus on the content.

Let me know if you write your own book.

What’s next?

Educators, Node.js, OpenShift Container Platform, OpenShift Online, OpenShift Origin
, , , , , ,
Comments are closed.