mkdocs.yml

# yaml-language-server: $schema=https://github.com/SchemaStore/schemastore/raw/master/src/schemas/json/github-workflow.json
#
# MkDocs-Material Workflow
# - Latest Python/pip with custom config
# TODO use env vars for pip config
#   - --no-input      Disable prompting for input
#   - --exists-action Default action when a path already exists ((i)gnore, (w)ipe)
#   - --disable-pip-version-check
#   - --no-color
#   - --no-python-version-warning
#   - --retries 1
#   - --timeout 1
# - Cache Python/pip and MkDocs
# - Install/Update MkDocs dependencies
#
---
name: MkDocs

on:
  push:
    branches: [ main ] # Only run on main branch
    paths:             # Only run on these directories changes
      - docs/**
      - mkdocs.yml
  # Allow to run workflow manually from Actions tab
  workflow_dispatch:

# Allow GITHUB_TOKEN deployment to GitHub Pages
permissions:
  contents: write
  id-token: write
  pages: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - name: Python Setup
        uses: actions/setup-python@v5
        with:
          python-version: '3.11' # use latest Python3 version
          # check-latest: true    # use latest version
          # cache: pip            # cache pip dependencies
      # - name: Export cache_id
      #   run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
      #- name: Cache MkDocs
      #  uses: actions/cache@v4
      #  id: mkdocs-material-cache
      #  continue-on-error: true
      #  with:
      #    key: mkdocs-material-${{ env.cache_id }}
      #    path: .cache
      #    restore-keys: |
      #      mkdocs-material-
      #- name: Cache Hit State
      #  if: ${{ steps.mkdocs-material-cache.outputs.cache-hit != 'true' }}
      #  continue-on-error: true
      #  run: echo "No Cache Hit!"
      - name: Pip Upgrade
        continue-on-error: true
        run: python -m pip install --upgrade --no-input pip
      - name: MkDocs Setup
        continue-on-error: true
        run: pip install --upgrade --no-input mkdocs-material
      - name: MkDocs Dependencies
        continue-on-error: true
        run: pip install --upgrade --no-input $(mkdocs --no-color --quiet get-deps)
      #- name: Upgrade Packages
      #  continue-on-error: true
      #  pip list --outdated --no-color | tail --lines=+3 | cut --delimiter=" " --fields=1 | xargs --max-args=1 pip install --upgrade --quiet --quiet --quiet
      - name: MkDocs Deploy
        run: mkdocs gh-deploy --force
# Disable MkDocs Cache as this repo isn't running a standard installation
#        id: mkdocs-material-cache
#        env: cache-name: mkdocs-material-cache
#        with:
#          path: .cache
#          key: ${{ env.cache-name }}-${{ hashFiles('requirements.txt') }}
#          restore-keys: ${{ env.cache-name }}-
#          # mkdocs --no-color --quiet get-deps >requirements.txt