# 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

```bash
# 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

```mermaid
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

```yaml
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

```bash
# 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

```bash
# 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

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

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

**Build Validation:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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

- [ ] Total site size <20MB
- [ ] Individual pages <500KB
- [ ] Images optimized (<200KB each)
- [ ] CSS/JS minified
- [ ] Load time <2 seconds

**Performance Checks:**

```bash
# 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

- [ ] WCAG 2.1 AA compliance
- [ ] Alt text on all images
- [ ] Proper heading hierarchy (H1 → H2 → H3)
- [ ] Keyboard navigation working
- [ ] Screen reader compatible

**Accessibility Testing:**

```bash
# 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:**

```bash
# 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

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

### Step 2: Verify Workflow Permissions

1. Navigate to **Settings → Actions → General**
2. **Workflow permissions:**
   - ✅ Read and write permissions
   - ✅ Allow GitHub Actions to create and approve pull requests
3. Click **Save**

### Step 3: First Deployment

```bash
# 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

```bash
# 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:**

```bash
# 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:**

1. **Add CNAME Record in DNS Provider:**
   ```
   Type: CNAME
   Name: docs
   Value: salacoste.github.io
   TTL: 3600 (1 hour)
   ```

2. **Create CNAME File:**

   **File:** `docs/CNAME`
   ```
   docs.yourproject.com
   ```

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

4. **Commit and Push:**
   ```bash
   git add docs/CNAME mkdocs.yml
   git commit -m "docs: configure custom domain"
   git push origin main
   ```

5. **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:**

```bash
# 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:**

```yaml
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**
```yaml
- 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:**
```yaml
- 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:**
```yaml
- 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:**
```yaml
- run: mkdocs build --strict
```

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

**5. Deploy to GitHub Pages:**
```yaml
- 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:**
```bash
# Run build locally to see warnings
mkdocs build --strict --verbose

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

**Solutions:**

1. **Fix broken links:**
   ```markdown
   # ❌ Wrong:
   [Link](non-existent-file.md)

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

2. **Remove missing nav entries:**
   ```yaml
   # mkdocs.yml
   nav:
     # - Missing Page: missing-file.md  # Remove or fix
     - Existing Page: existing-file.md
   ```

3. **Fix markdown syntax:**
   ```markdown
   # ❌ 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:**

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

2. **Verify gh-pages branch updated:**
   ```bash
   git fetch origin
   git log origin/gh-pages -1
   ```

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

**Solutions:**

1. **Clear browser cache:**
   - Hard reload: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
   - Incognito window

2. **Wait for CDN propagation:**
   - GitHub Pages CDN may take 1-5 minutes to update
   - Check again after 10 minutes

3. **Verify deployment commit:**
   ```bash
   # Check gh-pages branch
   git checkout gh-pages
   git log -1
   ls -la
   ```

### Permission Denied Errors

**Symptoms:**
```
Error: Resource not accessible by integration
```

**Solutions:**

1. **Enable workflow permissions:**
   - Settings → Actions → General
   - Workflow permissions → Read and write permissions
   - Save

2. **Check GITHUB_TOKEN permissions:**
   ```yaml
   permissions:
     contents: write
     pages: write
     id-token: write
   ```

### Custom Domain Not Working

**Symptoms:** Custom domain shows 404 or doesn't resolve

**Solutions:**

1. **Verify DNS propagation:**
   ```bash
   dig docs.yourproject.com
   # Should show CNAME to salacoste.github.io
   ```

2. **Check CNAME file:**
   ```bash
   cat docs/CNAME
   # Should contain: docs.yourproject.com
   ```

3. **Verify GitHub Pages settings:**
   - Settings → Pages → Custom domain
   - Green checkmark next to domain
   - HTTPS enforcement enabled (after SSL provision)

4. **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:**

```bash
# 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:**

```bash
# List outdated Python packages
pip list --outdated

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

**Update Dependencies:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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

```bash
# 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

```bash
# 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:**

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

# Serve and visually inspect
mkdocs serve

# Test critical workflows
```

**2. Use Pull Requests:**

```bash
# 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:**

```bash
# 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:**

```bash
# ✅ 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:**

```bash
# ✅ 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:

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

### 2. Code Block Optimization

```markdown
# ✅ 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):**

```markdown
<!-- 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:**

```bash
# 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:**

```bash
# 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](../about/contributing.md)** - How to contribute to documentation
- **[Changelog](../about/changelog.md)** - Documentation version history
- **[GitHub Repository](https://github.com/salacoste/mcp-n8n-workflow-builder)** - Source code

---

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