Documentation Deployment Guide¶

Complete guide to deploying the n8n MCP Workflow Builder documentation to GitHub Pages with CI/CD automation.

Overview¶

This project uses MkDocs Material with automated GitHub Actions deployment to GitHub Pages. Every push to the main branch automatically builds and deploys the documentation.

Deployment Stack:

Static Site Generator: MkDocs Material
Hosting: GitHub Pages
CI/CD: GitHub Actions
URL: https://salacoste.github.io/mcp-n8n-workflow-builder

Quick Start¶

Prerequisites¶

GitHub repository with documentation in docs/ directory
MkDocs Material configuration file (mkdocs.yml)
Python 3.11+ for local development

Deploy to Production¶

# 1. Ensure all changes are committed
git status

# 2. Push to main branch
git push origin main

# 3. Monitor deployment
gh run watch

# 4. Verify deployment
open https://salacoste.github.io/mcp-n8n-workflow-builder

Deployment Time: ~2-3 minutes

Architecture¶

Deployment Pipeline¶

graph TB
    A[Developer commits to main] --> B{CI/CD Workflow}
    B --> C[Checkout code]
    C --> D[Setup Python 3.11]
    D --> E[Install dependencies]
    E --> F[Build with MkDocs]
    F --> G{Build successful?}
    G -->|Yes| H[Deploy to gh-pages]
    G -->|No| I[Fail deployment]
    H --> J[GitHub Pages serves site]
    J --> K[Site live at github.io]

    style A fill:#e1f5ff
    style F fill:#fff4e6
    style H fill:#e8f5e9
    style K fill:#f3e5f5

Build Process¶

1. Checkout repository (fetch-depth: 0 for git revision dates)
    ↓
2. Setup Python 3.11 with pip caching
    ↓
3. Install MkDocs dependencies from requirements.txt
    ↓
4. Run: mkdocs build --strict --verbose
    ↓
5. Validate: No errors or warnings
    ↓
6. Deploy: Upload to gh-pages branch
    ↓
7. GitHub Pages: Serve static site

GitHub Actions Workflow¶

Current Deployment Workflow¶

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

Triggers:

Push to main branch with changes to:
docs/** (any documentation file)
mkdocs.yml (configuration changes)
.github/workflows/deploy-docs.yml (workflow changes)

Manual trigger: Available via GitHub Actions UI (workflow_dispatch)

Key Features:

Strict Mode: mkdocs build --strict fails on warnings
Git History: Full fetch for revision dates
Caching: Python dependencies cached for faster builds
Atomic Deployment: Uses peaceiris/actions-gh-pages@v3
Bot Identity: Commits as github-actions[bot]

Workflow Configuration¶

name: Deploy Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - '.github/workflows/deploy-docs.yml'
  workflow_dispatch:

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

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for git-revision-date plugin

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Build documentation
        run: mkdocs build --strict --verbose

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
          publish_branch: gh-pages
          user_name: 'github-actions[bot]'
          user_email: 'github-actions[bot]@users.noreply.github.com'
          commit_message: 'docs: deploy documentation ${{ github.sha }}'

Local Development¶

Setup Development Environment¶

# 1. Clone repository
git clone https://github.com/salacoste/mcp-n8n-workflow-builder.git
cd mcp-n8n-workflow-builder

# 2. Install Python dependencies
pip install -r requirements.txt

# Or install individually:
pip install mkdocs-material
pip install mkdocs-git-revision-date-localized-plugin
pip install mkdocs-minify-plugin

Serve Documentation Locally¶

# Start development server
mkdocs serve

# Server starts at: http://localhost:8000
# Live reload enabled - changes appear automatically

Development Server Features:

Live Reload: Automatic refresh on file changes
Fast Builds: Incremental builds during development
Error Display: Build errors shown in browser
Port Configuration: Use mkdocs serve -a 0.0.0.0:8080 for custom port

Build for Production¶

# Build static site with strict validation
mkdocs build --strict --verbose

# Output directory: ./site/
# Contains: HTML, CSS, JS, images, search index

Build Validation:

# Check for warnings
mkdocs build --strict 2>&1 | grep -i "warning"

# Verify output
ls -lh site/
find site -name "*.html" | wc -l

# Check total size
du -sh site/

Pre-Deployment Checklist¶

1. Content Validation¶

All documentation pages complete and reviewed
Code examples tested and working
Screenshots current and accurate
No placeholder content (TODO, Lorem ipsum)
Spelling and grammar checked
Technical accuracy verified

Validation Commands:

# Build in strict mode (fails on warnings)
mkdocs build --strict

# Check for TODOs
grep -r "TODO\|FIXME\|XXX" docs/

# Check for placeholder content
grep -r "Lorem ipsum" docs/

2. Build Quality¶

Build completes without errors
Build completes without warnings
All pages render correctly
Search index generated successfully
Navigation structure correct

Quality Checks:

# Strict build with verbose output
mkdocs build --strict --verbose

# Verify search index
ls -lh site/search/search_index.json

# Check navigation
cat site/sitemap.xml

3. Link Validation¶

All internal links working
External links accessible
No broken anchors
Cross-references valid

Link Checking:

# Install link checker
npm install -g markdown-link-check

# Check all markdown files
find docs -name "*.md" -exec markdown-link-check {} \;

# Or use broken-link-checker on built site
npm install -g broken-link-checker
mkdocs serve &
sleep 5
blc http://localhost:8000 -ro

4. Performance Validation¶

Performance Checks:

# Check total size
du -sh site/

# Find largest files
find site -type f -exec du -h {} + | sort -rh | head -20

# Verify minification
ls -lh site/assets/stylesheets/*.css
ls -lh site/assets/javascripts/*.js

5. Accessibility Validation¶

Accessibility Testing:

# Install pa11y
npm install -g pa11y-ci

# Serve site locally
mkdocs serve &
sleep 5

# Run accessibility tests
pa11y http://localhost:8000
pa11y http://localhost:8000/getting-started/
pa11y http://localhost:8000/api/overview/

6. SEO Validation¶

Page titles descriptive and unique
Meta descriptions on all pages
Keywords defined appropriately
sitemap.xml generated
robots.txt configured (if needed)

SEO Checks:

# Verify sitemap
cat site/sitemap.xml | head -50

# Check for duplicate titles
grep -r "<title>" site/ | sort | uniq -d

# Verify meta descriptions
grep -r '<meta name="description"' site/ | head -10

GitHub Pages Configuration¶

Step 1: Enable GitHub Pages¶

Navigate to repository Settings → Pages
Configure source:
Source: GitHub Actions (recommended)
Branch: main (or gh-pages if using branch deployment)
Enforce HTTPS: ✅ Enabled (default)
Click Save

Step 2: Verify Workflow Permissions¶

Navigate to Settings → Actions → General
Workflow permissions:
✅ Read and write permissions
✅ Allow GitHub Actions to create and approve pull requests
Click Save

Step 3: First Deployment¶

# Ensure you're on main branch
git checkout main

# Commit all changes
git add .
git commit -m "docs: initial GitHub Pages deployment"

# Push to trigger deployment
git push origin main

Step 4: Monitor Deployment¶

# Watch workflow execution
gh run watch

# Or view in GitHub UI:
# Actions tab → Deploy Documentation workflow

Step 5: Verify Deployment¶

Expected URL:

https://salacoste.github.io/mcp-n8n-workflow-builder/

Verification Steps:

# Check homepage
curl -I https://salacoste.github.io/mcp-n8n-workflow-builder/

# Test critical pages
curl -I https://salacoste.github.io/mcp-n8n-workflow-builder/getting-started/
curl -I https://salacoste.github.io/mcp-n8n-workflow-builder/api/overview/

# All should return: HTTP/2 200

Custom Domain Setup (Optional)¶

DNS Configuration¶

Subdomain Approach (Recommended):

Example: docs.yourproject.com

DNS Records:

Type	Name	Value	TTL
CNAME	docs	salacoste.github.io	3600

Configuration Steps:

Add CNAME Record in DNS Provider:

Type: CNAME
Name: docs
Value: salacoste.github.io
TTL: 3600 (1 hour)

Create CNAME File:

File: docs/CNAME

docs.yourproject.com

Update mkdocs.yml:
```
site_url: https://docs.yourproject.com
```

Commit and Push:

git add docs/CNAME mkdocs.yml
git commit -m "docs: configure custom domain"
git push origin main

Configure GitHub Pages:
Go to Settings → Pages
Under Custom domain, enter: docs.yourproject.com
Click Save
Wait for DNS check (green checkmark appears)
✅ Enforce HTTPS (enabled after SSL provision)

SSL Certificate Provisioning¶

Timeline:

DNS Propagation: 5 minutes - 48 hours (typically <2 hours)
SSL Certificate: 15 minutes - 24 hours after DNS propagation

Verification:

# Check DNS resolution
dig docs.yourproject.com

# Expected output:
# docs.yourproject.com. 3600 IN CNAME salacoste.github.io.

# Check SSL certificate
openssl s_client -connect docs.yourproject.com:443 -servername docs.yourproject.com | grep -A 2 "Certificate chain"

# Test HTTPS redirect
curl -I http://docs.yourproject.com
# Should return: HTTP/1.1 301 Moved Permanently
# Location: https://docs.yourproject.com/

Performance Optimization¶

Current Optimizations¶

MkDocs Configuration:

# Minification (enabled)
plugins:
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true

# Search optimization
plugins:
  - search:
      prebuild_index: true
      lang: en

Performance Results:

HTML Minification: ~30% size reduction
CSS Minification: ~40% size reduction
JS Minification: ~50% size reduction
Prebuilt Search Index: Faster initial search

Image Optimization¶

Guidelines:

# Install image optimization tools
brew install webp jpegoptim pngquant

# Optimize PNG images
for img in docs/assets/images/**/*.png; do
  pngquant --quality=80-90 --force --ext .png "$img"
done

# Optimize JPEG images
for img in docs/assets/images/**/*.{jpg,jpeg}; do
  jpegoptim --max=85 "$img"
done

# Convert to WebP
for img in docs/assets/images/**/*.{png,jpg,jpeg}; do
  cwebp -q 80 "$img" -o "${img%.*}.webp"
done

Best Practices:

Maximum resolution: 1280x720 for screenshots
File size target: <200KB per image
Use WebP with PNG/JPEG fallback
Lazy loading enabled by default (Material theme)

Performance Targets¶

Metric	Target	Current	Status
Total Site Size	<20MB	Check build	Monitor
Page Load Time	<2s	Test live	Monitor
First Contentful Paint	<1.5s	Test live	Monitor
Search Response	<500ms	Test live	Monitor

Performance Testing:

# Google PageSpeed Insights
open "https://pagespeed.web.dev/analysis?url=https://salacoste.github.io/mcp-n8n-workflow-builder"

# Lighthouse (local)
npm install -g lighthouse
lighthouse https://salacoste.github.io/mcp-n8n-workflow-builder --view

Build Validation¶

Strict Mode Builds¶

The deployment workflow uses mkdocs build --strict to catch issues:

What Strict Mode Catches:

Missing files referenced in navigation
Broken internal links
Invalid markdown syntax
Plugin errors
Theme configuration issues

Local Validation:

# Run strict build locally before pushing
mkdocs build --strict --verbose

# Check for warnings
mkdocs build --strict 2>&1 | grep -i "warning"

# Clean build (remove previous build)
rm -rf site/
mkdocs build --strict

Link Checking¶

Manual Link Validation:

# Install markdown-link-check
npm install -g markdown-link-check

# Check all markdown files
find docs -name "*.md" -exec markdown-link-check {} \;

# Check built HTML (more comprehensive)
npm install -g broken-link-checker
mkdocs serve &
sleep 5
blc http://localhost:8000 -ro --filter-level 3

Deployment Workflow Details¶

Workflow File Location¶

.github/workflows/deploy-docs.yml

Workflow Steps Explained¶

1. Checkout Repository:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full git history for revision dates

Why: The mkdocs-git-revision-date-localized-plugin needs full git history to show "Last updated" dates on pages.

2. Setup Python:

- uses: actions/setup-python@v4
  with:
    python-version: '3.11'

Why: MkDocs requires Python 3.8+, we use 3.11 for best compatibility.

3. Install Dependencies:

- run: pip install -r requirements.txt

Dependencies (requirements.txt):

mkdocs==1.5.3
mkdocs-material==9.5.3
mkdocs-git-revision-date-localized-plugin==1.2.2
mkdocs-minify-plugin==0.8.0
pymdown-extensions==10.7

4. Build Documentation:

- run: mkdocs build --strict

Why: Strict mode ensures quality by failing on warnings. Prevents broken builds from deploying.

5. Deploy to GitHub Pages:

- uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./site
    publish_branch: gh-pages

Why: Deploys built site to gh-pages branch, which GitHub Pages serves.

Troubleshooting¶

Build Fails with "Warning" Error¶

Symptoms:

ERROR - Build failed with strict mode warning

Diagnosis:

# Run build locally to see warnings
mkdocs build --strict --verbose

# Common causes:
# - Missing files in navigation
# - Broken internal links
# - Invalid markdown syntax

Solutions:

Fix broken links:

# ❌ Wrong:
[Link](non-existent-file.md)

# ✅ Correct:
[Link](../path/to/existing-file.md)

Remove missing nav entries:

# mkdocs.yml
nav:
  # - Missing Page: missing-file.md  # Remove or fix
  - Existing Page: existing-file.md

Fix markdown syntax:

# ❌ Wrong: Missing closing backtick
```typescript
const code = "example"

# ✅ Correct:
```typescript
const code = "example"
```(with closing backticks)

Deployment Succeeds but Site Not Updated¶

Symptoms: Workflow succeeds but changes don't appear on live site

Diagnosis:

Check deployment status:
```
gh run list --workflow=deploy-docs.yml
```

Verify gh-pages branch updated:

git fetch origin
git log origin/gh-pages -1

Check GitHub Pages settings:
Settings → Pages → Branch should show gh-pages

Solutions:

Clear browser cache:
Hard reload: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
Incognito window
Wait for CDN propagation:
GitHub Pages CDN may take 1-5 minutes to update
Check again after 10 minutes

Verify deployment commit:

# Check gh-pages branch
git checkout gh-pages
git log -1
ls -la

Permission Denied Errors¶

Symptoms:

Error: Resource not accessible by integration

Solutions:

Enable workflow permissions:
Settings → Actions → General
Workflow permissions → Read and write permissions
Save

Check GITHUB_TOKEN permissions:

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

Custom Domain Not Working¶

Symptoms: Custom domain shows 404 or doesn't resolve

Solutions:

Verify DNS propagation:

dig docs.yourproject.com
# Should show CNAME to salacoste.github.io

Check CNAME file:

cat docs/CNAME
# Should contain: docs.yourproject.com

Verify GitHub Pages settings:
Settings → Pages → Custom domain
Green checkmark next to domain
HTTPS enforcement enabled (after SSL provision)
Wait for SSL certificate:
Can take up to 24 hours after DNS propagation
Disable and re-enable "Enforce HTTPS" if needed

Monitoring & Maintenance¶

Deployment Monitoring¶

GitHub Actions:

# List recent deployments
gh run list --workflow=deploy-docs.yml --limit 10

# View specific run
gh run view <run-id>

# Watch live deployment
gh run watch

Deployment History:

View all deployments: Repository → Actions → Deploy Documentation
Check deployment times, success/failure rates
Review build logs for issues

Regular Maintenance¶

Weekly:

Review deployment logs
Check for build warnings
Verify site accessibility
Monitor page load times

Monthly:

Run link checker
Update dependencies (pip list --outdated)
Review analytics (if configured)
Test from multiple devices/browsers

Quarterly:

Comprehensive content audit
Update MkDocs and plugins
Performance optimization review
Accessibility audit

Dependency Updates¶

Check for Updates:

# List outdated Python packages
pip list --outdated

# Check for security vulnerabilities
pip install pip-audit
pip-audit

Update Dependencies:

# Update specific package
pip install --upgrade mkdocs-material

# Update all packages (test thoroughly first!)
pip install --upgrade -r requirements.txt

# Update requirements.txt
pip freeze > requirements.txt

Testing After Updates:

# Clean build
rm -rf site/
mkdocs build --strict

# Serve locally and test
mkdocs serve

# Test all critical pages manually

Rollback Procedures¶

Rollback via Git¶

Revert to Previous Commit:

# Find commit to rollback to
git log --oneline -10

# Revert specific commit
git revert <commit-sha>
git push origin main

# Or reset to previous commit (use with caution)
git reset --hard <commit-sha>
git push --force origin main

Manual Deployment of Specific Version¶

# Checkout specific commit
git checkout <commit-sha>

# Build documentation
mkdocs build --strict

# Deploy to gh-pages branch
mkdocs gh-deploy --force

# Return to main
git checkout main

Emergency Rollback¶

# Disable automatic deployment
# 1. Go to Settings → Actions → Disable workflows
# 2. Or rename .github/workflows/deploy-docs.yml temporarily

# Manually deploy previous version
git checkout <last-good-commit>
mkdocs build --strict
mkdocs gh-deploy --force

# Or use GitHub Actions manual dispatch with specific commit

Best Practices¶

Deployment Strategy¶

1. Test Locally First:

# Always build locally before pushing
mkdocs build --strict --verbose

# Serve and visually inspect
mkdocs serve

# Test critical workflows

2. Use Pull Requests:

# Create feature branch
git checkout -b docs/update-api-reference

# Make changes
# ...

# Push and create PR
git push origin docs/update-api-reference
gh pr create

# Review preview build in PR checks
# Merge only after validation passes

3. Monitor Deployments:

# Set up GitHub notifications
# Settings → Notifications → Actions

# Watch for workflow failures
gh run list --workflow=deploy-docs.yml

# Set up external monitoring (UptimeRobot, Pingdom)

Content Best Practices¶

1. Atomic Commits:

# ✅ Good: Focused commits
git commit -m "docs: update workflows API examples"
git commit -m "docs: fix broken link in multi-instance guide"

# ❌ Avoid: Large mixed commits
git commit -m "docs: update everything"

2. Descriptive Commit Messages:

# ✅ Good:
git commit -m "docs: add Python examples to workflows API reference"
git commit -m "docs: fix typo in installation guide"
git commit -m "docs: update architecture diagram with new components"

# ❌ Avoid:
git commit -m "fix"
git commit -m "update docs"

3. Review Before Merging:

Preview changes locally
Check for broken links
Validate code examples
Test on mobile viewport
Review spelling and grammar

Performance Optimization Tips¶

1. Lazy Loading Images¶

Material theme enables lazy loading by default:

![Architecture diagram](../assets/images/architecture.png)
<!-- Automatically lazy loaded if below fold -->

2. Code Block Optimization¶

# ✅ Good: Syntax highlighting with appropriate language
```typescript
interface WorkflowParams {
  name: string;
  nodes: Node[];
}
```(with closing backticks)

# ❌ Avoid: Generic code blocks (larger highlight.js bundle)

some code here ```(with closing backticks)

### 3. Search Index Optimization

```yaml
# mkdocs.yml
plugins:
  - search:
      prebuild_index: true  # Faster initial search
      lang: en
      indexing: 'full'      # Index all content

Exclude from Search (if needed):

<!-- search: exclude -->
# This section won't be indexed

Large code blocks or reference tables can be excluded.

Security Considerations¶

Sensitive Information¶

Never commit:

API keys or tokens
Passwords or credentials
Personal identifiable information (PII)
Internal URLs or system details

Validation:

# Search for potential secrets
grep -r "api_key\|password\|secret\|token" docs/

# Check git history for accidentally committed secrets
git log -p | grep -i "password\|secret"

HTTPS Enforcement¶

GitHub Pages Configuration:

✅ Enforce HTTPS enabled
✅ HSTS enabled by default
✅ Let's Encrypt SSL certificates (auto-renewed)

Verification:

# Verify HTTPS redirect
curl -I http://salacoste.github.io/mcp-n8n-workflow-builder/
# Should return: Location: https://...

# Check security headers
curl -I https://salacoste.github.io/mcp-n8n-workflow-builder/
# Look for: Strict-Transport-Security header

Next Steps¶

Contributing Guide - How to contribute to documentation
Changelog - Documentation version history
GitHub Repository - Source code

Document Version: 1.0 Last Updated: January 2025 Deployment URL: https://salacoste.github.io/mcp-n8n-workflow-builder