Deployment Workflow Guide¶

This comprehensive guide outlines the deployment workflow for the Ultimate MkDocs Material Guide hosted at www.albrittonanalytics.com. This documentation site leverages GitHub, Netlify, and MkDocs Material to provide a seamless development and deployment experience.

Overview¶

Current Architecture¶

Our deployment architecture follows modern DevOps best practices with automated CI/CD pipelines:

graph TB
    A[Developer] --> B[Feature Branch]
    B --> C[Pull Request]
    C --> D[Preview Deploy]
    D --> E[Review & Approve]
    E --> F[Merge to Main]
    F --> G[Production Deploy]
    G --> H[www.albrittonanalytics.com]

    subgraph "Netlify"
        D
        G
    end

    subgraph "GitHub"
        B
        C
        F
    end

Key Components¶

Component	Technology	Purpose
Source Control	GitHub	Repository hosting and collaboration
Documentation Engine	MkDocs Material	Static site generation
Hosting Platform	Netlify	CDN, hosting, and deployment automation
Domain	www.albrittonanalytics.com	Production domain
CI/CD	Netlify Build	Automated deployment pipeline

Repository Information

Repository: mattsiler/ultimate-mkdocs
Main Branch: main (production)
Build Tool: MkDocs Material 9.5+
Python Version: 3.11.10

Development Workflow¶

1. Setting Up Development Environment¶

Prerequisites¶

# Clone the repository
git clone https://github.com/mattsiler/ultimate-mkdocs.git
cd ultimate-mkdocs

# Install Python dependencies
pip install -r requirements.txt

# Verify installation
mkdocs --version

Local Development Server¶

# Start development server
mkdocs serve

# Access locally at http://localhost:8000
# Auto-reload enabled for real-time editing

Development Best Practices

Always work on feature branches
Test locally before pushing
Use descriptive branch names: feature-, fix-, docs-
Keep commits atomic and well-documented

2. Branch-Based Development Process¶

Creating Feature Branches¶

# Create and switch to feature branch
git checkout -b feature-new-documentation

# Make your changes
# Edit files in docs/ directory

# Test locally
mkdocs serve

# Stage and commit changes
git add .
git commit -m "Add comprehensive API documentation"

# Push feature branch
git push origin feature-new-documentation

Branch Naming Conventions¶

feature-*: New features or content
fix-*: Bug fixes or corrections
docs-*: Documentation improvements
style-*: Design or styling changes
refactor-*: Code reorganization

Content Updates¶

3. Adding New Documentation¶

Creating New Pages¶

# Navigate to appropriate directory
cd docs/

# Create new markdown file
touch new-section/example-page.md

Example Page Template¶

# Page Title

Brief description of the page content.

## Section 1

Content with proper formatting.

### Subsection

!!! note "Important Information"
    Use admonitions for important notes, warnings, and tips.

```python
# Code examples with syntax highlighting
def example_function():
    return "Hello, World!"

Conclusion¶

Summary of the page content.

#### Adding to Navigation
Edit `mkdocs.yml` to include new pages:

```yaml
nav:
  - Home: index.md
  - New Section:
      - new-section/index.md
      - Example Page: new-section/example-page.md

4. Content Guidelines¶

Markdown Best Practices¶

Use consistent heading hierarchy (H1 → H2 → H3)
Include descriptive alt text for images
Use proper link formatting
Leverage MkDocs Material features (admonitions, tabs, etc.)

Asset Management¶

# Add images to assets directory
docs/assets/images/

# Reference in markdown
<img loading="lazy" src="../assets/images/screenshot.png" alt="Description">

# For icons and logos
docs/assets/icons/

Asset Optimization

Optimize images before adding (use WebP when possible)
Keep file sizes reasonable for fast loading
Use descriptive filenames

Preview Deployments¶

5. Pull Request Preview System¶

When you create a pull request, Netlify automatically generates a preview deployment:

Automatic Preview Generation¶

Create Pull Request → GitHub triggers Netlify
Build Process → Netlify runs mkdocs build --verbose
Preview URL → Unique URL generated for testing
Status Check → Build status reported to GitHub

Preview URL Format¶

https://{deploy-id}--ultimate-mkdocs.netlify.app

Accessing Previews¶

GitHub PR Interface: Check status at bottom of PR
Netlify Dashboard: View all preview deployments
Email Notifications: Receive build status updates

6. Testing Preview Deployments¶

Checklist for Preview Review¶

All pages load without errors
Navigation functions correctly
Links work properly (internal and external)
Images and assets display correctly
Mobile responsiveness
Search functionality
Blog feeds and RSS (if applicable)

Preview Environment Differences¶

# Preview builds include:
CONTEXT=deploy-preview
ENABLE_PDF_EXPORT=false
MKDOCS_SERVE_DRAFTS=true  # Shows draft content

Draft Content

Preview deployments show draft content that won't appear in production.

Production Deployments¶

7. Main Branch Deployment Process¶

Automated Production Deployment¶

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub
    participant NL as Netlify
    participant PROD as Production

    Dev->>GH: Merge PR to main
    GH->>NL: Webhook trigger
    NL->>NL: Run build command
    NL->>NL: Deploy to production
    NL->>PROD: Update www.albrittonanalytics.com

Production Build Configuration¶

# netlify.toml production context
[context.production]
  command = "mkdocs build --verbose"

  [context.production.environment]
    CONTEXT = "production"
    ENABLE_PDF_EXPORT = "false"

Build Process Steps¶

Environment Setup: Python 3.11.10, Node.js 18
Dependency Installation: pip install -r requirements.txt
Site Generation: mkdocs build --verbose
Asset Optimization: CSS/JS minification, image optimization
CDN Distribution: Global content delivery network deployment

8. Production Environment Configuration¶

Domain and HTTPS¶

Primary Domain: www.albrittonanalytics.com
SSL Certificate: Automatic Let's Encrypt
CDN: Global Netlify edge network
Performance: Gzip/Brotli compression enabled

Caching Strategy¶

# Static assets (1 year)
Cache-Control = "public, max-age=31536000, immutable"

# HTML content (1 hour)
Cache-Control = "public, max-age=3600"

# RSS feeds (1 hour)
Cache-Control = "public, max-age=3600"

Build Process¶

9. Technical Build Details¶

MkDocs Configuration Highlights¶

# Key plugins and features
plugins:
  - search: # Enhanced search functionality
  - mkdocs-jupyter: # Jupyter notebook support
  - blog: # Blog functionality with RSS
  - rss: # RSS feed generation
  - mkdocstrings: # API documentation
  - glightbox: # Image galleries
  - tags: # Content tagging system

# Performance optimizations
theme:
  features:
    - navigation.instant # SPA-like navigation
    - search.suggest # Search suggestions
    - content.code.copy # Copy code buttons

Build Dependencies¶

# Core requirements
mkdocs>=1.5.0,<2.0.0
mkdocs-material>=9.5.0,<10.0.0
pymdown-extensions>=10.0,<11.0.0

# Content plugins
mkdocs-jupyter>=0.24.0,<1.0.0
mkdocs-rss-plugin>=1.12.0
mkdocs-glightbox>=0.3.0

# Documentation generation
mkdocstrings[python]>=0.24.0,<1.0.0

10. Build Performance Optimization¶

Current Build Settings¶

Timeout: 20 minutes
Python Version: 3.11.10 (specified in netlify.toml)
Caching: Pip dependencies cached
Parallelization: Netlify's build system optimization

Build Time Optimization Strategies¶

# Disable heavy features for faster builds
ENABLE_PDF_EXPORT=false  # PDF generation disabled
# mkdocs-jupyter: execute=false  # Notebook execution disabled

Build Performance

Current build time: ~3-5 minutes for typical content updates

Environment Configuration¶

11. Environment Variables and Contexts¶

Production vs Preview Differences¶

Setting	Production	Preview
Context	`production`	`deploy-preview`
Draft Content	Hidden	Visible
PDF Export	Disabled	Disabled
Analytics	Full tracking	Limited tracking
Cache Headers	Aggressive	Conservative

Environment-Specific Configuration¶

# Production optimizations
if os.getenv('CONTEXT') == 'production':
    # Enable production analytics
    # Disable debug features
    # Optimize for performance

# Preview/development settings
else:
    # Enable draft content
    # Add development tools
    # Relaxed caching

12. Feature Flags and Toggles¶

Available Feature Toggles¶

# PDF Export (resource intensive)
ENABLE_PDF_EXPORT=true/false

# Draft content visibility
MKDOCS_SERVE_DRAFTS=true/false

# Jupyter notebook execution
EXECUTE_NOTEBOOKS=true/false

# Social card generation
ENABLE_SOCIAL_CARDS=true/false

Feature Flag Usage

Use environment variables to enable expensive features only when needed.

Emergency Procedures¶

13. Hotfix Process¶

For urgent production fixes that can't wait for the normal PR process:

Emergency Hotfix Workflow¶

# 1. Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix-critical-issue

# 2. Make minimal necessary changes
# Edit only what's absolutely required

# 3. Test locally
mkdocs serve

# 4. Commit and push
git add .
git commit -m "Hotfix: Critical issue description"
git push origin hotfix-critical-issue

# 5. Create emergency PR
# Mark as urgent, request immediate review

# 6. Fast-track merge to main
# Deployment will trigger automatically

Critical Issue Response¶

Assess Impact: Determine if site is down or has major issues
Create Hotfix Branch: Branch from current main
Minimal Changes: Fix only the critical issue
Fast-Track Review: Request immediate review from team lead
Emergency Deploy: Merge to main for immediate deployment

14. Rollback Procedures¶

Automatic Rollback Options¶

# Via Netlify Dashboard
1. Go to Netlify dashboard
2. Select "Deploys" tab
3. Find previous working deployment
4. Click "Publish deploy"

Git-Based Rollback¶

# Revert to previous commit
git revert <commit-hash>
git push origin main

# Or reset to previous state (use cautiously)
git reset --hard <previous-commit>
git push --force origin main

Rollback Considerations

Always prefer git revert over git reset --hard
Communicate rollbacks to the team immediately
Document the issue and rollback reason

15. Monitoring and Health Checks¶

Automated Monitoring¶

Uptime Monitoring: Netlify status checks
Performance Monitoring: Core Web Vitals tracking
Build Monitoring: Failed build notifications
SSL Certificate: Automatic renewal monitoring

Manual Health Checks¶

# Quick site verification
curl -I https://www.albrittonanalytics.com

# Check key pages
curl -f https://www.albrittonanalytics.com/
curl -f https://www.albrittonanalytics.com/getting-started/
curl -f https://www.albrittonanalytics.com/api/

# Verify RSS feed
curl -f https://www.albrittonanalytics.com/feed_rss_created.xml

Best Practices¶

16. Development Best Practices¶

Content Creation Guidelines¶

Consistency: Follow established patterns and styles
Documentation: Include clear descriptions and examples
Testing: Test all links and functionality locally
Accessibility: Use semantic HTML and proper alt text
Performance: Optimize images and avoid large assets

Code Quality Standards¶

# mkdocs.yml structure
- Use consistent indentation (2 spaces)
- Group related configurations
- Comment complex configurations
- Follow semantic versioning for dependencies

# Markdown standards
- Use consistent heading hierarchy
- Include descriptive alt text for images
- Use proper code fence languages
- Leverage MkDocs Material features appropriately

17. Collaboration Workflows¶

Multi-Developer Coordination¶

# Before starting work
git checkout main
git pull origin main
git checkout -b feature-your-feature

# Regular synchronization
git fetch origin
git rebase origin/main

# Before creating PR
git rebase origin/main  # Ensure clean history
git push origin feature-your-feature

Review Process¶

Self-Review: Review your own changes first
Draft PR: Create draft PR for early feedback
Team Review: Request review from relevant team members
Address Feedback: Make requested changes promptly
Final Approval: Obtain approval before merging

18. Content Maintenance¶

Regular Maintenance Tasks¶

Monthly: Review and update outdated links
Quarterly: Check for plugin and dependency updates
Annually: Review and refresh content for accuracy
As Needed: Fix broken links and formatting issues

Content Audit Checklist¶

All external links functional
Screenshots and images current
Code examples tested and working
Documentation reflects current features
Search functionality working properly
Mobile responsiveness maintained

Advanced Configuration¶

19. Custom Domain Management¶

Domain Configuration¶

Primary Domain: www.albrittonanalytics.com
DNS Provider: [Your DNS provider]
Netlify DNS: Automatic HTTPS and CDN

SSL/TLS Configuration¶

Certificate Type: Let's Encrypt (automatic)
Renewal: Automatic (Netlify managed)
HSTS: Enabled with 1-year max-age
Security Headers: Comprehensive security policy

20. Performance Optimization¶

Current Performance Metrics¶

First Contentful Paint: < 1.5s
Largest Contentful Paint: < 2.5s
Time to Interactive: < 3.5s
Cumulative Layout Shift: < 0.1

Optimization Strategies¶

# Asset compression
[build.processing.css]
  bundle = true
  minify = true

[build.processing.js]
  bundle = true
  minify = true

# Caching headers
Cache-Control = "public, max-age=31536000, immutable"

Performance Results

Our current configuration achieves excellent Core Web Vitals scores and fast load times globally.

Troubleshooting¶

21. Common Issues and Solutions¶

Build Failures¶

# Common causes and solutions:

1. Dependency conflicts
   Solution: Update requirements.txt, clear cache

2. Markdown syntax errors
   Solution: Validate markdown, check for typos

3. Missing files or broken links
   Solution: Use mkdocs serve locally to identify issues

4. Plugin configuration errors
   Solution: Review mkdocs.yml for syntax errors

Deployment Issues¶

# Debug deployment problems:

1. Check Netlify deploy logs
2. Verify netlify.toml configuration
3. Test build command locally:
   mkdocs build --verbose

4. Check for environment variable issues

22. Getting Help¶

Support Resources¶

Documentation: MkDocs Material Documentation
Netlify Support: Netlify Documentation
Team Contact: Repository Issues

Escalation Process¶

Self-Service: Check this documentation first
Team Discussion: Post in team chat/discussion
Create Issue: File detailed GitHub issue
Emergency Contact: Use emergency contact for critical issues

Quick Reference¶

Essential Commands¶

# Local development
mkdocs serve

# Build site
mkdocs build

# Create feature branch
git checkout -b feature-name

# Deploy to production
git push origin main  # (after PR merge)

Important URLs¶

Production: https://www.albrittonanalytics.com
Repository: https://github.com/mattsiler/ultimate-mkdocs
Netlify Dashboard: [Your Netlify dashboard]

Emergency Contacts¶

Site Down: [Emergency contact procedure]
Build Issues: [Technical team contact]
Content Issues: [Content team contact]

Documentation Updates

This workflow guide is regularly updated. Last revision: {{ git.date.strftime('%B %Y') }}