MkDocs GitHub Pages Deployment Workflow

Complete process from local markdown editing to published GitHub Pages site

flowchart TD
    subgraph Local["💻 Local Development"]
        Start["Edit Markdown Files"]:::startNode
        Serve["mkdocs serve
(Preview locally)"]:::processNode
        Build["mkdocs build
(Generate static site)"]:::buildNode
        Decision{"Build
Successful?"}:::decisionNode
        Commit["git add & commit
(Save changes)"]:::gitNode
    end

    subgraph GitHub["🔧 Git/GitHub"]
        Push["git push origin main
(Upload source)"]:::gitNode
        Deploy["mkdocs gh-deploy
(Build + push gh-pages)"]:::gitNode
        Receive["GitHub receives
gh-pages push"]:::githubNode
    end

    subgraph Pages["🌐 GitHub Pages Service"]
        GHBuild["GitHub Pages Build
(Copy to CDN)"]:::githubNode
        CDN["Deploy to CDN
(Global distribution)"]:::githubNode
        Live["🎉 Site Live at
username.github.io/repo/"]:::endNode
    end

    Start --> Serve
    Serve --> Build
    Build --> Decision
    Decision -->|No
Fix errors| Start
    Decision -->|Yes| Commit
    Commit --> Push
    Push --> Deploy
    Deploy --> Receive
    Receive --> GHBuild
    GHBuild --> CDN
    CDN --> Live
    Live -.->|Continue
development| Start

    classDef startNode fill:#43aa8b,stroke:#2d6a4f,stroke-width:3px,color:#fff
    classDef processNode fill:#4facfe,stroke:#3498db,stroke-width:2px,color:#fff
    classDef buildNode fill:#4facfe,stroke:#3498db,stroke-width:2px,color:#fff
    classDef decisionNode fill:#ffd166,stroke:#f77f00,stroke-width:2px,color:#333
    classDef gitNode fill:#f77f00,stroke:#d67000,stroke-width:2px,color:#fff
    classDef githubNode fill:#9b59b6,stroke:#8e44ad,stroke-width:2px,color:#fff
    classDef endNode fill:#43aa8b,stroke:#2d6a4f,stroke-width:3px,color:#fff

Color Legend

Green: Start and successful completion
Blue: Build and verification steps
Orange: Git operations
Purple: GitHub automated processes
Yellow: Decision points

Workflow Details

💻 Local Development (Steps 1-5)

  1. Edit Markdown Files: Author writes content in /docs folder using text editor or IDE
  2. mkdocs serve: Launch local development server on http://localhost:8000 to preview changes
  3. mkdocs build: Generate static site in /site directory to verify build succeeds
  4. Build Successful?: Check for errors in markdown parsing, missing files, or broken links
  5. git add & commit: Stage markdown source files and commit with descriptive message

🔧 Git/GitHub (Steps 6-8)

  1. git push origin main: Upload source commits to GitHub repository main branch
  2. mkdocs gh-deploy: Build site and force-push to gh-pages branch automatically
    Note: gh-deploy handles build + push to gh-pages automatically
  3. GitHub receives gh-pages push: GitHub detects new commits to gh-pages branch

🌐 GitHub Pages Service (Steps 9-11)

  1. GitHub Pages Build: GitHub copies files from gh-pages branch to CDN hosting infrastructure
  2. Deploy to CDN: Site deployed to global CDN with HTTPS enabled
  3. Site Live: Documentation accessible worldwide with custom domain option
    Typical deployment time: 1-2 minutes

Key Concepts

  • Swimlanes: Three distinct areas of responsibility (Local, Git/GitHub, GitHub Pages)
  • Validation Loop: Build errors send you back to editing (step 4 → step 1)
  • Continuous Development: After deployment, cycle continues with new edits
  • Automation: gh-deploy command handles both building and deploying in one step
  • Dual Branches: main branch stores source, gh-pages branch stores built site