From 488ace15ff9f7dd737b2864af6853141b5933346 Mon Sep 17 00:00:00 2001
From: Nick Fitzgerald <fitzgen@gmail.com>
Date: Fri, 22 Jun 2018 10:30:06 -0700
Subject: [PATCH] user guide: Add instructions for running `mdbook` in CI

This adds instructions for building and testing books in CI on every PR and
push, as well as instructions for how to automatically deploy to gh-pages on
successful CI runs on `master`.

Fixes #714
---
 book-example/src/SUMMARY.md                |  1 +
 book-example/src/continuous-integration.md | 55 ++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 book-example/src/continuous-integration.md

diff --git a/book-example/src/SUMMARY.md b/book-example/src/SUMMARY.md
index fc5203c3..8c03a750 100644
--- a/book-example/src/SUMMARY.md
+++ b/book-example/src/SUMMARY.md
@@ -17,6 +17,7 @@
         - [Editor](format/theme/editor.md)
     - [MathJax Support](format/mathjax.md)
     - [mdBook specific features](format/mdbook.md)
+- [Continuous Integration](continuous-integration.md)
 - [For Developers](for_developers/README.md)
     - [Preprocessors](for_developers/preprocessors.md)
     - [Alternate Backends](for_developers/backends.md)
diff --git a/book-example/src/continuous-integration.md b/book-example/src/continuous-integration.md
new file mode 100644
index 00000000..ac5c39c7
--- /dev/null
+++ b/book-example/src/continuous-integration.md
@@ -0,0 +1,55 @@
+# Running `mdbook` in Continuous Integration
+
+While the following examples use Travis CI, their principles should
+straightforwardly transfer to other continuous integration providers as well.
+
+## Ensuring Your Book Builds and Tests Pass
+
+Here is a sample Travis CI `.travis.yml` configuration that ensures `mdbook
+build` and `mdbook test` run successfully. The key to fast CI turnaround times
+is caching `mdbook` installs, so that you aren't compiling `mdbook` on every CI
+run.
+
+```yaml
+language: rust
+sudo: false
+
+cache:
+  - cargo
+
+rust:
+  - stable
+
+before_script:
+  - (test -x $HOME/.cargo/bin/cargo-install-update || cargo install cargo-update)
+  - (test -x $HOME/.cargo/bin/mdbook || cargo install --vers "^0.1" mdbook)
+  - cargo install-update -a
+
+script:
+  - cd path/to/mybook && mdbook build && mdbook test
+```
+
+## Deploying Your Book to GitHub Pages
+
+Following these instructions will result in your book being published to GitHub
+pages after a successful CI run on your repository's `master` branch.
+
+First, create a new GitHub oauth token with the "public_repo" permissions (or
+"repo" for private repositories). Go to your repository's Travis CI settings
+page and add an environment variable named `GITHUB_TOKEN` that is marked secure
+and *not* shown in the logs.
+
+Then, add this snippet to your `.travis.yml`:
+
+```yaml
+deploy:
+  provider: pages
+  skip-cleanup: true
+  github-token: $GITHUB_TOKEN
+  local-dir: path/to/mybook/book
+  keep-history: false
+  on:
+    branch: master
+```
+
+That's it!