Docs and Website Editing

This skill covers creating and editing documentation for the Invowk Docusaurus website. For reviewing documentation accuracy against the codebase, use the /review-docs skill instead.

Before You Edit

Read website/WEBSITE_DOCS.md before any website edits.
Check .agents/skills/review-docs/references/consolidated-sync-map.md for code → docs mappings (the canonical change-oriented map covering both website docs and diagrams).
For documentation audit ownership, use .agents/skills/review-docs/references/doc-ownership.json; every current MDX page must retain exactly one semantic checklist owner with resolvable sources of truth.

Syncing Docs After Code Changes

When code changes require documentation updates:

Identify affected docs: Cross-reference the consolidated sync map (code → website docs + diagrams)
Read the code change: Understand what behavior changed
Update English docs first: Modify the relevant .mdx pages in website/docs/
Update snippets: If code examples changed, update Snippet/data/*.ts. Old entries superseded by new IDs can be removed — versioned docs use immutable snapshots.
Update i18n: Mirror changes to website/i18n/pt-BR/docusaurus-plugin-content-docs/current/
Update diagrams: If architecture changed, use the Diagram Editing workflow below
Verify parity: (cd website && npm run docs:parity)
Verify versioned assets: (cd website && node ../scripts/validate-version-assets.mjs)
Verify build: (cd website && npm run build)

Snippet System

All code blocks use the <Snippet> component — never inline fenced code blocks for reusable content.

Define snippets in website/src/components/Snippet/data/*.ts (12 section files)
Reference by ID: <Snippet id="section/name" />
Reuse identical snippet IDs across EN and pt-BR translations
Escape ${...} as \${...} inside snippets
When adding CUE snippets with implementation blocks, always include platforms: — see .agents/skills/review-docs/references/cue-drift-patterns.md for correct values per runtime

New Page Checklist

Create .mdx file in website/docs/<section>/
Create pt-BR translation at website/i18n/pt-BR/docusaurus-plugin-content-docs/current/<section>/
Add to website/sidebars.ts — sidebar_position only controls ordering, NOT inclusion
Add <Snippet> entries to Snippet/data/*.ts if code examples are needed
Run cd website && npm run docs:parity to verify parity

i18n Checklist

Use .mdx extension (not .md) in website/docs/ and translations
Treat website/docs/ as the upcoming version; only touch versioned docs for backport fixes
Update English first, then mirror to website/i18n/pt-BR/docusaurus-plugin-content-docs/current/
When backporting, also update the corresponding versioned pt-BR path (for example, website/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.0/)
Keep translations prose-only — reuse identical snippet IDs
Regenerate translation JSON when UI strings change: cd website && npx docusaurus write-translations --locale pt-BR

Style Guide

Friendly, approachable tone with occasional humor
Progressive disclosure: start simple, add complexity gradually
Practical examples for each feature
Use admonitions (:::info, :::warning, :::danger) for callouts

Documentation Testing

cd website && npm start                    # English dev server
cd website && npm start -- --locale pt-BR  # pt-BR dev server
cd website && npm run docs:parity          # Enforce EN ↔ pt-BR parity
cd website && node ../scripts/validate-version-assets.mjs
cd website && npm run build                # Full build (all locales, catches broken links)
cd website && npm run serve                # Test language switcher

Version-Scoped Asset Snapshots

Versioned docs resolve snippets and diagrams from immutable per-version snapshots. Updates to Snippet/data/*.ts or live SVGs never affect versioned docs.

Snippet/Diagram Migration (schema changes that rename IDs)

Create new snippet ID in Snippet/data/*.ts
Update current + i18n docs to reference the new ID
Remove old ID from data file — versioned docs resolve from immutable snapshots
Never touch versioned docs for ID renames

Backport Fixes

Edit the versioned MDX to add the new reference
Edit the matching versioned pt-BR MDX path when the backport affects translated docs
Run node scripts/snapshot-version-assets.mjs <version> --update

Generated Files (do not edit manually)

website/src/components/Snippet/versions/   # Per-version snippet snapshots + barrel
website/src/components/Diagram/versions/   # Per-version diagram path maps + barrel
website/static/diagrams/v{VERSION}/        # Per-version SVG copies

Versioning Pitfalls

Chicken-and-egg: docusaurus.config.ts lastVersion must reference a version already in versions.json. Fix: temporarily use an existing version, run version-docs.sh, which validates parity in step 5 and updates/restores lastVersion in step 6.
Doc-then-version: Fix docs in website/docs/ BEFORE running version-docs.sh — the script snapshots current state into versioned_docs/.
New diagrams break old validation: Adding SVGs to Diagram/index.tsx triggers failures for old version snapshots. Fix: node scripts/snapshot-version-assets.mjs <old-version> --update per affected version.
Retroactive versioning: version-docs.sh handles out-of-order safely (sorts versions.json by semver, uses semver comparison for lastVersion).

Diagram Editing

Edit .d2 source → d2 fmt → d2 validate → make render-diagrams → commit both source and SVG. For D2 syntax, readability rules, and update triggers, use the /d2-diagrams skill.

Important Rules

All invowk internal * commands are hidden — do NOT document in website docs
Container examples use debian:stable-slim by default. Language-specific slim images such as python:3-slim or node:22-slim are allowed only for language-specific runtime demonstrations. Never use Alpine or Windows container images.

docs

SKILL.md.claude/skills/docs