documentation（文档）

Documentation Skill

This skill provides comprehensive guidelines for AI coding assistants working on Kubb documentation.

When to Use

• Adding a new plugin, feature, or option
• Changing plugin behavior or API signatures
• Fixing bugs that affect code generation
• Writing or updating functionalities/component/composable documentation
• Optimizing documentation for search engines

What It Does

• Create clear, concise, practical documentation optimized for developer experience
• Optimize content for search engines and developer intent
• Structure content for maximum scannability and engagement

Writing Standard

Override: When writing documentation, maintain proper grammar and complete sentences. The "sacrifice grammar for brevity" rule does NOT apply here.

Documentation must be:

• Grammatically correct
• Clear and unambiguous
• Properly punctuated
• Complete sentences (not fragments)

Brevity is still valued, but never at the cost of clarity or correctness.

Available References

Load based on context:

• Writing prose → ../documentation/references/writing-style.md
• Props, options, usage patterns → ../documentation/references/content-patterns.md
• Adding navigation or sections → ../documentation/references/config-json.md
• Optimizing for search → ../documentation/references/seo-optimization.md

Language and Tone

• Use the US spelling. For example, use license, not licence.

Naming Conventions

• Use kebab-case: how-to-do-thing.md
• Be descriptive: multipart-form-data.md not form.md
• Match URL structure: File name becomes the URL path

Writing Patterns

Modal Verbs

Component Patterns (WHEN to use)

Headings

• H1 (#): No backticks
• H2-H4: Backticks work fine

Links and Cross-References

• Internal links: Use relative paths: /plugins/plugin-ts/
• Anchor links: Link to specific sections: /plugins/plugin-ts/#output-path
• External links: Use full URLs with descriptive text
• Placement: Add links section at the very end of the document

Images and assets

• Location: docs/public/
• Reference: Use relative paths from markdown files
• Formats: Use optimized formats (webp/png/jpg)
• Sizing: Keep file sizes reasonable
• Naming: Use descriptive names: plugin-react-query-example.png

Configuration (config.json)

The docs/config.json file defines navigation and sidebar structure using the Kubb.dev schema.

• Schema: https://kubb.dev/schemas/config/schema.json
• Required: sidebars (array), sidebar (route mapping)
• Optional: nav (navigation), $schema (validation)
• Link format: Use absolute paths with trailing slash: /getting-started/introduction/
• Route mapping: /getting-started maps to gettingStarted sidebar name

When adding new sections:

1. Define sidebar in sidebars array with unique name
2. Add navigation items to nav array
3. Map route prefix to sidebar name in sidebar object

See ./references/config-json.md for complete schema reference.

Checklist

• Active voice (85%+)
• Present tense
• 2-3 sentences per paragraph
• Explanation before code
• Validate frontmatter syntax
• Update config.json when adding new pages/sections