Manual Deploy

In the case that the auto-deploy system is not working or needs to be tweaked, you can manually deploy the gitbook pages.

It is not recommended to manually deploy the docs site, however it can be done using git.

⚠️ This guide assumes that the master branch is the markdown and that gh-pages is the live HTML site. For the repo bandwidth.github.com the main branch is gitbook and the master branch is actually the live HTML site ⚠️

Checkout the master branch

Make sure that you have any and all changes contained in the master branch. If you know what you're doing and are aware of the side effects of deploying another branch, proceed with caution.

Prepare files

When deploying, you should make sure that you have the latest version of all plugins. The most comprehensive way is to rm -rf the node_modules and fresh install.

$ rm -rf node_modules
$ gitbook install

This ensures that the plugins stored in the node_modules are completely up-to-date.

Build the Gitbook

To deploy the site, we don't need all the features that come with gitbook serve. To generate the static HTML used to drive the site use the build command

$ gitbook build

The build command creates a _book folder in the same directory as the files. The _book folder contains the rendered HTML that will be uploaded to the gh-pages branch.

Preview the site with HTTP-Server

In order to preview the site before it goes live, I use a tool called http-server. http-server simply serves up a static site on localhost:8080 which is perfect for our use case. http-server works best when installed via NPM globally.

$ cd _book
$ http-server
Starting up http-server, serving ./
Available on:
  http://127.0.0.1:8080
  http://10.3.145.209:8080
  http://10.3.32.141:8080
Hit CTRL-C to stop the server

Verify the site

Follow the same checklist you would do before merging a pull request. Once finished CTRL-C the http-server. And cd out of the _book directory.

Checkout the gh-pages branch

Once the site has been clear and you're back at the root folder, checkout the gh-pages branch.

We're going to copy the contents of the _book directory to the main folder of the project. Essentially overwriting and replacing all the old copies.

$ git checkout gh-pages

I personally use a visual tool to 'copy & paste' the files from _book to the main folder, but you're welcome to use bash or whatever you'd like.

Git Add and Git Commit the changes

After the copypasta has finished, check the changes and add the files with git.

$ git status
//files changed

$ git add --all
$ git commit -m 'Update site on 3/22/18'

Git push makes it live

Final step is to push the changes to the gh-pages remote on github's servers.

$ git push

Once the contents have been pushed to github's servers, the site should be live in the next couple minutes.

Be sure to checkout master

Be sure to checkout master after the push is finished!!!

$ git checkout master