Skip to content

Documentation Site Deployment Guide

Overview

Deploy the comprehensive MkDocs Material documentation portal to docs.hgcontent.com for production use.

Note: Internal documentation is deployed separately to Cloudflare Pages at https://dev.hgcontent.com and protected by Cloudflare Access.

Deployment Options

Primary: GitHub Pages (Chosen Platform)

Advantages: Free, versioned deploys via mike, simple CNAME support, tight GitHub integration Production Setup:

  1. Review .github/workflows/docs.yml (already configured for build + mike deploy)
  2. Ensure gh-pages branch exists and contains CNAME with docs.hgcontent.com
  3. Push to main (or tag a release) to trigger build and versioned deploy
  4. Confirm deployment in Actions logs and that docs.hgcontent.com serves the new version

Alternative: Vercel Deployment

Advantages: Edge performance, preview deployments Use Case: If you need Vercel-specific features

Build Command: pip install -r requirements-docs.txt && mkdocs build
Output Directory: site
Install Command: pip install -r requirements-docs.txt

Alternative: Netlify Deployment

Advantages: Form handling, split testing, edge functions Use Case: If advanced form processing needed

Build command: pip install -r requirements-docs.txt && mkdocs build
Publish directory: site

Custom Domain Setup

DNS Configuration (GitHub Pages)

# Add CNAME record for GitHub Pages (Cloudflare DNS)
docs.hgcontent.com → cvsloane.github.io  (DNS only, no proxy)

GitHub Pages will serve the site from the gh-pages branch and respect the CNAME file.

SSL Certificate

  • GitHub Pages: Automatic Let's Encrypt (recommended)
  • Vercel: Automatic SSL (if using Vercel alternative)
  • Custom: Configure Let's Encrypt or purchase certificate

Version Management

Mike Configuration

# Deploy development version
mike deploy dev --push

# Deploy production version  
mike deploy 1.0 latest --push

# Set default version
mike set-default latest --push

# List versions
mike list

Version Strategy

  • dev - Latest development (main branch)
  • 1.0, 1.1, etc. - Tagged releases
  • latest - Latest stable release

Analytics Integration

Google Analytics 4

# In mkdocs.yml
extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

Plausible Analytics (Privacy-focused)

<!-- In mkdocs.yml theme.custom_dir/main.html -->
<script defer data-domain="docs.hgcontent.com" src="https://plausible.io/js/plausible.js"></script>

Search Optimization

Apply for Algolia DocSearch

  1. Visit https://docsearch.algolia.com/apply/
  2. Submit documentation site URL
  3. Configure once approved:
# In mkdocs.yml
extra:
  search:
    provider: algolia
    app_id: YOUR_APP_ID
    api_key: YOUR_API_KEY  
    index_name: hgcontent-docs

Performance Optimization

CDN Configuration (Vercel)

  • Vercel Edge Network: Built-in global CDN with 40+ regions
  • Automatic optimization: Image optimization, compression, caching
  • Edge Functions: Server-side logic at the edge (if needed)
  • Additional CDN: Optional Cloudflare for extra caching layer

Image Optimization

# Optimize images before build
find docs -name "*.png" -exec optipng {} \;
find docs -name "*.jpg" -exec jpegoptim {} \;

Build Optimization

# In mkdocs.yml
plugins:
  - search
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true

Monitoring and Maintenance

Health Checks

# Test documentation build locally
mkdocs build --strict

# Check for broken links
linkchecker site/

# Validate OpenAPI specs
swagger-codegen validate openapi/hgcontent-api-v1.yaml

Automated Updates

# GitHub Actions already configured for:
- Build validation on PRs
- Automatic deployment on merge
- Link checking
- OpenAPI validation
- Build report generation

Integration with Marketing Site

// In apps/frontend/components/layout/PublicFooter.tsx
const documentationLinks = [
  {
    href: "https://docs.hgcontent.com",
    label: "Documentation"
  },
  {
    href: "https://docs.hgcontent.com/api", 
    label: "API Reference"
  },
  {
    href: "https://docs.hgcontent.com/api/python-sdk",
    label: "Python SDK"
  },
  {
    href: "https://docs.hgcontent.com/api/typescript-sdk", 
    label: "TypeScript SDK"
  },
  {
    href: "https://docs.hgcontent.com/getting-started",
    label: "Quick Start"
  }
]

Developer Dropdown

// In apps/frontend/components/layout/PublicHeader.tsx
const developerMenuItems = [
  {
    href: "https://docs.hgcontent.com",
    label: "Documentation",
    description: "Complete guides and API reference"
  },
  {
    href: "https://docs.hgcontent.com/api/openapi-spec",
    label: "API Explorer", 
    description: "Interactive API documentation"
  },
  {
    href: "https://docs.hgcontent.com/api/python-sdk",
    label: "Python SDK",
    description: "Python client library"
  },
  {
    href: "https://docs.hgcontent.com/api/typescript-sdk",
    label: "TypeScript SDK", 
    description: "TypeScript/JavaScript client"
  }
]

Deployment Checklist

Pre-Deployment

  • Test build locally with mkdocs serve
  • Validate all links with linkchecker site/
  • Check OpenAPI specs are valid
  • Verify all images are optimized
  • Test responsive design on mobile
  • Review navigation structure

Domain Configuration

  • Configure DNS CNAME record
  • Set up SSL certificate
  • Test domain resolution
  • Configure redirects if needed
  • Set up www redirect (docs.hgcontent.com)

Analytics Setup

  • Configure Google Analytics 4
  • Set up Plausible Analytics
  • Apply for Algolia DocSearch
  • Test tracking is working
  • Set up goal tracking

Production Deployment

  • Deploy via chosen platform
  • Test all pages load correctly
  • Verify search functionality
  • Test mobile responsiveness
  • Check page load speeds
  • Validate SSL certificate

Marketing Integration

  • Update marketing site footer links
  • Add developer dropdown menu
  • Test cross-linking between sites
  • Update About page with documentation links
  • Add documentation to Contact/Support page

Post-Deployment

  • Submit to search engines
  • Add to Google Search Console
  • Monitor analytics for usage
  • Collect user feedback
  • Plan regular content updates

Troubleshooting

Common Issues

Build Fails 

# Check for syntax errors
mkdocs build --strict

# Validate requirements
pip install -r requirements-docs.txt

Custom Domain Not Working - Verify DNS propagation (24-48 hours) - Check CNAME record configuration - Ensure SSL certificate is issued

Search Not Working - Verify search plugin is enabled - Check JavaScript is not blocked - Apply for Algolia DocSearch for better search

Slow Load Times - Enable CDN (Cloudflare recommended) - Optimize images and assets - Enable compression/minification

Support Resources

  • MkDocs Material: https://squidfunk.github.io/mkdocs-material/
  • GitHub Pages: https://docs.github.com/en/pages
  • Vercel: https://vercel.com/docs
  • Netlify: https://docs.netlify.com/
  • Algolia DocSearch: https://docsearch.algolia.com/

Maintenance Schedule

Daily

  • Monitor build status
  • Check for broken links
  • Review user feedback

Weekly

  • Update content based on feedback
  • Review analytics data
  • Check search query performance

Monthly

  • Update dependencies
  • Review and optimize performance
  • Plan content improvements
  • Update API documentation

Quarterly

  • Major content review
  • User experience assessment
  • SEO optimization
  • Platform evaluation