github-pages-sync（GitHub pages sync 开发）

GitHub Pages Sync

This skill ensures the public GitHub Pages site (site-docs/) stays synchronized with source code and internal documentation changes.

When This Skill Activates

Automatic Triggers

1. Code changes in core modules - synapse/*.py, synapse/commands/*.py
2. Profile changes - synapse/profiles/*.yaml
3. Plugin/Skill changes - plugins/**/*
4. Configuration changes - pyproject.toml (version, dependencies, entry points)
5. Internal doc changes - guides/*.md, docs/*.md, README.md
6. Site-docs changes - site-docs/** (direct edits to the published site)

Manual Invocation

• /github-pages-sync - Run full site-docs synchronization check

Workflow

Phase 1: Detect Changes

When code or internal docs are modified, identify affected site-docs pages by consulting references/source-site-mapping.md.

Quick Reference - Common Patterns:

Phase 2: Propose Updates

For each affected site-docs page:

1. Read the current page content
2. Identify the specific section to update
3. Propose the minimal necessary change
4. Present changes to user for approval

Update Principles:

• Maintain MkDocs Material formatting (admonitions, tabs, code annotations)
• Update only affected sections — do not rewrite entire pages
• Keep index.md concise; put details in guide/ or reference/ pages
• Preserve existing Mermaid diagrams unless the architecture changed
• Ensure nav structure in mkdocs.yml stays consistent

Phase 3: Apply Updates

After user approval:

1. Apply changes to affected site-docs/ pages
2. Update mkdocs.yml nav if new pages were added
3. Update changelog.md if the change is user-facing

Phase 4: Verify

Run build verification:

uv run mkdocs build --strict

Check for:

1. Build success - No warnings or errors in strict mode
2. Broken links - All internal cross-references resolve
3. Nav consistency - mkdocs.yml nav matches actual files in site-docs/

Page Categories

High Traffic (Update Promptly)

Core Guides

Deep Reference

Reference Files

For detailed page inventory and source-to-page mappings, consult:

• references/source-site-mapping.md - Source file to site-docs page relationships
• references/site-inventory.md - Complete list of all site-docs pages and their roles

Special Cases

Version Updates

When pyproject.toml version changes:

1. Update changelog.md with release notes
2. Check if index.md badges need updating

New Feature Addition

For major new features:

1. Add to index.md feature highlights
2. Create or update relevant page in guide/ or concepts/
3. Update reference/cli.md and/or reference/api.md
4. Add to mkdocs.yml nav if a new page was created
5. Update getting-started/quickstart.md if the feature affects onboarding

New CLI Command

1. Add to reference/cli.md with full syntax and examples
2. Update relevant guide/ page with usage context
3. Update getting-started/quickstart.md if commonly used

Deprecation

When deprecating features:

1. Mark as deprecated with admonition in relevant pages
2. Add migration guide if needed
3. Update changelog.md
4. Remove from getting-started/quickstart.md examples