GitBook has become the go-to documentation tool for many smaller companies. Startups routinely use GitBook pages instead of the traditional docs section. And for a good reason – it doesn’t take much effort to learn, and it is very convenient in case you have already started some documentation on your GitHub.
In this tutorial, we’ll show you the first steps, so you can start building your own documentation in a more systematic manner. For the demonstration, I forked GitHub repo from docker compose to my own GitHub page.

This tutorial will go through the following tasks:

1/ Integrate GitHub with your new GitBook account

2/ Create a new space

3/ Connect your repo to the new space

4/ Start editing documentation

5/ Synch changes between Gitbook and Github

1/ Integrate GitHub with your new GitBook account

Let’s register a new account with GitBook at
https://app.gitbook.com

You will get to the home screen:

Let’s click on the Integrations button in the left column. On this page, you will choose which accounts to connect. Besides GitHub and GitLab, also notably Figma, Google Analytics, Slack, Intercom and many others. We will choose GitHub:

And in the next step, we will authenticate. Press Connect with GitHub

And confirm your credentials:

Integration done!

2/ Create a new space

GitBook has already created one empty project, but I recommend to start from the scratch.

Notice the Spaces bookmarks in the left column. Space is a term for a documentation project in GitBook.
Click on the “+” sign to start a new project.
And select New space.

Your new space is ready.

3/ Connect your repo to the new space

We’ll now synch our GitHub repo with our new space to copy the content.

In the right upper corner, press configure button

It will lead you once again to the integration page.
GitBook may now request you to authenticate your GitHub again.

Select your GitHub account and repository you want to connect:

Finish by choosing “GitHub to GitBook” option:

The synch will start:

4/ Start editing documentation

The new space you have created in the step 2 is now filled with content from your GitHub.  For this particular tutorial, we used Docker Compose as an example:

Content of your GitHub page and GitBook space page are identical at this point. It is similar to a situation when you clone a repo from GitHub to your local computer.

To start editing your documentation in GitBook, you have to now press the green Edit button:

As an example, we will change the description for the “up” command. Let’s navigate to the docs bookmark on the left and find the respective section to change:

And we write just “TESTING GITBOOK”

5/ Merge changes between Gitbook and Github

At this point, you have changed documentation on your GitBook space page, but it didn’t synch yet with your GitHub.

To merge the changes, simply press the purple Merge button:

Done! As you can see, the change is now visible on your GitHub page as well:

Mastering tools like GitBook will make your life easier. But you still need skilled technical writers to organize and fill-in your docs. Our team of writers with devs and ops background will help you out: