Mkdocs Documentation Deployment Workflow

This YAML defines a GitHub Actions workflow that automates the lifecycle of your MkDocs documentation site on github pages.

Workflow Configuration

View Workflow Configuration

name: Deploy static HTML to gh-pages
on:
  push:
    branches:
      - main
      - Milestone-*
    paths:
      - docs/**
      - mkdocs.yml

  pull_request:
    branches:
      - main
      - Milestone-*
    paths:
      - docs/**
      - mkdocs.yml
    types:
      - opened
      - reopened
      - synchronize
      - closed

  workflow_dispatch: 

permissions:
  contents: write
  pull-requests: write
  deployments: write

jobs:
  deploy:
    if: ${{github.event_name == 'push'}}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v3
        with:
          python-version: "3.12"
      - name: Install MkDocs and theme
        run: |
          python -m pip install --upgrade pip
          pip install mkdocs-material
          pip install mkdocs-glightbox
      - name: Deploy to GitHub Pages
        run: mkdocs gh-deploy --force

  pr-preview:
    if: ${{github.event_name == 'pull_request'}}
    runs-on: ubuntu-latest
    concurrency:
      group: preview-${{ github.event.pull_request.number }}
      cancel-in-progress: true
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v3
        with:
          python-version: "3.12"
      - name: Install MkDocs and theme
        run: |
          python -m pip install --upgrade pip
          pip install mkdocs-material
          pip install mkdocs-glightbox
      - name: Build docs
        run: mkdocs build --clean
      - name: Deploy preview
        uses: rossjrw/pr-preview-action@v1
        with:
          source-dir: site

It splits the process into two distinct paths:

1. Production Deployment: Updates your live site when you modify the main codebase.

2. Preview Deployment: Creates a temporary test site when someone proposes changes (Pull Request).

---

Detailed Explanation

1. Triggers (on)

This section defines when the automation starts. It is designed to be efficient so it doesn't run on every single commit, only relevant ones.

• push: Runs when code is merged or pushed to main or Milestone-* branches.

• pull_request: Runs when a PR is opened or updated targeting those same branches.

• paths: Crucial optimization. The workflow only triggers if files in the docs/ folder or the mkdocs.yml config file are changed. If you change a generic Python script elsewhere in the repo, this workflow ignores it.

• workflow_dispatch: Adds a manual "Run Workflow" button in the GitHub Actions UI for emergency deploys.

2. Permissions

permissions:
  contents: write
  pull-requests: write
  deployments: write

This grants the bot high-level access. It needs write permission to:

• Push the built HTML to the gh-pages branch (to publish the site).

• Post a comment on your Pull Request with the "Preview Link."

---

3. Job A: Production Deployment (deploy)

This job updates the actual live website.

• Condition: if: ${{github.event_name == 'push'}}

  • It only runs when code is actually pushed/merged. It ignores Pull Requests.

• The Steps:

  1. Checkout & Setup: Downloads your code and installs Python 3.12.

  2. Install Dependencies: Installs mkdocs-material (the theme) and mkdocs-glightbox (an image zoom plugin).

  3. The Deploy Command:

     mkdocs gh-deploy --force
     

     This is the standard MkDocs command. It builds the static HTML and force-pushes it to the gh-pages branch, instantly updating your public URL.

---

4. Job B: PR Preview (pr-preview)

This job helps you review changes before they go live.

• Condition: if: ${{github.event_name == 'pull_request'}}

  • It only runs on Pull Requests.

• Concurrency (Resource Saver):

  concurrency:
    group: preview-${{ github.event.pull_request.number }}
    cancel-in-progress: true
  

  If you push 3 commits to a PR in 1 minute, this setting automatically cancels the first 2 builds and only runs the latest one. This saves GitHub Actions minutes.

• The Steps:

  1. Build: It runs mkdocs build --clean to generate the HTML files locally.

  2. Preview Action: It uses rossjrw/pr-preview-action. This tool takes the built HTML and uploads it to a temporary location. It then posts a comment on your Pull Request containing a direct link to view that specific version of the documentation