Skip to content

Publishing and Deployment

Estimated time to read: 4 minutes

Publishing and Deployment

The final step in creating workshop documentation is making it accessible through reliable publishing platforms. This lab covers deploying MkDocs documentation using GitHub Pages with automated workflows.

What You'll Learn

  • Deploy MkDocs documentation to GitHub Pages
  • Set up automated deployment workflows
  • Configure basic maintenance processes
  • Monitor site performance

Prerequisites

  • Completion of Lab 5: AI-Assisted Content Creation
  • A complete MkDocs workshop project
  • GitHub account with repository access
  • Basic understanding of Git workflows

Introduction

Publishing workshop documentation effectively ensures consistent availability, professional presentation, and easy maintenance. GitHub Pages provides an ideal platform because it integrates seamlessly with your development workflow and offers robust performance at no cost for public repositories.

Lab Exercise

You'll deploy your workshop documentation to GitHub Pages with automated deployment workflows.

Step 1: Prepare Your Repository

Ensure your repository is ready for GitHub Pages deployment.

  1. Verify your repository structure:

    Text Only
    1
2
3
4
5
6
7
    your-workshop-repo/
├── docs/
│   ├── docs/
│   │   └── en/ (your content)
│   ├── mkdocs.yml
│   └── requirements.txt
└── README.md

  2. Update your mkdocs.yml for deployment:

    YAML
    1
2
3
4
5
6
7
8
9
    site_name: Your Workshop Name
site_url: https://yourusername.github.io/your-repo-name/

# Essential configuration
theme:
  name: material

plugins:
  - search

  3. Commit and push your changes:

    Bash
    1
2
3
    git add .
git commit -m "Prepare for GitHub Pages deployment"
git push origin main

Step 2: Create GitHub Actions Workflow

Set up automated deployment using GitHub Actions.

  1. Create the workflow directory:

    Bash
    1
    mkdir -p .github/workflows

  2. Create .github/workflows/deploy.yml:

    YAML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
    name: Deploy MkDocs

on:
  push:
    branches: [main]

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

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: pip install -r docs/requirements.txt
      - run: mkdocs gh-deploy --force --config-file docs/mkdocs.yml

Step 3: Enable GitHub Pages

Configure GitHub Pages settings in your repository.

  1. Go to your repository settings
  2. Navigate to Pages section
  3. Select "Deploy from a branch"
  4. Choose "gh-pages" branch
  5. Select "/ (root)" folder
  6. Save the settings

Step 4: Verify Deployment

Ensure your site is working correctly.

  1. Check the Actions tab for successful workflow completion
  2. Visit your site at https://yourusername.github.io/your-repo-name/
  3. Test all navigation and verify content renders properly

Best Practices for Maintenance

Regular Updates

  • Monthly: Test all code examples and check for broken links
  • Quarterly: Update screenshots and refresh external resources
  • Annually: Complete content audit and refresh examples

Feedback Collection

Set up ways to collect participant feedback:

  • Create issue templates in your repository
  • Add feedback forms to lab pages
  • Monitor usage analytics (if using Google Analytics)

Exercise Results

After completing this lab, you should have:

  • ✅ A deployed workshop site on GitHub Pages
  • ✅ Automated deployment workflow
  • ✅ Maintenance processes for keeping content current
  • ✅ Professional presentation for your learners

Workshop Complete!

Congratulations! You've created a comprehensive workshop documentation system using best practices for audience analysis, content design, MkDocs implementation, advanced features, AI assistance, and professional deployment.

Troubleshooting Deployment

Issue: "GitHub Actions workflow fails"
Solution: Check the Actions tab for specific error messages. Ensure your requirements.txt and mkdocs.yml paths are correct.

Issue: "Site shows 404 error"
Solution: Verify the gh-pages branch was created and contains a built site. Check your Pages settings in repository configuration.

Issue: "Site loads but styling is broken"
Solution: Ensure your site_url in mkdocs.yml matches your actual GitHub Pages URL exactly.