56 lines
1.5 KiB
Markdown
56 lines
1.5 KiB
Markdown
|
# 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!
|