Site Synchronization & Automation

Automated sync between docs site and public site

1 Overview

Our documentation and public sites stay synchronized through automated Git hooks and scheduled processes. This ensures consistency across all our digital properties while maintaining separate concerns.

1.1 Architecture

graph LR
    A[Docs Site] -->|Link Health| B[Public Site]
    B -->|Branding Assets| A
    A -->|Git Hooks| C[Auto Sync]
    C -->|Triggers| D[Background Jobs]
    D -->|Updates| A
    D -->|Updates| B

1.2 Sync Operations

1.2.1 🎨 Branding Sync (Public → Docs)

Frequency: Every 6 hours + Git hooks Purpose: Keep docs site branding consistent with public site

Syncs _brand.yml configuration
Copies brand assets (logos/, styles/)
Updates color palettes and typography
Maintains visual consistency

1.2.2 🔗 Link Health Monitoring (Docs → Public)

Frequency: Every hour Purpose: Monitor documentation link health and expose metrics

Scans all markdown files for links
Checks HTTP status codes and response times
Generates health reports and summaries
Creates public dashboard on main site

1.2.3 📊 Full Sync Process

Frequency: Every 4 hours Trigger: bash scripts/sync-all.sh

Branding Sync - Pull latest brand assets
Link Health Check - Scan all documentation links
Site Build - Render updated documentation
Deploy - Push to production (optional)

1.3 Git Hook Integration

1.3.1 Pre-commit Hook (Docs Site)

Runs before each commit to ensure consistency:

# Automatically triggered on: git commit
./.githooks/pre-commit

Operations: 1. Sync branding from public site 2. Refresh mirrored documents 3. Run link health check 4. Stage updated assets

1.3.2 Post-commit Hook (Docs Site)

Runs after successful commits:

# Automatically triggered after: git commit
./.githooks/post-commit

Operations: 1. Log commit information 2. Trigger async sync to public site 3. Maintain commit history

1.3.3 Post-receive Hook (Public Site)

Runs when public site receives updates:

# Automatically triggered on: git push (to public site)
./.githooks/post-receive

Operations: 1. Detect branding changes in commit messages 2. Trigger background sync to docs site 3. Log update history

1.4 Manual Operations

1.4.1 Individual Sync Scripts

# Sync branding only
cd /Users/srvo/ethicalcapital-docs
python3 scripts/sync-branding.py

# Run link health check only
python3 tools/link-health.py

# Sync link health to public site
cd /Users/srvo/ethicic-site
python3 scripts/sync-link-health.py

# Complete docs sync process
cd /Users/srvo/ethicalcapital-docs
bash scripts/sync-all.sh

# Complete public site sync
cd /Users/srvo/ethicic-site
BUILD=true bash scripts/sync-from-docs.sh

1.4.2 Scheduled Operations

# Run individual operations
python3 scripts/sync-schedule.py branding
python3 scripts/sync-schedule.py link-health
python3 scripts/sync-schedule.py full-sync

# Start automated scheduler
python3 scripts/sync-schedule.py schedule

1.5 Installation & Setup

1.5.1 Initial Setup

# Install Git hooks
cd /Users/srvo/ethicalcapital-docs
bash scripts/install-hooks.sh

# Verify installation
git config core.hooksPath
# Should output: .githooks

1.5.2 Dependencies

Python 3.x with packages: aiohttp, pyyaml, requests, schedule
Quarto for site building
Cloudflare Wrangler for deployment
Standard Unix tools (bash, git, etc.)

1.5.3 Environment Variables

# Optional build/deploy flags
export BUILD=true    # Build site after sync
export DEPLOY=true   # Deploy after build
export TMPDIR=/tmp/claude/  # Temp directory for logs

1.6 Monitoring & Status

1.6.1 Generated Reports

Report	Location	Purpose
Link Health Summary	`tools/link-health-reports/summary.json`	Overall health metrics
Detailed Link Report	`tools/link-health-reports/link-health.csv`	Per-link status details
Branding Status	`tools/branding-sync-status.json`	Asset sync verification
Commit History	`scripts/commit-history.json`	Git hook execution log

1.6.2 Public Dashboards

Link Health Status - Public health dashboard
Docs Tools Overview - Internal sync tools documentation

1.6.3 Status Checks

# Check hook installation
ls -la .githooks/
git config core.hooksPath

# View recent sync status
cat scripts/sync-status.json | jq '.[0:5]'

# Check link health summary
cat tools/link-health-reports/summary.json | jq '.health_score'

# Verify branding sync
cat tools/branding-sync-status.json | jq

1.7 Troubleshooting

1.7.1 Common Issues

Hooks not running

# Check configuration
git config core.hooksPath
# Should be: .githooks

# Re-install hooks
bash scripts/install-hooks.sh

Permission errors

# Make hooks executable
chmod +x .githooks/*

Sync failures

# Test individual components
python3 scripts/sync-branding.py
python3 tools/link-health.py

Background jobs stuck

# Check system logs
tail -f /tmp/claude/sync-schedule.log

# Kill stuck processes
pkill -f sync-

1.7.2 Log Locations

Scheduler logs: /tmp/claude/sync-schedule.log
Sync status: scripts/sync-status.json
Commit history: scripts/commit-history.json
Link health reports: tools/link-health-reports/

1.8 Security Considerations

All sync operations use local file paths or HTTPS
No API keys stored in sync scripts
Git hooks are version controlled and auditable
External requests are rate-limited and have timeouts
Sync failures are non-blocking for normal operations

Continuous Improvement

This sync system is designed to be self-maintaining. Link health monitoring helps identify issues before they impact users, and automated branding sync ensures consistent presentation across all properties.