Skip to content

GitHub Pages Deployment Guide

🚀 Deploy Enhanced Toolkits Documentation to GitHub Pages

This guide shows you how to deploy your MkDocs documentation to GitHub Pages for free hosting.

Prerequisites

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

# Verify MkDocs works locally
mkdocs serve

Deploy to GitHub Pages

# From your project root directory
mkdocs gh-deploy

This command will: - Build your documentation - Create/update the gh-pages branch - Push the built site to GitHub Pages - Make it available at https://malvavisc0.github.io/enhancedtoolkits/

First-Time Setup

If this is your first deployment:

  1. Enable GitHub Pages in your repository:
  2. Go to repository Settings
  3. Scroll to Pages section
  4. Set Source to "Deploy from a branch"
  5. Select Branch: gh-pages

  6. Click Save

  7. Deploy the documentation: 

    mkdocs gh-deploy --force  # Use --force for first deployment

  8. Access your site:

  9. Visit https://malvavisc0.github.io/enhancedtoolkits/
  10. May take a few minutes to become available

Method 2: GitHub Actions (Automated)

Create GitHub Actions Workflow

Create .github/workflows/docs.yml:

name: Deploy Documentation

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

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r docs/requirements.txt

    - name: Build documentation
      run: mkdocs build

    - 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
    if: github.ref == 'refs/heads/main'
    steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v2

Enable GitHub Actions Deployment

  1. Repository Settings:
  2. Go to Settings > Pages

  3. Set Source to "GitHub Actions"

  4. Commit the workflow: 

    git add .github/workflows/docs.yml
git commit -m "Add GitHub Pages deployment workflow"
git push

  5. Automatic deployment:

  6. Documentation deploys automatically on every push to main
  7. Check Actions tab for deployment status

Method 3: Custom Domain (Optional)

Set Up Custom Domain

  1. Add CNAME file: 

    echo "docs.enhancedtoolkits.com" > docs/CNAME

  2. Update mkdocs.yml: 

    site_url: https://docs.enhancedtoolkits.com

  3. Configure DNS:

  4. Add CNAME record: docs.enhancedtoolkits.com → malvavisc0.github.io

  5. Or A records pointing to GitHub Pages IPs

  6. Enable HTTPS:

  7. GitHub Pages automatically provides SSL certificates
  8. Check "Enforce HTTPS" in repository settings

Deployment Configuration

Update mkdocs.yml for GitHub Pages

Ensure your mkdocs.yml has the correct settings:

# Site Information
site_name: Enhanced Toolkits
site_url: https://malvavisc0.github.io/enhancedtoolkits/

# Repository
repo_name: malvavisc0/enhancedtoolkits
repo_url: https://github.com/malvavisc0/enhancedtoolkits
edit_uri: edit/main/docs/

# GitHub Pages specific settings
use_directory_urls: true

Handle MkDocstrings Issues in CI

For GitHub Actions deployment, add this to your workflow:

- name: Install package for MkDocstrings
  run: |
    pip install -e .
  continue-on-error: true  # Continue even if package install fails

- name: Build documentation
  run: mkdocs build

Or disable problematic auto-generated pages in CI:

- name: Build documentation (fallback)
  run: |
    # Remove auto-generated API pages if module import fails
    if ! python -c "import enhancedtoolkits" 2>/dev/null; then
      echo "Module not available, using manual reference only"
      # Remove auto-generated API pages from navigation
      sed -i '/Auto-Generated APIs:/,/Time Value Calculator:/d' mkdocs.yml
    fi
    mkdocs build

Troubleshooting Deployment

Common Issues

1. Build Fails Due to MkDocstrings

Solution: Use manual reference only for deployment 

# Temporarily disable auto-generated APIs
# Edit mkdocs.yml to comment out problematic pages
mkdocs gh-deploy

2. Site Not Updating

Solutions: 

# Force rebuild and deploy
mkdocs gh-deploy --force

# Clear browser cache
# Check GitHub Pages settings

3. 404 Errors

Solutions: - Verify site_url in mkdocs.yml - Check GitHub Pages source branch - Ensure gh-pages branch exists

4. CSS/JS Not Loading

Solution: Use relative paths in mkdocs.yml: 

extra_css:
  - assets/css/custom.css
extra_javascript:
  - assets/js/custom.js

Deployment Checklist

Before deploying:

  • Test locally: mkdocs serve
  • Check all links work
  • Verify images and assets load
  • Test manual reference works
  • Commit all changes to git
  • Push to main branch

Deployment Commands

Quick Deployment

# One-command deployment
mkdocs gh-deploy --clean --message "Deploy documentation"

Development Workflow

# 1. Make documentation changes
# 2. Test locally
mkdocs serve

# 3. Commit changes
git add docs/
git commit -m "Update documentation"
git push

# 4. Deploy to GitHub Pages
mkdocs gh-deploy

Advanced Options

# Deploy with custom commit message
mkdocs gh-deploy --message "Update docs with new API reference"

# Deploy specific branch
mkdocs gh-deploy --remote-branch gh-pages

# Deploy with verbose output
mkdocs gh-deploy --verbose

# Clean build before deploy
mkdocs gh-deploy --clean

Monitoring Deployment

Check Deployment Status

  1. GitHub Actions: Check the Actions tab for build status
  2. GitHub Pages: Check Settings > Pages for deployment status
  3. Site Health: Visit your site URL to verify it's working

Deployment Logs

# View recent deployments
git log --oneline gh-pages

# Check GitHub Pages build logs in repository settings

Best Practices

1. Automated Deployment

  • Use GitHub Actions for automatic deployment
  • Deploy on every push to main branch
  • Include build status badges in README

2. Content Strategy

  • Use manual reference as primary API documentation
  • Enable auto-generated APIs only when module is available
  • Include comprehensive examples and guides

3. Performance

  • Optimize images and assets
  • Use CDN for external resources
  • Enable GitHub Pages caching

4. Maintenance

  • Regular dependency updates
  • Monitor for broken links
  • Keep documentation in sync with code changes

Example Deployment Script

Create scripts/deploy-docs.sh:

#!/bin/bash
set -e

echo "🚀 Deploying Enhanced Toolkits Documentation"

# Test locally first
echo "📋 Testing documentation locally..."
mkdocs serve --dev-addr=127.0.0.1:8001 &
SERVER_PID=$!
sleep 5
kill $SERVER_PID

# Build and deploy
echo "🔨 Building and deploying to GitHub Pages..."
mkdocs gh-deploy --clean --message "Deploy docs: $(date)"

echo "✅ Documentation deployed successfully!"
echo "🌐 Visit: https://malvavisc0.github.io/enhancedtoolkits/"

Make it executable: 

chmod +x scripts/deploy-docs.sh
./scripts/deploy-docs.sh

Result

After deployment, your Enhanced Toolkits documentation will be available at: - Primary URL: https://malvavisc0.github.io/enhancedtoolkits/ - Custom domain (if configured): https://docs.enhancedtoolkits.com/

The site will feature: - Professional documentation with search - Complete API reference (manual + auto-generated) - Responsive design for all devices - Fast loading with GitHub Pages CDN - Automatic HTTPS encryption

Your documentation is now publicly accessible and will update automatically with your chosen deployment method! 🚀