Documentation with versions using GitHub Actions, mike and Cloudflare Pages

[niden]

Related: #6513

We are in the process of converting our documentation with our next release, to use mkdocs-material. The biggest hurdle we had was understanding how versioning works with mike. Loads of rabbit holes to follow and somewhat missing documents/pointers, but we made it in the end.

I hope this post helps people that want to follow the same path.

Requirements:

• Documentation deployed as static files
• Using mkdocs-material as the theme with some plugins
• Using mike for versions
• Having a local environment to test
• Deploy in Cloudflare Pages

Pretty straight forward. Following the manual, one can run the docker command for mkdocs-material and serve the documents locally, make alterations etc. and see them live. The unknown for us was how to incorporate mike, check the output and deploy to Cloudflare Pages.

Cloudflare Pages

Cloudflare Pages have been linked to the repository, and build whenever a commit happens in the production branch. (more on that further down)

Local Environment

You will need to create a new docker image for yourself. Although a docker container exists for mkdocs-material, we could not find one for mike, so we created one for both. The image will contain mkdocs, mkdocs-material and various plugins as well as mike

FROM python:3
LABEL authors="[email protected]"

WORKDIR /usr/src/app

COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

and the requirements.txt file is:

mkdocs
mkdocs-material
mkdocs-material-extensions
mkdocs-minify-plugin
mkdocs-redirects
mike

Switch to the folder you have the Dockerfile and build it:

docker build -t mkdocs-mike .

and then enter it so that you can run commands

docker run -it --rm \
    --network host \
    -v "$PWD":/usr/src/myapp \
    -w /usr/src/myapp \
    mkdocs-mike /bin/bash

This will allow you to enter the image and run different commands such as

mkdocs serve

You can then load http://localhost:8000/ in your browser and view your documents. When the time comes, you can run mike also to produce the documents (it will be in the site folder)

NOTE: If you produce output with mike and then try to copy the contents of the site folder, you might end up with permission issues. The user that runs in that docker environment is not the same one as your host, so use chown where necessary.

Doing it this way is indeed two steps, one to enter the dockerized environment and then run the serve command, but it offers access to mike, so it helps in that respect. If you install packages directly on your machine, you can just install all the requirements and not have to deal with a docker container.

Deployment

Deploying with mike is easy. The fastest way is to create the documents, was to copy them from the site folder to a temporary location. Of course, we had to change the permissions on the files since they were generated from the user in the container and not the host user. Then it was a matter of switching to the production branch, and copy the documents over to the correct folder (3.1, 3.2, 4.1, 5.5 etc.). Commit and push upstream.

Cloudflare Pages would detect the commit and deploy the site.

Workflow

The above worked but a pain after a while. The need is for things to be automated. Based on suggestions, we checked the Andruino-Cli project and how they handle this.

They deploy in GitHub pages, so the steps are a bit different but the way they detect branches and changes is great! Kudos.

In the repository we of course have the master branch. Off that, we create a new branch 5.4.x. The reason for the x in the end is because this branch will host all the 5.4 versions. It is also parsed in the GitHub workflow.

In that branch we make any alterations we need. Once ready we push upstream and let the GitHub action do its magic.

The action does:

• Check if the branch of the latest commit. If it is 0-9.0-9.x, then it proceeds with the deployment
• If the above is OK
  • Checkout the code
  • Set up Python
  • Install requirements (requirements.txt)
  • Determine the version
  • Set the GitHub user for the push commit
  • Run mike targeting the production branch

To determine the version we use a file in the root of the project called VERSION, which has one line in it:

5.5|latest

The first part (before the |) is the version, the second the alias. In this case, we are setting 5.5 to be the latest branch. For 5.4 the file would be

5.4|

Just before we run mike we need to pull from the production branch to update references, and then set up the user that will make the commit.

IMPORTANT For this to work, you will need to allow Workflow Write access to your repository for GitHub Actions

Repository > Settings > Actions > General > Workflow Permissions > r+w

Once that is done, mike runs doing its magic, commits, and pushes to the production branch. Cloudflare Pages detects the commit and publishes the site.

NOTE Since mike built the site, Cloudflare Pages only needs to upload the files to their network, so the build command while setting up Cloudflare Pages is empty and the framework is set to None

Our workflow file is at the bottom of this post.

New Version

When creating a new version, we will make a new branch 5.6.x and make the necessary changes to the VERSION file as well as the GitHub action. If you notice, we like to have the name of the action reflect the version. Not a necessary step but we like it.

After the documents are completed and before we deploy to live, we switch to the current latest version branch 5.5.x and alter the VERSION file, removing the latest alias. Push so that we get a deployment and then switch to the latest branch and push up to get the new latest version.

Conclusion

Enjoyable and a bit frustrating trip, but we got there in the end. We only have some cosmetic issues to deal with but our documents are ready to be deployed with the next version of our framework.

Note, that we did not opt to use the projects plugin (yet), which could have been used instead of mike. We will have to experiment with that in the near future, and should it prove to be what we need, we will definitely switch to that workflow and update this post accordingly.

GitHub Actions workflow file

# Workflow inspiration and adaptation came from Andruino-Cli
# https://github.com/arduino/arduino-cli/blob/master/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml

name: Deploy Documents 5.5

env:
  PYTHON_VERSION: "3.9"

on:
  push:
    branches:
      # Branch to base "dev" website on. Set in siteversion.py also.
      - master
      # Release branches have names like 0.8.x, 0.9.x, ...
      - "[0-9]+.[0-9]+.x"
  create:

jobs:
  pre-publish:
    runs-on: ubuntu-latest
    outputs:
      result: ${{ steps.determination.outputs.result }}
    steps:
      - name: Determine if documentation should be published on this workflow run
        id: determination
        run: |
          RELEASE_BRANCH_REGEX="refs/heads/[0-9]+.[0-9]+.x"
          if [[ "${{ github.event_name }}" == "push" || ( "${{ github.event_name }}" == "create" && "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX ) ]]; then
            RESULT="true"
          else
            RESULT="false"
          fi

          echo "result=$RESULT" >> $GITHUB_OUTPUT
          echo "Deploy documents: $RESULT"

  publish:
    runs-on: ubuntu-latest
    needs: pre-publish
    if: needs.pre-publish.outputs.result == 'true'

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Install Requirements
        run: |
          python -m pip install --upgrade pip
          python -m pip install -r requirements.txt

      - name: Determine versioning parameters
        id: determine-versioning
        run: |
          # Read the first line from the VERSION file
          LINE=$(head -n 1 ./VERSION)

          # Extract version and alias using parameter expansion
          VERSION="${LINE%%|*}"
          ALIAS="${LINE#*|}"

          # Print the extracted values for verification
          echo "Version: $VERSION"
          echo "Alias: $ALIAS"

          echo "PH_DOCS_VERSION=$VERSION" >> $GITHUB_ENV
          echo "PH_DOCS_ALIAS=$ALIAS" >> $GITHUB_ENV

      - name: Deploy
        if: ${{ env.PH_DOCS_VERSION }} != null
        run: |
          # Publishing implies creating a git commit on the production branch, 
          # We will need to create a user for this at some point
          git config user.name <GitHub user>
          git config user.email <GitHub user email>
          git fetch --no-tags --prune --depth=1 origin +refs/heads/production:refs/remotes/origin/production
          mike deploy \
            --update-aliases \
            --branch production \
            --push \
            ${{ env.PH_DOCS_VERSION }} \
            ${{ env.PH_DOCS_ALIAS }}

[jjmachan]

this should be added to the docs - thank you so much for sharing @niden ❤️

[squidfunk]

Thanks for sharing! We're actively working on making versioning and multi-language setups simpler, so most of this will not be necessary anymore in the near future ☺️ See our latest blog post on our current efforts.