Skip to content

GitHub Pages & Documentation Deployment

Branch: gh-docs
Last Updated: December 20, 2025

What is GitHub Pages?

GitHub Pages automatically builds and publishes documentation from your repository. When you push to the gh-docs branch, GitHub:

  1. ✅ Runs MkDocs to build HTML documentation
  2. ✅ Publishes to https://YOUR-ORG.github.io/workspace-setup/
  3. ✅ Updates automatically on every push

Setup GitHub Pages

Step 1: Enable GitHub Pages

  1. Go to https://github.com/Golfklubb-IT/workspace-setup-template/settings/pages
  2. Under Source:
  3. Branch: gh-docs
  4. Folder: / (root)
  5. Click Save

Step 2: Enable GitHub Actions Workflow

The repository includes a GitHub Actions workflow that automatically builds and deploys MkDocs documentation.

File: .github/workflows/deploy-docs.yml

This workflow: - Runs when you push to gh-docs branch - Installs Python and MkDocs - Builds the documentation site - Publishes to GitHub Pages

Step 3: Verify Deployment

After pushing to gh-docs:

  1. Go to https://github.com/Golfklubb-IT/workspace-setup-template/actions
  2. Check the latest workflow run
  3. If ✅ green - documentation is deployed
  4. If ❌ red - check logs for errors

Building Documentation Locally

Install MkDocs

# Install Python (if needed)
# Download from: https://www.python.org/downloads/

# Install MkDocs and theme
pip install mkdocs mkdocs-material

# Verify installation
mkdocs --version

Build Locally

# Navigate to repository
cd c:\Users\owest\Dev\workspace-setup-template

# Run local server
mkdocs serve

# Opens at: http://localhost:8000
# Automatically rebuilds on file changes

Deploy Manually (if needed)

# Build static site
mkdocs build

# This creates `site/` folder with HTML files

# Push to gh-docs branch
git add site/
git commit -m "Docs: Build MkDocs documentation"
git push origin gh-docs

Documentation Structure

docs/
├── index.md                          # Home page
├── DEPLOYMENT_GUIDE.md              # Complete setup walkthrough
├── QUICK_START.md                   # 5-minute quickstart
├── ORGANIZATION_SETUP_GUIDE.md      # Step-by-step setup
├── USER_MANAGEMENT.md               # Managing users
├── GROUP_MANAGEMENT.md              # Managing groups
├── SHARED_DRIVES.md                 # Shared drive setup
├── SECURITY_SETTINGS.md             # Security configuration
├── TROUBLESHOOTING.md               # Common issues & solutions
├── GAM_COMMANDS.md                  # Google Apps Manager reference
├── MIGRATION_PLAYBOOK.md            # Migration from legacy systems
├── ONBOARDING_PLAN.md               # New employee onboarding
├── TEMPLATE_STRUCTURE.md            # Architecture overview
└── PLACEHOLDER_REFERENCE.md         # All configuration variables

Customizing Documentation

Update MkDocs Config

Edit mkdocs.yml to: - Change site name - Add/remove pages - Change theme colors - Add custom CSS

Add New Pages

  1. Create .md file in docs/ folder
  2. Add entry to nav: section in mkdocs.yml
  3. Push to gh-docs branch

Example: 

nav:
  - Custom Page: custom-page.md

Update Theme

Edit mkdocs.yml theme section:

theme:
  name: material
  palette:
    - scheme: default
      primary: blue              # Change primary color
      accent: blue               # Change accent color

Branching Strategy

Branch Purpose Deploy
main Production code ❌ No
gh-docs Documentation only ✅ GitHub Pages
develop Development work ❌ No
feature/* New features ❌ No

Common Tasks

Update Single Page

# Edit documentation
notepad docs/TROUBLESHOOTING.md

# Commit and push
git add docs/TROUBLESHOOTING.md
git commit -m "Docs: Update troubleshooting guide"
git push origin gh-docs

Add New Organization's Documentation

When deploying for a new organization:

# Create organization-specific docs folder
mkdir docs/organizations/YOURORG

# Create setup guide
notepad docs/organizations/YOURORG/setup.md

# Add to mkdocs.yml

Search Documentation

The Material theme includes built-in search. Users can: 1. Click search icon in top right 2. Type keywords 3. Navigate to relevant pages

Troubleshooting GitHub Pages

Workflow Failed

Check GitHub Actions logs: 1. Go to Actions tab 2. Click latest workflow run 3. Check "Build documentation" step 4. Fix errors in markdown/YAML

Common errors: - YAML syntax error - Check mkdocs.yml indentation - Missing file - File referenced in mkdocs.yml doesn't exist - Invalid markdown - Check markdown syntax

Site Not Updating

# Force rebuild
git commit --allow-empty -m "Trigger docs rebuild"
git push origin gh-docs

Can't Find Deployed Site

URL Format: https://GITHUB-USERNAME.github.io/REPO-NAME/

For Golfklubb-IT organization: - URL: https://golfklubb-it.github.io/workspace-setup-template/

Best Practices

✅ DO: - Update docs when code changes - Keep examples current - Use clear headings - Include code blocks with syntax highlighting - Test links locally before pushing

❌ DON'T: - Commit .env files - Include sensitive information - Use very long pages (break into sections) - Forget to push to gh-docs branch

Resources

Last Updated: December 20, 2025