How to Deploy Docs to GitHub Pages with MkDocs in GitHub Actions

Docs go stale when publishing is manual; an MkDocs build wired to Pages keeps the site in sync with main.

Run mkdocs build, upload the site/ directory as a Pages artifact, and deploy it with actions/deploy-pages.

Steps

• Install MkDocs (and any theme like Material) with pip.
• Run mkdocs build to produce the static site/ directory.
• Upload site/ as a Pages artifact and deploy with actions/deploy-pages.

Workflow

name: Docs
on:
  push:
    branches: [main]
permissions:
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: github-pages
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mkdocs-material
      - run: mkdocs build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: site
      - uses: actions/deploy-pages@v4

Notes

• Set the Pages source to "GitHub Actions" in repo settings or the deploy step fails.
• On Latchkey managed runners docs builds run cheaper and self-heal if a runner drops.

Related guides