authoring-documentation

Documentation (*.md)

You MUST review @projects/site/src/docs/internal/guidelines/documentation.md before making any documentation changes.

When to Use This Skill

• Creating or updating markdown documentation files
• Working with 11ty templates in the documentation site
• Using or creating Eleventy shortcodes
• Writing API documentation or component guides
• Updating internal guidelines or developer documentation
• Fixing Vale prose-linting errors in markdown or JSDoc

Key Principles

1. Frontmatter Required: All documentation files must include proper frontmatter with title and layout
2. Eleventy Shortcodes: Use built-in shortcodes for common patterns (code examples, callouts, etc.)
3. Clear Structure: Use proper heading hierarchy and table of contents for long documents
4. Code Examples: Include working code examples with proper syntax highlighting
5. Cross-References: Link to related documentation and guidelines using proper paths

Prose Linting (Vale)

How Vale Runs

• Pre-commit (via lint-staged): automatically lints staged non-test *.ts and *.md files
• CI:runs as part of pnpm run ci
• Manual:pnpm run lint:vale from the repo root (pass specific files as args to narrow scope)

Rule Sets by File Type

• *.md:Vale, Google, write-good, Elements (full rule set)
• *.ts:Vale, write-good, Elements (no Google rules or spelling checks to reduce noise on code identifiers)
• *.examples.ts:same as *.ts plus three summary rules: SummaryStyle, SummaryActionable, SummaryGerund

Common Errors and Fixes

Suppressing Rules

Use sparingly, and re-enable immediately after the affected content:

<!-- vale Google.Quotes = NO -->
content here
<!-- vale Google.Quotes = YES -->

Key Files

• .vale.ini:root config (rule toggles, file-type scopes, token ignores)
• config/vale/styles/Elements/:custom rules (Branding, Terminology, Summary*)
• config/vale/styles/config/vocabularies/Elements/accept.txt:approved vocabulary

References

• Documentation Guidelines
• Examples Guidelines
• Vale Config
• Custom Vale Rules