Documentation Update Check

If the changes are purely internal (refactoring, test-only, CI config, internal code reorganization with no behavioral change), skip the doc check.

How to Check

Step 1: Identify what changed

Look at the changes you just made (or use git diff if needed). Categorize them:

• What component was changed? (router, cli, controlplane, studio, composition, helm, etc.)
• What is the user-visible effect?
• Are there new configuration options, flags, or environment variables?
• Did any existing behavior change?

Step 2: Map changes to documentation sections

Use this mapping to find which docs might need updating:

Step 3: Read the relevant doc pages

Read the existing documentation pages that correspond to your changes. Check for:

1. Missing information — is the new feature/option/flag documented?
2. Outdated information — do existing descriptions still match the new behavior?
3. Code examples — do they still work with the changes?
4. Configuration examples — do they reflect new defaults or options?
5. Screenshots — if UI changed, do screenshots still match? (flag these — don't generate new ones)

Step 4: Check navigation

If a new documentation page is needed, it must be added to docs-website/docs.json in the appropriate navigation group. Read docs.json to verify the page is listed.

The navigation is organized into three tabs:

• Documentation — concepts, router, studio, control plane, federation, deployments
• CLI — all CLI commands organized by resource type
• Tutorials — step-by-step guides

Step 5: Report findings

Tell the user what you found. Be specific:

• Which doc pages need updating — list the file paths
• What needs to change — describe each update needed (new section, updated example, corrected default value, etc.)
• Whether new pages are needed — and where they should go in the navigation
• Whether screenshots are outdated — flag these for the user since you can't regenerate them

Then ask the user if they want you to make the documentation updates now.

Writing Documentation

When writing or updating docs, follow these conventions:

• Format: MDX with YAML frontmatter (title, description, optional icon and sidebarTitle)
• Callouts: Use <Info>, <Note>, <Warning> for important information
• Images: Place in docs-website/images/[topic]/, reference as /images/topic/filename.png
• Code blocks: Use language-specific syntax highlighting (yaml, graphql, ```bash, etc.)
• Internal links: Use relative paths like /router/configuration
• Style: Be direct and practical. Lead with what the user needs to do, then explain why.

Common Pitfalls

• Forgetting docs.json — new pages won't appear in the sidebar without a navigation entry
• Config reference drift — when adding router config options, the config reference page (router/configuration.mdx) must be updated along with any feature-specific page
• CLI flag docs — each CLI command page documents all available flags; new flags need to appear there
• Environment variable docs — these are often documented both in the config reference and in deployment guides