Skip to content

Deploying Documentation to GitHub Pages

This guide explains how to deploy the MkDocs documentation to GitHub Pages.

Prerequisites

  • Git repository on GitHub
  • Python 3.8+ installed
  • Write access to the repository

Deployment Options

Step 1: Install MkDocs

# Install MkDocs and dependencies
pip install -r requirements.txt

# Verify installation
mkdocs --version

Step 2: Build Documentation

# Build the documentation
mkdocs build

# This creates a 'site' directory with static HTML

Step 3: Deploy to GitHub Pages

# Deploy to gh-pages branch
mkdocs gh-deploy

# This will:
# 1. Build the documentation
# 2. Push to gh-pages branch
# 3. Make it available at https://yourusername.github.io/authentication_test

Step 4: Configure GitHub Pages

  1. Go to your repository on GitHub
  2. Click "Settings"
  3. Scroll to "Pages" section
  4. Under "Source", select:
  5. Branch: gh-pages
  6. Folder: / (root)
  7. Click "Save"

Your documentation will be available at: 

https://yourusername.github.io/authentication_test

Step 1: Create Workflow File

Create .github/workflows/docs.yml:

name: Deploy Documentation

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'requirements.txt'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: 3.x

      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          key: ${{ github.ref }}
          path: .cache

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

      - name: Build and deploy
        run: mkdocs gh-deploy --force

Step 2: Commit and Push

git add .github/workflows/docs.yml
git commit -m "Add GitHub Actions workflow for documentation"
git push origin main

Step 3: Verify Deployment

  1. Go to "Actions" tab in your repository
  2. Watch the workflow run
  3. Once complete, visit your documentation site

Mike allows you to maintain multiple versions of documentation.

Install Mike:

pip install mike

Deploy Version:

# Deploy version 1.0
mike deploy --push --update-aliases 1.0 latest

# Set default version
mike set-default --push latest

View Versions Locally:

mike serve

Visit: http://localhost:8000

Customizing Deployment

Custom Domain

  1. Create docs/CNAME file: 

    docs.example.com

  2. Configure DNS:

  3. Add CNAME record pointing to yourusername.github.io

  4. In GitHub Settings → Pages:

  5. Enter custom domain
  6. Enable "Enforce HTTPS"

Update mkdocs.yml

site_url: https://docs.example.com
repo_url: https://github.com/yourusername/authentication_test

Local Development

Serve Locally

# Start development server
mkdocs serve

# With live reload
mkdocs serve --dev-addr=0.0.0.0:8000

Visit: http://localhost:8000

Build Only

# Build without deploying
mkdocs build

# Build to custom directory
mkdocs build --site-dir custom_site

Clean Build

# Remove site directory
rm -rf site

# Rebuild
mkdocs build

Troubleshooting

Build Fails

Check for errors:

mkdocs build --verbose

Common issues: - Missing dependencies: pip install -r requirements.txt - Invalid YAML in mkdocs.yml - Broken links in documentation

Deployment Fails

  1. Check GitHub Actions logs
  2. Verify permissions: 
    permissions:
  contents: write
  3. Ensure gh-pages branch exists

Site Not Updating

  1. Clear browser cache
  2. Wait a few minutes for GitHub Pages to update
  3. Check GitHub Actions workflow completed successfully
  4. Verify gh-pages branch has new commits

404 Errors

  1. Check site_url in mkdocs.yml
  2. Verify GitHub Pages is enabled
  3. Ensure gh-pages branch is selected as source

Best Practices

1. Version Control

Don't commit the site/ directory:

# .gitignore
site/
.cache/

2. Documentation Structure

Keep documentation organized:

docs/
├── index.md
├── getting-started/
├── build/
├── keycloak/
├── api/
├── config/
├── troubleshooting/
└── development/

3. Regular Updates

Update documentation with code changes:

# After code changes
git add docs/
git commit -m "Update documentation"
git push

4. Review Before Deploy

Always review locally:

mkdocs serve
# Review at http://localhost:8000
mkdocs gh-deploy

5. Use Branches

For major documentation changes:

git checkout -b docs/update-api-guide
# Make changes
git push origin docs/update-api-guide
# Create pull request

Monitoring

MkDocs Material includes built-in search. No configuration needed.

Maintenance

Update Dependencies

# Update all dependencies
pip install --upgrade -r requirements.txt

# Update specific package
pip install --upgrade mkdocs-material

# Install linkchecker
pip install linkchecker

# Check links
mkdocs build
linkchecker site/

Additional Resources

Next Steps