mkdocs-gh-pages.yml

# Build and deploy your MkDocs site to GitHub Pages from branch "gh-pages".
# Ref: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch

# You should consider using "mkdocs.yml" to build your MkDocs site and "github-pages.yml" to deploy to GitHub Pages instead.
# Ref: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow

name: ♻ mkdocs-gh-pages

on:
  workflow_call:
    inputs:
      runs_on:
        description: The label of the runner (GitHub- or self-hosted) to run this workflow on. Defaults to `ubuntu-24.04`.
        type: string
        required: false
        default: ubuntu-24.04

      python_version:
        description: The version of Python to install.
        type: string
        required: false
        default: latest

      mkdocs_version:
        description: The version of MkDocs to install using PIP.
        type: string
        required: false
        default: ">=1.0.0"

      requirements:
        description: The path of a file containing the Python packages to install using PIP, usually "requirements.txt".
        type: string
        required: false
        default: ""

permissions: {}

jobs:
  mkdocs:
    name: MkDocs
    runs-on: ${{ inputs.runs_on }}
    permissions:
      contents: write # Required to checkout the repository push to the "gh-pages" branch

    steps:
      - name: Checkout
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683

      - name: Setup Python
        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
        with:
          python-version: ${{ inputs.python_version }}

      - name: Install MkDocs
        env:
          MKDOCS_VERSION: ${{ inputs.mkdocs_version }}
        run: |
          python -m pip install --upgrade pip
          pip install "mkdocs$MKDOCS_VERSION"

      - name: Install dependencies
        if: inputs.requirements != ''
        env:
          REQUIREMENTS: ${{ inputs.requirements }}
        run: pip install -r "$REQUIREMENTS"

      - name: Deploy MkDocs
        run: mkdocs gh-deploy --force