CI/CD for MkDocs with GitHub Actions

Build your MkDocs documentation strictly and ship it automatically.

MkDocs builds Markdown into a static site, and the Material theme is a popular choice. Building with --strict turns warnings like broken links into errors, which is ideal for CI. This recipe builds strictly and deploys to GitHub Pages.

What the pipeline does

• install Python with pip caching
• install mkdocs and the theme
• build with mkdocs build --strict
• upload the site output
• deploy to GitHub Pages

The workflow

setup-python with cache: pip caches downloaded wheels. --strict fails the build on any warning. MkDocs builds to site/.

name: CI
on:
  push:
    branches: [main]
  pull_request:
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: pip
      - run: pip install -r requirements.txt
      - run: mkdocs build --strict
      - uses: actions/upload-pages-artifact@v3
        with:
          path: site
  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment:
      name: github-pages
    steps:
      - uses: actions/deploy-pages@v4

Caching and speed

cache: pip on setup-python restores the wheel cache so installs are quick. MkDocs builds are fast even for big docs, so CI is mostly install time; if you run docs CI across many repos, cheaper managed runners such as Latchkey lower the aggregate minute cost.

Deploying

Set site_url in mkdocs.yml. site/ deploys to Pages (shown), Netlify, or S3+CloudFront. Pin mkdocs and theme versions in requirements.txt so a dependency release does not silently change the output.

Key takeaways

• Build with --strict so warnings fail CI.
• Pin MkDocs and theme versions in requirements.txt.
• Output is site/ for any static host.

Related guides