Tom J Nowell

Gitbooks & GitHub

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.

Setting Up

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:

  • .gitignore
  • README.md
  • SUMMARY.md

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.

Congratulations!

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.

7 responses to “Gitbooks & GitHub”

  1. Chris McCoy avatar
    Chris McCoy

    they also have a desktop app which you can create the books from (mac,win,linux)

    Reply
  2. Tim N avatar
    Tim N

    Hey Tom,

    Since you keep closing my WordPress Stack questions, I’ll ask the man himself. Another developer already deployed WordPress with GIT to our HostDime cPanel WHM Linux environment, we’re successfully logged in via SSH seeing the GIT file and ready to clone. What setup, with WP database migration in mind and in preparation for cloning the repository to use as your staging environment, should be configured on a Mac 10.9.4? Our goal is to make a workstation for testing instead of testing directly on the live server, an example would be daily development or whether the WordPress update will break your theme.

    Our current thought is to use SourceTree with Bitbucket as our GIT GUI, but were looking for advice on a working setup for the localized environment from an experienced user who has already managed the database transition. We are excited to move towards the GIT workflow but don’t see a great database handoff.

    We have looked into some database solutions and saw that WP Migrate DB Pro can potentially handle the database transitions. We would rather not WP Migrate DB Pro

    Thank you.

    Reply
    1. Tom J Nowell avatar
      Tom J Nowell

      I put your question on hold because it’s off topic. If you disagree with the way Stack Exchange is ran or the decision, then you should open a question on the meta site and make your case, your question may even be reopened if people agree with you. Failing that, I’ve already indicated good places to ask the question, e.g. the WordPress Google+ community or the Facebook groups were questions like this are asked on a near daily basis.

      As a sidenote, this is completely irrelevant to this blogpost. I’d be happy to discuss gitbook without, but if you want to continue discussing your question with me, go to the Meta site

      Reply
  3. Kristian Mandrup avatar
    Kristian Mandrup

    Thanks for the guide! Still took me a while to figure it all out though.

    My steps in detail:

    Github/gitbook.io integration
    1. Created repo named `test` in github
    2. Created a book named `test` in gitbook.io
    3. Clicked settings pane for the book
    4. Clicked bottom left menu item github
    5. Entered my /test in input field
    6. Clicked green `Save` button
    7. Integrations section appears at the bottom right
    8. Click `Add webhook` button
    9. Wait a few seconds, then click `Check webhooks`
    10. New window opens which displays hooks for the github account. If green check mark all is good 🙂

    Local setup
    11. Create a new folder `test` on your system
    12. Create the files mentioned
    13. Add remote origin, commit and push.
    14. Check the files are on github in the repo
    15. Check that the gitbook.io book is updated via webhook

    Gitbook Editor integration
    16. Open Gitbook Editor app
    17. Click `Open` menu item in initial book overview screen
    18. Navigate to local folder for your repo and open
    19. It should now load your (empty) book content into the editor…
    20. Create article and write something
    21. Click save
    22. Notice that the sync button has a 1 (change) notifier
    23. Click the Sync button
    24. Check github repo for change
    25. Goto gitbook.io and publish then finally read your published book 🙂

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.