Gitbook Starter Kit

##What? This is a starter repo for your gitbook. You may fork it and get your book started, or clone it and remove the .git folder in the repo to have a fresh start. This file serves as the README file for the repository, as well as the introduction to your gitbook!

##Why Write This? Gitbook has a great way of documenting the specifics of how to work with it, but I wanted to create an opinionated guide for workflow that people can use use without headeaches, and work together as a team. This is my workflow and I'm outlining what works for me, and this will not necessarily fit everyone that is using a tool as flexible as gitbook.

More Information

I'm not going to re-write gitbook documentation. If I wanted to add / edit it, I would do it either on their help site or on their super useful README. Everything regarding how to work with this repo is contained above.

##How? (AKA the good stuff)

• Let's start with some assumptions:
• You keep all your code / things you work on in ~/Code (which is the same as /Users/Your-User-Name/Code)
• You want to call your book "BookName"

Setup your computer

• Install node by going to the Node Site, clicking install and downloading the package.
• Once the install finishes, open your terminal (Applications -> Utilities -> Terminal)
• In your command line, run npm install -g gitbook

Get your starter kit on

• Navigate your browser to the gitbook starter kit repo;
• Make sure you have a github account.
• Click the Fork Button: (screenshot)
• Rename the repo to what you want your book to be called:
  • Click settings from the home screen of the forked repo (forking creates a copy of the repository under your username). (screenshot)
  • Rename the repo (screenshot)
• Clone the repo to your machine. Remember our assumptions. I will walk through how I would do it:
  • Find the URL of the new forked repo. (screenshot)
  • Open terminal back up and execute the following:
  • git clone YOUR_REPO_URL ~/Code/BookName
  • cd ~/Code/BookName
  • gitbook serve
  • The last command will start a local server at port 4000 which you can access at http://localhost:4000; It will automatically refresh on changes. Now you're ready to start writing!

Putting the pen to paper.

Organizing

This is not the only way to do it, but I think it makes sense to organze the file structure as the example set up in the starter repo. The order of the files does not seem to matter (at least from what I can tell) because it's all controlled by the SUMMARY.md file (more on that later), but I recommend it for your own sanity.

How everything works together

All of the organization comes from the SUMMARY.md file. The file structure does not matter as much as long the links in the SUMMARY.md file are correct. The README.md file at the top of the repo (what you're reading now) acts the introduction to the book. That's the only thing that's set as default. Everything else can be controlled through the README file.

Actually writing

Gitbook has a great editor that will help you write Markdown and see the preview side by side. However, it does seem a little buggy still and people have trouble using it, therefore I wouldn't recommend it. If you are comfortable creating your own blank files (File -> New in Finder), I would recommend using MacDown, an open source markdown editor.

Publishing

This is another fairly confusing part. If you want to publish your book on gitbook.io (and I'm assuming you do), you want your workflow to look like this:

• Write some stuff locally. Preview it at localhost:4000
• Become happy with what you wrote. Commit it to git and push it to github.
• Once github receives the code, it tells gitbook.io to re-build your book in different formats
• In about 10 minutes, you see your new published version of the book!

So let's make it happen!

• Login to Gitbook.io with github. (screenshot)
• Create a new book
• At the book home page, go to settings (screenshot)
• Add the github url to the book under Github Repo. In our case it will be YOUR_USER_NAME/gitbook-starter-kit (screenshot).
• Click the "Add Deployment Webhook" button.

Now, whenever you push to Github, it will send a payload with the information of the push to gitbook and gitbook will know to start the build!