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!