🚀 GitHub Pages + MkDocs Complete Guide 2025 - Fast Site Building with Auto-Deploy¶

Combining GitHub Pages and MkDocs allows you to build free and fast technical documentation sites. This article provides a complete walkthrough of implementation methods based on 2025's latest best practices.

🎯 Build Target¶

⚡ Quick Build in 5 Minutes¶

Step 1: Create Repository¶

# Initialize repository
mkdir my-mkdocs-site
cd my-mkdocs-site
git init

Step 2: MkDocs Setup¶

# Install MkDocs Material
pip install mkdocs-material

# Create initial configuration
mkdocs new .

Step 3: Basic Configuration File¶

Create mkdocs.yml with the following content:

mkdocs.yml

site_name: My Documentation Site
site_url: https://yourusername.github.io/my-mkdocs-site/

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.path
    - navigation.top
    - search.highlight
    - search.share
    - toc.follow
    - content.code.copy
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Reference: api.md

plugins:
  - search
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - admonition
  - pymdownx.details
  - pymdownx.tabbed:
      alternate_style: true
  - attr_list
  - md_in_html

Step 4: GitHub Actions Auto-Deploy¶

Create .github/workflows/deploy-mkdocs.yml:

.github/workflows/deploy-mkdocs.yml

name: Deploy MkDocs to GitHub Pages

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0  # for git-revision-date-localized

    - name: Configure Git Credentials
      run: |
        git config user.name github-actions[bot]
        git config user.email 41898282+github-actions[bot]@users.noreply.github.com

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

    - name: Upgrade pip
      run: |
        # install pip=>20.1 to use "pip cache dir"
        python3 -m pip install --upgrade pip

    - name: Get pip cache dir
      id: pip-cache
      run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT

    - name: Cache dependencies
      uses: actions/cache@v3
      with:
        path: ${{ steps.pip-cache.outputs.dir }}
        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
        restore-keys: |
          ${{ runner.os }}-pip-

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

    - name: Build MkDocs
      run: mkdocs build

    - name: Setup Pages
      uses: actions/configure-pages@v3

    - name: Upload artifact
      uses: actions/upload-pages-artifact@v2
      with:
        path: site/

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Step 5: Dependencies Configuration¶

Create requirements.txt:

requirements.txt

mkdocs>=1.5.0
mkdocs-material>=9.0.0
mkdocs-git-revision-date-localized-plugin>=1.2.0

🔧 Advanced Configuration¶

Custom Domain Setup¶

Create CNAME file

docs/CNAME

yourdomain.com

DNS Configuration

Add CNAME record in your domain's DNS settings:

CNAME @ yourusername.github.io

SEO Optimization¶

Add SEO settings to mkdocs.yml:

site_description: High-quality technical documentation site
site_author: Your Name

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/yourusername
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/yourusername

plugins:
  - search
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago
  - minify:
      minify_html: true

Plugin Extensions¶

Add advanced plugins:

plugins:
  - search
  - git-revision-date-localized
  - minify
  - redirects:
      redirect_maps:
        'old-page.md': 'new-page.md'
  - tags:
      tags_file: tags.md
  - glightbox:  # image zoom functionality

🎨 Theme Customization¶

Custom CSS¶

Create docs/stylesheets/extra.css:

docs/stylesheets/extra.css

:root {
  --md-primary-fg-color: #1976d2;
  --md-accent-fg-color: #2196f3;
}

.md-header {
  background: linear-gradient(90deg, #1976d2, #2196f3);
}

.md-typeset h1 {
  color: var(--md-primary-fg-color);
  border-bottom: 2px solid var(--md-accent-fg-color);
  padding-bottom: 0.5rem;
}

Add load configuration to mkdocs.yml:

extra_css:
  - stylesheets/extra.css

Custom JavaScript¶

Create docs/javascripts/extra.js:

docs/javascripts/extra.js

// Google Analytics configuration example
gtag('config', 'GA_MEASUREMENT_ID');

// Add custom functionality
document.addEventListener('DOMContentLoaded', function() {
    // Processing on page load
    console.log('MkDocs site loaded successfully!');
});

📊 Performance Optimization¶

Image Optimization¶

plugins:
  - optimize:
      enabled: !ENV [CI, false]
      cache: true
      optimize_png: true
      optimize_jpg: true

Cache Strategy¶

Build cache configuration in GitHub Actions:

- name: Cache pip dependencies
  uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}

- name: Cache MkDocs build
  uses: actions/cache@v3
  with:
    path: site/
    key: mkdocs-${{ runner.os }}-${{ hashFiles('mkdocs.yml', 'docs/**') }}

🔍 Troubleshooting¶

Common Issues and Solutions¶

GitHub Pages Settings

You need to change "Source" to "GitHub Actions" in the "Pages" section of repository settings

Build Error Response

# Local build test
mkdocs build --clean --strict

# Verbose log output
mkdocs build --verbose

Plugin Errors

Specify all dependencies in requirements.txt

Handling Deploy Failures¶

# For permission errors
git config --global user.name "github-actions[bot]"
git config --global user.email "actions@github.com"

# Clear cache
mkdocs build --clean

🚀 Application Examples¶

Multi-Repository Configuration¶

Integrate multiple project documentation:

nav:
  - Home: index.md
  - Project A:
    - Overview: project-a/index.md
    - API: project-a/api.md
  - Project B:
    - Overview: project-b/index.md
    - Guide: project-b/guide.md

CI/CD Pipeline Integration¶

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Run tests
      run: |
        # Run tests
        python -m pytest

    - name: Link check
      run: |
        # Link check
        mkdocs build --strict

📈 Operational Best Practices¶

Content Management¶

Regular Updates: Monthly content review
SEO Strategy: Metadata optimization
Usability: Navigation structure improvements

Team Development¶

Branch Strategy: feature → develop → main
Review Process: Pull Request-based review
Documentation Standards: Establish writing guidelines

Summary¶

The combination of GitHub Pages + MkDocs enables you to build free and high-quality technical documentation sites. With GitHub Actions auto-deploy, you can achieve continuous updates while minimizing maintenance overhead.

Based on the configuration in this guide, build the optimal documentation site for your project!