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)

  1. Append pip install mkdocs with the other packages you need to install for example with mkdocs-material it would be pip install mkdocs mkdocs-material pymdown-extensions pygments

• Scenario 2: The theme is not installable via pip (such as docskimmer)

  1. Remove the --strict argument from mkdocs build --verbose --clean --strict to suppress a possible error from using theme not installable via pip.

  2. Add the code required to set up the theme in the before_deploy section, above mkdocs 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:

1. If you've already set up a Personal Access token with the public_repo scope, skip to step 11
2. Go to this URL. If it loads, skip to step 7. Otherwise, continue these instructions as usual.
3. Go to the settings of your Github account
4. Click Developer settings
5. Click Personal access tokens
6. Click Generate new token
7. You may need to enter your GitHub password to authorise the creation
8. Under Token description, choose a name for your token - it could be anything; I'd name it something like Travis CI as you can reuse the token for as many repositories as you like.
9. Enable the public_repo scope/permission
10. Click Generate token at the bottom of the page
11. Go to the settings of the Travis CI repository which you want to build the Mkdocs documentation for
12. Create an environmental variable with the following settings:
    • Name: github_token
    • Value: <THE TOKEN YOU JUST GENERATED>
    • Display value in build log: No
13. 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.