The default GITHUB_TOKEN in this workflow does not have write permission to contents, so the push to gh-pages is rejected.

[aj1126]

The failure is a permissions issue in the docs deployment step, not a MkDocs build error.

Root cause

The job fails when mkdocs gh-deploy --force tries to push to gh-pages:

• workflow: .github/workflows/docs.yml
• failing step: line 16
• error from logs: Permission to aj1126/DriveTools.git denied to github-actions[bot] and git push origin gh-pages --force returned 403

Relevant files:

• Workflow: https://github.com/aj1126/DriveTools/blob/0ae3f1d1c9bcaac89f989a9f4ce51f2e6409a0a6/.github/workflows/docs.yml
• MkDocs config: https://github.com/aj1126/DriveTools/blob/0ae3f1d1c9bcaac89f989a9f4ce51f2e6409a0a6/mkdocs.yml

Why it happens

Your workflow uses actions/checkout@v3 with default permissions, then mkdocs gh-deploy attempts a Git push. The default GITHUB_TOKEN in this workflow does not have write permission to contents, so the push to gh-pages is rejected.

Fix

Grant the workflow write access to repository contents and persist credentials during checkout.

Replace .github/workflows/docs.yml with:

name: Build Docs

on:
  push:
    branches: [ main ]

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: true

      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'

      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

Also fix the MkDocs metadata

Your mkdocs.yml still points at the old repository/site:

site_url: https://aj1126.github.io/MyBookTools/
repo_url: https://github.com/AJ1126/MyBookTools

Since this repo is DriveTools, update it to match the current repository:

site_name: DriveTools
site_description: "PowerShell tools for large drive maintenance"
site_url: https://aj1126.github.io/DriveTools/
repo_url: https://github.com/aj1126/DriveTools
theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: deep orange
  features:
    - navigation.tabs
    - navigation.sections
    - search.highlight
    - search.suggest
nav:
  - Home: index.md
  - Installation: install.md
  - Commands: commands.md
  - Examples: examples.md
  - API: api/MyBookTools.md

Optional cleanup

If the project has been renamed from MyBookTools to DriveTools, also review this nav entry:

- API: api/MyBookTools.md

If that file was renamed too, update it to the current filename or the docs build may fail later.

Summary

Use permissions: contents: write in the workflow and update checkout to a current version. That resolves the 403 push failure. The mkdocs.yml repo/site URLs should also be corrected to DriveTools so the published docs point to the right location.