Auto-build an Mkdocs documentation in Travis CI

Question

How exactly do I automatically deploy my Mkdocs documentation in Travis CI?

Answer 1

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 and repo_deployment 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.

Answer 2

Its very simple to deploy your MkDocs website using Travis (considered you are using material theme)

Step 1: Create the repository for your project with empty 3 branches called master, dev, gh-pages.

Step 2 : Clone repository and local and checkout to dev branch. Add your MkDocs website to your dev branch on local. Add '/site' directory to git-ignore.(ie don't push .html) add .travis.yml given below in repo. Push you site to dev branch.

Step 3: Raise pull request to master from dev branch

Step 4: Login to Travis and connect your repositories there, Add env variable 'git_token' in travis(used in .travis.yml) its value you can get from github.com -> settings-> dev settings -> personal access token.

Step 5: Complete/Merge pull request to master.It will trigger web-hook and Travis will start build.After build your generated html files will be pushed to gh-pages branch.

Step 6: Go to repository settings and setup git-hub pages website to load from gh-pages branch.

Done

.travis.yml

language: python # Set the build language to Python

python: 3.6 # Set the version of Python to use

branches: master # Set the branch to build from

install:
    - pip install mkdocs mkdocs-material pymdown-extensions pygments # 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