documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation Skill

文档编写Skill

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

本Skill为负责编写Kubb文档的AI代码助手提供全面指南。

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

添加新插件、功能或选项时
修改插件行为或API签名时
修复影响代码生成的bug时
撰写或更新功能/组件/composable文档时
为搜索引擎优化文档时

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

可用参考文档

Reference	Purpose
../documentation/references/writing-style.md	Voice, tone, sentence structure
../documentation/references/content-patterns.md	Usage patterns, props structure, component patterns
../documentation/references/config-json.md	Navigation and sidebar configuration schema
../documentation/references/seo-optimization.md	SEO best practices, titles, descriptions, keywords, FAQs

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

参考文档	用途
../documentation/references/writing-style.md	语态、语气、句子结构规范
../documentation/references/content-patterns.md	使用模式、属性结构、组件格式规范
../documentation/references/config-json.md	导航与侧边栏配置 schema
../documentation/references/seo-optimization.md	SEO最佳实践、标题、描述、关键词、常见问题

根据上下文加载对应文档：

撰写散文类内容 → ../documentation/references/writing-style.md
属性、选项、使用模式相关 → ../documentation/references/content-patterns.md
添加导航或章节 → ../documentation/references/config-json.md
搜索引擎优化 → ../documentation/references/seo-optimization.md

Language and Tone

语言与语气

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

使用美式拼写，例如使用license而非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

使用kebab-case命名：
```
how-to-do-thing.md
```
名称需具有描述性：
```
multipart-form-data.md
```
而非
```
form.md
```
与URL结构匹配：文件名即为URL路径

Writing Patterns

写作句式

Pattern	Example
Subject-first	"The `useApp` composable handles Fabric related logic."
Imperative	"Add the following to `kubb.config.ts` ."
Contextual	"When relying on TypeScript, configure..."

句式类型	示例
主语前置	"The `useApp` composable handles Fabric related logic."
祈使句	"Add the following to `kubb.config.ts` ."
语境引导	"When relying on TypeScript, configure..."

Modal Verbs

情态动词使用规范

Verb	Meaning
`can`	Optional
`should`	Recommended
`must`	Required

动词	含义
`can`	可选操作
`should`	推荐操作
`must`	强制要求

Component Patterns (WHEN to use)

组件格式规范（适用场景）

Need	Component
Info aside	`> [!NOTE]`
Suggestion	`> [!TIP]`
Caution	`> [!WARNING]`
Required	`> [!IMPORTANT]`
Multi-source code	`::: code-group` and ends with `:::`

需求	组件格式
信息提示	`> [!NOTE]`
建议提示	`> [!TIP]`
警告提示	`> [!WARNING]`
强制要求提示	`> [!IMPORTANT]`
多源代码块	`::: code-group` 并以 `:::` 结尾

Headings

标题规范

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

H1（
#
）：标题中不使用反引号
H2-H4：标题中可使用反引号

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

内部链接：使用相对路径：
```
/plugins/plugin-ts/
```
锚点链接：链接到特定章节：
```
/plugins/plugin-ts/#output-path
```
外部链接：使用完整URL并搭配描述性文本
位置要求：在文档末尾添加链接章节

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
```

存储位置：
```
docs/public/
```
引用方式：使用相对于Markdown文件的路径
格式要求：使用优化后的格式（
```
webp
```
/
```
png
```
/
```
jpg
```
）
大小要求：控制文件大小在合理范围
命名要求：使用描述性名称：
```
plugin-react-query-example.png
```

Configuration (config.json)

配置文件（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:

Define sidebar in
```
sidebars
```
array with unique
```
name
```
Add navigation items to
```
nav
```
array
Map route prefix to sidebar name in
```
sidebar
```
object

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

docs/config.json

文件使用Kubb.dev schema定义导航与侧边栏结构。

Schema地址：

https://kubb.dev/schemas/config/schema.json

必填项：
```
sidebars
```
（数组）、
```
sidebar
```
（路由映射）
可选项：
```
nav
```
（导航栏）、
```
$schema
```
（校验）
链接格式：使用带末尾斜杠的绝对路径：
```
/getting-started/introduction/
```
路由映射：
```
/getting-started
```
对应
```
gettingStarted
```
侧边栏名称

添加新章节时：

在
```
sidebars
```
数组中定义带有唯一
```
name
```
的侧边栏
在
```
nav
```
数组中添加导航项
在
```
sidebar
```
对象中配置路由前缀与侧边栏名称的映射

完整schema参考请查看./references/config-json.md。