Add production-ready GitHub Actions workflow for MkDocs deployment

[Copilot]

Automates MkDocs documentation deployment to GitHub Pages on push to main branch.

Changes

Created requirements.txt

• Pins MkDocs dependencies: mkdocs>=1.5.0, mkdocs-material>=9.0.0

Enhanced .github/workflows/deploy-mkdocs.yml

• Added pip dependency caching via cache: 'pip' with cache-dependency-path
• Separated build (mkdocs build --strict --verbose) from deploy (mkdocs gh-deploy)
• Configured explicit GITHUB_TOKEN authentication for gh-pages push
• Set fetch-depth: 0 for full git history (supports git-based plugins)
• Added workflow comments explaining each step for maintainability

Workflow

- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: 'pip'
    cache-dependency-path: 'requirements.txt'

- name: Install MkDocs and dependencies
  run: pip install -r requirements.txt

- name: Build MkDocs site
  run: mkdocs build --strict --verbose

- name: Deploy to GitHub Pages
  run: mkdocs gh-deploy --force --message "Deploy documentation [skip ci]"
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Original prompt

Create a GitHub Actions workflow to automate deployments for GitHub Pages using MkDocs. This workflow should automate the process of building the MkDocs project and pushing the generated static site to the 'gh-pages' branch. The actions should be triggered on every push to the 'main' branch. Requirements for the workflow:

1. Trigger:

   • The workflow should run whenever changes are pushed to the 'main' branch.

2. Jobs:

   • A job to check out the repository.
   • A job to set up Python (as MkDocs requires Python).
   • A job to install MkDocs and its dependencies from the project's requirements (if a requirements.txt file exists).
   • A job to build the site using mkdocs build.
   • A job to deploy the generated site to the 'gh-pages' branch using the gh-pages deploy action or by manually pushing the output.

3. Cache Dependencies:

   • Use caching for Python dependencies to optimize workflow runtime.

4. Secure Deployments:

   • Leverage GitHub's GITHUB_TOKEN for authentication to push to the 'gh-pages' branch.
   • Ensure the workflow has permissions to push to 'gh-pages' branch.

5. Documentation:

   • Include comments in the workflow file explaining each step to make it beginner-friendly.

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[d0midigi]

Not sure