I started writing a book on gitbook.io recently, and chose to use GitHub to host it. I ran into some stumbling blocks as I started, mainly because things weren’t documented well enough, so I’m going to explain how to begin.
First, create an empty repository on GitHub to store your book. You’ll then want to log in to gitbook.io and create the book. In the settings, look for the GitHub option and enter the full name of your books empty GitHub repository, and save. Finally, click the deploy hooks button.
Next you’ll want to add the following empty files to your books repository:
In your .gitignore, put “/_book/”, commit and push.
It should be noted that Gitbook.io’s GitHub integration is 1-way. GitHub changes are pushed to Gitbook, but pushing changes to Gitbook doesn’t update GitHub. Once you’ve set up the GitHub integration, all content editing should happen via GitHub.
Your First Changes
Now you’re ready to start writing your book. Install the Gitbook Editor app, and open it. Use the file menu to open a book, and navigate to a folder containing your GitHub repository. You want to open the folder, not the files inside. This should allow you to start adding chapters and editing articles.
Remember to save your changes, and commit/add any changed files to your git repository. When you want to publish your changes, push them up to GitHub. The deploy hooks we set up earlier will kick in, and Gitbook.io will rebuild your live book with the new changes.
The Gitbook desktop editor will also save things inside the _book folder of your repository for internal purposes, such as the live preview. Do not add this folder to your git repository.
You do not need to authenticate with gitbook.io unless gitbook.io is hosting everything.
You now have an automated pipeline for building and hosting your book, and editing your content on GitHub! Be sure to visit Gitbook.io for traffic stats and to check if your builds are passing. In the books activity page is a markdown snippet you can insert that shows if the book is currently passing builds.