[Collection Thread] Workflow setups for automated MkDocs Pages publishing to Static Site hosts

[Andre601]

This discussion is meant as a way to collect possible setups to automatically publish MkDocs Pages to any Static Site Host (SSH) that might exist out there such as GitHub Pages, GitLab Pages, Codeberg Pages (Bunch of "... Pages" Services), etc.

Maybe, this can be used in the future to update the user docs of MkDocs with up-to-date examples of deploying your documentation.

If you share your own setups, try to avoid duplicates and also stick to posting the info (i.e. file setups) directly here, instead of linking to a post.

GitHub Actions (Publish to GH Pages)

Note

• Uses and requires a requirements.txt file with the dependencies in it.
• Custom domains need to be specified in the Pages settings of your repository, not in a CNAME file.

name: Publish site

on:
  workflow_dispatch:
  push:
    branches:
      - master
      - main
    #paths: # Recommended to avoid extra builds
    #  - .github/workflows/your_site_publish_file.yml # Change name to what your workflow file is
    #  - docs/**
    #  - mkdocs.yml
    #  - requirements.txt

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: github-pages
  cancel-in-progress: false

jobs:
  buildAndPublish:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Recommended for git localized plugin
      - name: Setup Python 3.x
        uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - name: Install dependencies
        run: |
          python -m pip install -U pip setuptools
          python -m pip install -r requirements.txt # Define your dependencies in this file.
      - name: Build Pages
        run: mkdocs build
      - name: Configure GitHub Pages # No idea if that actually does anything...
        uses: actions/configure-pages@v4
      - name: Upload Pages Artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: site/ # Important. Set to your output dir in MkDocs
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v3

---

Woodpecker-CI (Publish to Codeberg Pages)

Note

• Uses and requires a requirements.txt file with the dependencies in it.
• This setup also requires a target repository with a pages branch to commit to and a PAT for authentication during push.
• Folders and files persist between steps.

when:
  - event: push
    branch: master # Change to your branch with MkDocs
    path:
      include: ["docs/**", "mkdocs.yml", "requirements.txt"]

# Reusables
variables:
  setup_git: &setup_git
    - apk add git
    - git config user.email "$EMAIL" # Provided as secret later on
    - git config user.name "CI Site Builder"

steps:
  cloneTargetRepo:
    image: alpine:3.18.4 # Can be any image offering chmod, mv, cd, etc.
    secrets: [email]
    commands:
      - chmod -R a+w . # Avoid possible permission issues
      - <<: *setup_git # Insert our Git reusable
      - git config --add safe.directory /woodpecker/src/codeberg.org/ExampleUser/ExampleRepo # Change to whatever path the source repo was cloned into
      - git config init.defaultBranch pages
      - git clone -b pages https://codeberg.org/ExampleUser/TargetRepo.git pages # Your target repo for the page
      - chmod -R a+w pages
  buildDocs:
    image: woodpeckerci/plugin-mkdocs:latest # Recommended to stay on latest release. Uses Material for MkDocs as base
    settings:
      site_dir: pages # Override MkDocs site_dir output
  commitAndPush:
    image: alpine:3.18.4
    secrets: [email, cbtoken] # cbtoken is a PAT with push perms to the target repo
    commands:
      - <<: *setup_git
      - mv domains .domains # Optional. Moves a domains file containing your custom domain into the pages folder and names it .domains for Codeberg Pages to recognize
      - cd pages
      - git remote set-url origin https://$CBTOKEN@codeberg.org/ExampleUser/TargetRepo.git
      - git add --all
      - git commit -m "Update Site ($( env date +"%d.%m.%Y %Z" )) [SKIP CI]"
      - git push