Codeup Sample Gitbook

The purpose of this repository is to give us a common set of tools and standards for writing Gitbooks. It is intended to be used as a base repository that all our actual books can fork and add content to. This way we can all use the same basic set of utilities and features across the board.

Initial Setup

If you're just getting started writing a Gitbook, there's a handful of commandline tools you'll need to install, and only a couple of files to change before you begin adding content.

Installing Utilities

Gitbook is written using Node.js, so first things first you'll need to install this utility. If you're on a Mac using Homebrew you can run the following command:

brew install node

Once you have node installed, install gitbook using npm (depending on your setup, this may need to be done using sudo)

npm install -g gitbook

Once gitbook is installed, you will need to also install the repository plugins. These plugins are managed using the package.json file (more on this in a second). Install these by running the following from within this directory:

npm install

Finally, the deployment script is written in Ruby and requires a couple of gems to run. You can install these using Bundler:

bundle install

Setting up Submodules

In order to consolidate our curriculum content, we store it all in a separate repository and include it here as a submodule. Typically, this submodule is stored under book/content. If you have just cloned this repository, you will probably need to pull these files into your repo as well. In order to do that, run the following Git commands:

git submodule init
git submodule update

This will configure the submodule settings for your checkout and then clone the current commit of our curriculum content.

Note: The above process can be simplified by passing the flag --recursive to the git clone command:

git clone --recursive [repository-url] [directory]

Repository File Structure

This repository contains some basic utilities and configuration options that I think should be useful for most of our books. Most of these you shouldn't need to modify but it's good to know what's going on.

• .gitignore — Default git ignore; ignores files generated by gitbook and managed by npm & bundler
• .tm_properties — Some handy options for editing Gitbooks in TextMate
• deploy.rb — Ruby script to compile your Gitbook and push it out to Amazon S3; more on this below.
• Gemfile & Gemfile.lock— Ruby gem settings for deploy.rb
• package.json — Node.js settings and dependencies for your Gitbook. Although it would be good to change these to reflect your project for the most part it isn't strictly necessary. What you should check however, is the dependecies object. This is where you can add or remove additional Gitbook plugins and have them installed for you automatically by using npm. You can find additional plugins using something similar to

  npm search gitbook

• book — This is where all the content of your Gitbook will go. Anything added to this directory will be included in the compiled book, and any markdown file will be rendered as HTML.
  • .bookignore — Files to be excluded from the compiled book; by default only ignores the _book directory gitbook uses for serving the dev site.
  • .htpasswd — Default passwords for use with s3auth. Includes the codeup and codeupe-staff users
  • book.json — Properties and settings for your book. In particular, look at:
    • title & description — Your book's title and description, do modify these values
    • plugins — Some default Gitbook plugs we commonly use; after installing your new plugins using npm you will need to add them here to enable them in your book. We also disable the default MathJax plugin as it causes conflicts with our code samples
    • links — Disables all the default sharing links and adds a couple of extra links to the sidebar for us
  • content — Curriculum content, included as a submodule of this repository
  • cover.jpg & cover_small.jpg — A simple default cover for your book.
  • GLOSSARY.md — An empty glossary file for your book, see the documentation
  • README.md — An empty landing page; this will be the introduction for your book
  • SUMMARY.md — This is the file that defines your book's table of contents. It is an unordered list of links. Subsections can be created by adding child bullet points.

Recommended Tools

Github has created a GUI tool for editing & writing Gitbooks. It looks very nice. You probably shouldn't use it. I've found it creates very inconsistent file organization and doesn't provide precise enough control over filenames and repository structure. This in turn has led to various bugs in our Gitbooks once they're deployed (for example, links in Gitbook are not case sensitive; in the real world they are). Instead, using the gitbook command line tool to serve the rendered output locally and using a plain text editor seems to work at least as well, and provides much more predictable output. For a text editor, I'd recommend any one of the following:

• Sublime Text — Well, obviously
• TextMate 2 — My preferred editor, has some additional facilities for editing Markdown
• Mou — Purpose built split pane Markdown editor. Has nice layout and can roughly approximate the CSS Gitbook uses (only one file at a time however)

Previewing

To view your Gitbook use the gitbook commandline tool. From within this directory run:

gitbook serve book

Then in your browser go to http://localhost:4000.

Deployment

We use Amazon S3 to host the rendered Gitbook. The deploy.rb can automatically compile your book, cleanup a handful of bugs related to how S3 responds to different URLs, and upload it to a specified S3 bucket. At minimum, you will need a bucket name, an authorized access key, and it's corresponding secret. Running ./deploy.rb -h should get you the following help text:

Usage: deploy [options]
    -b, --bucket=BUCKET              S3 Bucket to deploy to (REQUIRED)
    -o, --output_dir=DIRECTORY       Build directory (Default: "build")
    -B, --branch=BRANCH              Checkout specified branch before building (Default: "master")
    -k, --aws_key=KEY                AWS Upload Key (Default: $AWS_ACCESS_KEY_ID)
    -s, --aws_secret=SECRET          AWS Upload Secret (Default: $AWS_SECRET_ACCESS_KEY)
    -t, --threads=THREADS            Number of threads to use for uploading (Default: 8)
    -f, --force                      Force deployment, even if the working directory is not clean
    -h, --help                       Display this help

The script is designed to deploy a given branch of your repository; by default master. If you specify a different branch, deploy.rb will attempt to checkout this other branch, run the deployment, and then switch back to the previous branch. As an additional safety check, deploy.rb will not push to S3 unless all your changes are committed. You can override this option by passing the -f flag, but you'd better have a good reason for doing so! Finally, once deployment is complete, deploy.rb will tag your repository with [bucket.name]@[date] so that we can track what versions of our material have been deployed, and to where.