Auto-build an Mkdocs documentation in Travis CI
Here's how to automatically deploy your mkdocs document. Simply follow the 3 steps below.
Step 1
Simply insert the following code snippets into their respective locations in your .travis.yml
configuration file:
language: python # Set the build language to Python
python: 3.8 # Set the version of Python to use
branches: master # Set the branch to build from
install:
- pip install mkdocs # Install the required dependencies
script: true # Skip script (Don't use this if one already exists)
before_deploy:
- mkdocs build --verbose --clean --strict # Build a local version of the docs
deploy: # Deploy documentation to Github in the gh_pages branch
provider: pages
skip_cleanup: true
github_token: $github_token
local_dir: site
on:
branch: master
Step 2
If you are using a mkdocs theme that is not mkdocs
or readthedocs
then follow the following steps to install it:
Scenario 1: The theme is installable via pip (such as mkdocs-material)
- Append
pip install mkdocs
with the other packages you need to install for example withmkdocs-material
it would bepip install mkdocs mkdocs-material pymdown-extensions pygments
- Append
Scenario 2: The theme is not installable via pip (such as docskimmer)
Remove the
--strict
argument frommkdocs build --verbose --clean --strict
to suppress a possible error from using theme not installable via pip.Add the code required to set up the theme in the
before_deploy
section, abovemkdocs build --verbose --clean
The code in the
before_deploy
section would look like this for docskimmer:before_deploy: - git clone https://github.com/hfagerlund/mkdocs-docskimmer.git # Clone the repo hosting the code - cp -r $PWD/mkdocs-docskimmer/mkdocs_docskimmer . # Copy the required code to the repo root - cp -r $PWD/mkdocs-docskimmer/mkdocs_docskimmer/. ./docs # Copy the required code to the docs folder - mkdocs build --verbose --clean # Build a local version of the docs
Installation of themes not available via pip may vary.
Step 3
The final step is to tell Travis CI the credentials required to sign in to your GitHub account to push the changes:
- If you've already set up a Personal Access token with the
public_repo
scope, skip to step 11 - Go to this URL. If it loads, skip to step 7. Otherwise, continue these instructions as usual.
- Go to the settings of your Github account
- Click Developer settings
- Click Personal access tokens
- Click Generate new token
- You may need to enter your GitHub password to authorise the creation
- Under
Token description
, choose a name for your token - it could be anything; I'd name it something likeTravis CI
as you can reuse the token for as many repositories as you like. - Enable the
public_repo
scope/permission - Click
Generate token
at the bottom of the page - Go to the settings of the Travis CI repository which you want to build the Mkdocs documentation for
- Create an environmental variable with the following settings:
- Name:
github_token
- Value:
<THE TOKEN YOU JUST GENERATED>
- Display value in build log:
No
- Name:
- Click
add
Afterword
You're done! Please feel free to ask me any questions in the comments.
Also, if the method stops working or doesn't work, PLEASE tell me in the comments and I will fix it ASAP.