mkdocs.yml

name: ♻ mkdocs

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: ""

      artifact_name:
        description: The name of the artifact to upload.
        type: string
        required: false
        default: mkdocs

    outputs:
      artifact_name:
        description: The name of the uploaded artifact containing the site.
        value: ${{ inputs.artifact_name }}

permissions: {}

jobs:
  mkdocs:
    name: MkDocs
    runs-on: ${{ inputs.runs_on }}
    permissions:
      contents: read # Required to checkout the repository

    env:
      SITE_DIR: site
      ARTIFACT_NAME: ${{ inputs.artifact_name }}

    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: MkDocs Build
        run: mkdocs build --site-dir "$SITE_DIR"

      - name: Create tarball
        id: tar
        working-directory: ${{ env.SITE_DIR }}
        run: |
          tarball="$RUNNER_TEMP/$ARTIFACT_NAME.tar"
          tar -cvf "$tarball" .
          echo "tarball=$tarball" >> "$GITHUB_OUTPUT"

      - name: Upload artifact
        uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b
        with:
          name: ${{ inputs.artifact_name }}
          path: ${{ steps.tar.outputs.tarball }}