Back to Details

write-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Write Docs

编写文档

Create clear, consistent documentation for the Inkeep docs site following established patterns and structure.
遵循既定的格式和结构，为Inkeep文档站点创建清晰、一致的文档。

Use when

适用场景

  • Any customer-facing feature, API, SDK, CLI, UI, config, or behavior change needs documenting
  • Creating or updating pages in 
    agents-docs/content/
    , snippets, or public-facing READMEs or reference artifacts (like .env.example files)
  • Restructuring or reorganizing docs (moves, renames, redirects)
  • 任何面向客户的功能、API、SDK、CLI、UI、配置或行为变更需要文档支持时
  • 创建或更新
    agents-docs/content/
    下的页面、代码片段，或面向公众的README文件、参考制品（如.env.example文件）时
  • 重构或重新组织文档（移动、重命名、设置重定向）时

Do NOT use when

不适用场景

  • Writing code comments or inline documentation (not MDX docs)
  • Working on internal-only changes with no customer-facing surface area
  • Updating internal tooling docs (e.g. 
    AGENTS.md
    , 
    .agents/skills/
    , 
    .agents/rules/
    , 
    CONTRIBUTING.md
    , 
    .github/workflows/
    )
  • 编写代码注释或内联文档（非MDX格式的文档）时
  • 处理仅内部变更、无客户接触面的内容时
  • 更新内部工具文档（如
    AGENTS.md
    、
    .agents/skills/
    、
    .agents/rules/
    、
    CONTRIBUTING.md
    、
    .github/workflows/
    ）时

Philosophy

文档理念

Every feature must be documented fully across all surfaces: how it's used, interacted with, depended on, or perceived by end-users. Documentation is the audited source of truth for the product.
  • Every Surface Area Needs Documentation: Anything that an engineering change touches that involves a customer-facing change in any product surface area[s] need to be documented.
  • Keep docs current: Documentation is a living artifact. When code changes, existing docs must be updated in the same change. Stale docs are misleading docs.
  • Accuracy over speed: Incorrect documentation erodes trust faster than missing documentation. Cross-reference source code to verify that types, parameter names, and described behavior match the actual implementation.
  • Consistency: Use the same terminology, structure, and formatting patterns across all docs. If we call it a "project" in one place, don't call it a "workspace" in another.
  • For the right audience: Tailor voice, depth, and framing to who will read the page. A developer integrating an SDK needs different context than an admin configuring a project.
  • Good information architecture: The right audiences find the right content.
  • Clarity over assumption: Don't assume prior knowledge. Be explicit about prerequisites and context.
  • Direct and practical: Get to the point. Documentation exists to help users accomplish goals, not to showcase everything we know.
  • Progressive disclosure: Build up concepts before diving into details.
  • Scoped and targeted: Each doc has a clear outcome. Provide the context needed—nothing more, nothing less.
  • Right detail, right place: Avoid duplication. If something is explained elsewhere, link to it or reuse it in some way as appropriate.
每个功能都必须在所有层面完整文档化：包括使用方式、交互方式、依赖关系，以及终端用户的感知方式。文档是产品的权威可信来源。
  • 所有接触面都需要文档：工程变更涉及的任何客户可见产品接触面，都必须编写文档。
  • 保持文档时效性：文档是动态更新的产物。代码变更时，现有文档必须同步更新。过时的文档会误导用户。
  • 准确性优先于速度：错误的文档比缺失的文档更能损害用户信任。需交叉参考源代码，确保类型、参数名称和描述的行为与实际实现一致。
  • 一致性：所有文档使用统一的术语、结构和格式。如果在某处称其为“项目”，就不要在另一处称其为“工作区”。
  • 面向目标受众：根据读者群体调整语气、深度和框架。集成SDK的开发者与配置项目的管理员需要不同的上下文信息。
  • 良好的信息架构：让目标受众能轻松找到所需内容。
  • 清晰而非假设：不要假设读者具备前置知识。明确说明前提条件和上下文。
  • 直接实用：直奔主题。文档的存在是为了帮助用户完成目标，而非展示所有知识。
  • 渐进式披露：先构建概念，再深入细节。
  • 聚焦目标：每个文档都有明确的成果。提供必要的上下文——不多不少。
  • 合理布局细节：避免重复。如果内容已在别处说明，可链接到该内容或适当复用。

Workflow

工作流程

  1. Understand context - Fully map out the scope of what needs to be changed. Consider all procuct surface areas plausibly affected, and identify existing documentation or documentation sections that may need updating or new articles.
  2. Identify documentation type — Determine if this is reference, tutorial, integration, or overview content (see Step 1)
  3. Write frontmatter — Add required 
    title
    and optional fields like 
    sidebarTitle
    , 
    description
    , 
    keywords
    (see Step 2)
  4. Structure content — Use the appropriate pattern template for your doc type (see Step 3)
  5. Use components correctly — Apply 
    <Steps>
    , 
    <Tabs>
    , 
    <Cards>
    , callouts as needed (see Step 4)
  6. Write code examples — Ensure examples are runnable with language tags and realistic values (see Step 5)
  7. Handle navigation — Update 
    meta.json
    if needed; add redirects for moves/renames (see File Organization)
  8. Verify — Check against the verification checklist before completing
  1. 理解上下文 - 全面梳理需要变更的范围。考虑所有可能受影响的产品接触面，确定可能需要更新的现有文档或文档章节，或需要创建的新文档。
  2. 确定文档类型 — 判断文档属于参考型、教程型、集成型还是概述型（见步骤1）
  3. 编写前置元数据 — 添加必填的
    title
    字段，以及可选字段如
    sidebarTitle
    、
    description
    、
    keywords
    （见步骤2）
  4. 构建内容结构 — 根据文档类型使用合适的模板（见步骤3）
  5. 正确使用组件 — 按需使用
    <Steps>
    、
    <Tabs>
    、
    <Cards>
    、提示框等组件（见步骤4）
  6. 编写代码示例 — 确保示例可运行，添加语言标签并使用真实合理的取值（见步骤5）
  7. 处理导航 — 必要时更新
    meta.json
    ；为移动/重命名的页面添加重定向（见文件组织）
  8. 验证 — 完成前对照验证清单检查

Step 0: Identify Relevant Surface Areas

步骤0：识别相关接触面

Before writing anything, map out which surface areas the change touches. Review the engineering or product changes (staged files, PR diff, or task description) and ask:
  1. What changed? — Identify the modified packages, APIs, schemas, or UI components
  2. Who is affected? — Determine which user-facing surfaces consume or expose this change. For example (not exhaustive!):
    • SDK/CLI users (types, builder APIs, commands)
    • Dashboard users (UI forms, views, workflows)
    • API consumers (endpoints, request/response shapes, streaming formats)
    • Widget/chat users (runtime behavior, rendering)
    • Self-hosting users (env vars, deployment config)
  3. What docs already exist? — Search 
    agents-docs/content/
    for pages that reference the affected feature; these may need updates
  4. What's new vs. changed? — New surface areas need new pages; changed behavior needs existing page updates
If a change touches multiple surface areas, create or update a doc for each. Don't bundle unrelated surfaces into one page unless it's a natural fit with the existing document or similar analogous docs.
在开始编写前，梳理变更涉及的所有接触面。查看工程或产品变更内容（暂存文件、PR差异或任务描述），并思考：
  1. 变更了什么？ — 确定修改的包、API、架构或UI组件
  2. 谁会受影响？ — 确定哪些用户接触面会使用或展示此变更。例如（非 exhaustive 列表）：
    • SDK/CLI用户（类型、构建器API、命令）
    • 控制台用户（UI表单、视图、工作流）
    • API消费者（端点、请求/响应格式、流格式）
    • 小部件/聊天用户（运行时行为、渲染效果）
    • 自托管用户（环境变量、部署配置）
  3. 已有哪些文档？ — 在
    agents-docs/content/
    中搜索提及受影响功能的页面；这些页面可能需要更新
  4. 哪些是新增内容，哪些是变更内容？ — 新增接触面需要新页面；变更的行为需要更新现有页面
如果变更涉及多个接触面，应为每个接触面创建或更新文档。除非与现有文档自然契合，否则不要将不相关的接触面内容合并到一个页面。

Step 1: Identify Documentation Type

步骤1：确定文档类型

PatternWhen to useFocusTitle style
OverviewConceptual explanation ("what is X?")Mental models, "why", terminology, key definitions, relationshipsNoun
ReferenceNew SDK feature, API, or configuration optionsExhaustive, scannable, precise specsNoun
TutorialStep-by-step instructions to accomplish somethingGoal-oriented, sequential, minimal tangentsVerb
IntegrationConnecting a third-party serviceInstallation-focused, platform-awareVerb
模式适用场景核心重点标题风格
概述型概念性解释（“什么是X？”）思维模型、“为什么”、术语、关键定义、关联关系名词
参考型新SDK功能、API或配置选项全面、易扫描、精确的规范名词
教程型分步指导完成某项任务目标导向、按顺序、尽量减少无关内容动词
集成型连接第三方服务以安装为重点、适配平台动词

Step 2: Write Frontmatter

步骤2：编写前置元数据

Every 
.mdx
file must have frontmatter with at least a 
title
.
每个
.mdx
文件必须包含至少带有
title
字段的前置元数据。

Required

必填字段

yaml
---
title: Full Descriptive Title with Context
---
yaml
---
title: 包含上下文的完整描述性标题
---

Optional (add when relevant)

可选字段（相关时添加）

yaml
---
title: Add Chat Button to Next.js
sidebarTitle: Chat Button
description: Integrate Inkeep's chat button into your Next.js application.
icon: LuMessageSquare
keywords: Next.js integration, chat button, React
---
yaml
---
title: 在Next.js中添加聊天按钮
sidebarTitle: 聊天按钮
description: 将Inkeep的聊天按钮集成到你的Next.js应用中。
icon: LuMessageSquare
keywords: Next.js集成, 聊天按钮, React
---

When to add each field

各字段添加时机

FieldAdd when
sidebarTitle
Title is long/sentence-like, or breadcrumb provides context so sidebar can be short
description
Page is important for SEO or is a top-level entry point
keywords
Page targets common search intents ("authentication", "vercel", "docker")
icon
Landing/overview page or frequently linked in cards
字段添加时机
sidebarTitle
标题过长/为句子形式，或面包屑已提供上下文，侧边栏可使用短标题时
description
页面对SEO很重要，或为顶级入口页面时
keywords
页面针对常见搜索意图（如“authentication”、“vercel”、“docker”）时
icon
首页/概述页面，或频繁在卡片中链接的页面时

Title rules

标题规则

  • Sentence case: capitalize first word + proper nouns (e.g., "Deploy to Vercel")
  • Use breadcrumb context—don't repeat the section name in the title
  • Include the action for how-to content: "Configure authentication" not "Authentication"
  • Use verbs/phrases for task pages; nouns for references/concepts
  • 句子大小写：仅首字母和专有名词大写（例如“Deploy to Vercel”）
  • 利用面包屑上下文——不要在标题中重复章节名称
  • 操作类内容包含动作：使用“Configure authentication”而非“Authentication”
  • 任务类页面使用动词/短语；参考/概念类页面使用名词

SidebarTitle rules

侧边栏标题规则

  • 1-3 words when possible
  • Leverage parent context (don't repeat parent name)
  • Action words for how-to content: "Install", "Configure", "Setup"
  • 尽可能控制在1-3个单词
  • 利用父级上下文（不要重复父级名称）
  • 操作类内容使用动作词：“Install”、“Configure”、“Setup”

Examples

示例

✅ Good: descriptive title + short sidebarTitle
yaml
---
title: Live Debugger, Traces, and OTEL Telemetry
sidebarTitle: Traces
---
❌ Avoid: redundant title repeating breadcrumb
yaml
---
✅ 推荐：描述性标题 + 简短侧边栏标题
yaml
---
title: 实时调试器、追踪和OTEL遥测
sidebarTitle: 追踪
---
❌ 避免：标题重复面包屑内容
yaml
---

Breadcrumb already includes "TypeScript SDK"

面包屑已包含“TypeScript SDK”

title: TypeScript SDK Model Configuration


❌ **Avoid: sidebarTitle repeating parent context**
```yaml

title: TypeScript SDK模型配置


❌ **避免：侧边栏标题重复父级上下文**
```yaml

Parent folder: "Slack Integration"

父文件夹：“Slack Integration”

title: Set up Inkeep in Slack sidebarTitle: Set up Inkeep in Slack # BAD

✅ **Good: context-aware sidebarTitle**
```yaml
title: 在Slack中设置Inkeep sidebarTitle: 在Slack中设置Inkeep # 不推荐

✅ **推荐：上下文感知的侧边栏标题**
```yaml

Parent folder: "Slack Integration"

父文件夹：“Slack Integration”

title: Set up Inkeep in Slack sidebarTitle: Installation # Parent provides context

---
title: 在Slack中设置Inkeep sidebarTitle: 安装 # 父级已提供上下文

---

Step 3: Structure Content

步骤3：构建内容结构

These templates are examples. Mix and match as appropriate for your use case.
以下模板为示例。可根据实际需求混合搭配使用。

Reference Pattern (APIs, SDKs, Configuration)

参考型模式（API、SDK、配置）

markdown
undefined
markdown
undefined

Feature Name

功能名称

Brief one-sentence description of what this feature does.
一句话简要描述该功能的作用。

Quick Start (recommended)

快速开始（推荐）

Minimal working example (< 10 lines).
最简可运行示例（少于10行代码）。

Parameters / Options (recommended)

参数/选项（推荐）

ParameterTypeRequiredDescription
apiKey
stringYesYour API key
参数类型必填描述
apiKey
string是你的API密钥

Examples

示例

Basic Usage

基础用法

[code example]
[代码示例]

Advanced Usage

高级用法

[code example with options]
[带选项的代码示例]

Related

相关链接

  • [Link to related feature]
undefined
  • [相关功能链接]
undefined

Tutorial Pattern (How-to Guides)

教程型模式（操作指南）

markdown
undefined
markdown
undefined

How to [Accomplish Task]

如何[完成任务]

Brief description of what you'll build/achieve.
简要描述你将构建或实现的内容。

Prerequisites

前提条件

  • Requirement 1
  • Requirement 2
  • 要求1
  • 要求2

Steps

步骤

<Steps> <Step> ### Step Title 
Explanation and code.
</Step> <Step> ### Next Step 
More explanation.
</Step> </Steps>
<Steps> <Step> ### 步骤标题 
说明和代码。
</Step> <Step> ### 下一步 
更多说明。
</Step> </Steps>

What's Next

后续操作

  • [Link to next tutorial]
  • [Link to reference docs]
undefined
  • [下一个教程链接]
  • [参考文档链接]
undefined

Integration Pattern (Third-party Services)

集成型模式（第三方服务）

markdown
undefined
markdown
undefined

[Service Name] Integration

[服务名称]集成

Brief description of what this integration enables.
简要描述该集成的功能。

Prerequisites

前提条件

  • Service account
  • API key from service
  • 服务账户
  • 服务提供的API密钥

Installation

安装

<Steps> <Step> Install the package ```bash pnpm add @inkeep/[package] ``` </Step> <Step> Configure credentials [code] </Step> </Steps>
<Steps> <Step> 安装包 ```bash pnpm add @inkeep/[package] ``` </Step> <Step> 配置凭证 [代码] </Step> </Steps>

Configuration Options

配置选项

OptionDescriptionDefault
option1
What it does
value
选项描述默认值
option1
功能说明
value

Platform-Specific Notes

平台特定说明

<Tabs> <Tab title="Next.js"> [Next.js specific instructions] </Tab> <Tab title="Node.js"> [Node.js specific instructions] </Tab> </Tabs> ```
<Tabs> <Tab title="Next.js"> [Next.js特定说明] </Tab> <Tab title="Node.js"> [Node.js特定说明] </Tab> </Tabs> ```

Overview Pattern (Conceptual Docs)

概述型模式（概念文档）

markdown
undefined
markdown
undefined

[Concept Name]

[概念名称]

Opening paragraph explaining what this is and why it matters.
开篇段落解释该概念是什么，以及其重要性。

Key Features

核心功能

  • Feature 1: Brief explanation
  • Feature 2: Brief explanation
  • 功能1：简要说明
  • 功能2：简要说明

How It Works

工作原理

Conceptual explanation, optionally with diagram.
概念性解释，可选择性添加图表。

Use Cases

使用场景

When to use this:
  • Use case 1
  • Use case 2
适用场景：
  • 使用场景1
  • 使用场景2

Getting Started

快速入门

<Cards> <Card title="Quick Start" href="/path/to/quickstart"> Get up and running in 5 minutes </Card> <Card title="API Reference" href="/path/to/reference"> Detailed API documentation </Card> </Cards> ```
<Cards> <Card title="快速开始" href="/path/to/quickstart"> 5分钟内快速上手 </Card> <Card title="API参考" href="/path/to/reference"> 详细的API文档 </Card> </Cards> ```

Step 4: Use Components Correctly

步骤4：正确使用组件

Component Selection

组件选择指南

What are you presenting?
│
├─ Multiple code variants (languages, frameworks)?
│  └─ Use <Tabs>
│
├─ Sequential instructions?
│  └─ Use <Steps>
│
├─ Navigation to other docs?
│  └─ Use <Cards>
│
├─ Content that's helpful but not essential?
│  └─ Use <Accordions>
│
├─ Important callout?
│  ├─ Helpful tip → <Tip>
│  ├─ Important note → <Note>
│  └─ Critical warning → <Warning>
│
└─ Regular content
   └─ Use plain markdown
你要展示什么内容？
│
├─ 多版本代码（不同语言、框架）？
│  └─ 使用<Tabs>
│
├─ 分步说明？
│  └─ 使用<Steps>
│
├─ 跳转到其他文档的导航？
│  └─ 使用<Cards>
│
├─ 有用但非必需的内容？
│  └─ 使用<Accordions>
│
├─ 重要提示？
│  ├─ 实用技巧 → <Tip>
│  ├─ 重要说明 → <Note>
│  └─ 关键警告 → <Warning>
│
└─ 常规内容
   └─ 使用纯Markdown

Component Syntax Reference

组件语法参考

Tabs (multi-language/multi-framework):
mdx
<Tabs>
  <Tab title="TypeScript">

```typescript
const config = { apiKey: 'key' };
```

  </Tab>
  <Tab title="JavaScript">

```javascript
const config = { apiKey: 'key' };
```

  </Tab>
</Tabs>
Steps (sequential instructions):
mdx
<Steps>
  <Step>
    First step with explanation
  </Step>
  <Step>
    Second step
  </Step>
</Steps>
Cards (navigation):
mdx
<Cards>
  <Card title="Feature Name" icon="IconName" href="/path">
    Brief description
  </Card>
</Cards>
Callouts (important information):
mdx
<Tip>Helpful best practice</Tip>
<Note>Important information</Note>
<Warning>Critical warning - user might break something</Warning>
Accordions (collapsible detail):
mdx
<Accordions>
  <Accordion title="Advanced Options">
    Detailed content here
  </Accordion>
</Accordions>
Tabs（多语言/多框架）：
mdx
<Tabs>
  <Tab title="TypeScript">

```typescript
const config = { apiKey: 'key' };
```

  </Tab>
  <Tab title="JavaScript">

```javascript
const config = { apiKey: 'key' };
```

  </Tab>
</Tabs>
Steps（分步说明）：
mdx
<Steps>
  <Step>
    第一步说明
  </Step>
  <Step>
    第二步说明
  </Step>
</Steps>
Cards（导航）：
mdx
<Cards>
  <Card title="功能名称" icon="IconName" href="/path">
    简要描述
  </Card>
</Cards>
提示框（重要信息）：
mdx
<Tip>实用最佳实践</Tip>
<Note>重要信息</Note>
<Warning>关键警告 - 用户可能会损坏某些内容</Warning>
折叠面板（可展开的详细内容）：
mdx
<Accordions>
  <Accordion title="高级选项">
    详细内容
  </Accordion>
</Accordions>

Additional Global Components

其他全局组件

These are registered for all docs pages (no 
import
needed):
ComponentUse for
<Image src="..." alt="..." />
Consistent image styling (full-width + rounded)
<Video src="..." title="..." />
YouTube or video embeds
<BigVideo src="..." />
Large MP4 player for 
/public/videos/
assets
<CodeGroup>
Tabbed code variants (use 
title="..."
on fences)
<Snippet file="..." />
Reusable content from 
_snippets/
<AutoTypeTable path="..." name="..." />
TypeScript reference tables that stay in sync
<SkillRule id="..." skills="..." title="...">
Mark sections extractable as agent skills
<ComparisonTable competitor="..." sectionTitle="..." />
Competitor comparison tables
以下组件已在所有文档页面注册（无需
import
）：
组件适用场景
<Image src="..." alt="..." />
统一的图片样式（全屏+圆角）
<Video src="..." title="..." />
YouTube或视频嵌入
<BigVideo src="..." />
用于
/public/videos/
资源的大型MP4播放器
<CodeGroup>
标签页式代码变体（在代码块中使用
title="..."
）
<Snippet file="..." />
复用
_snippets/
中的内容
<AutoTypeTable path="..." name="..." />
与代码同步更新的TypeScript参考表格
<SkillRule id="..." skills="..." title="...">
标记可提取为Agent技能的章节
<ComparisonTable competitor="..." sectionTitle="..." />
竞品对比表格

Step 5: Write Code Examples

步骤5：编写代码示例

Rules

规则

  1. Always specify language: 
    ```typescript
    not 
    ```
  2. Make it runnable: Users will copy-paste. Test your examples.
  3. Include comments for non-obvious parts: But don't over-comment
  4. Show realistic values: 
    apiKey: 'YOUR_API_KEY'
    not 
    apiKey: 'xxx'
  1. 始终指定语言：使用
    ```typescript
    而非
    ```
  2. 确保可运行：用户会直接复制粘贴代码。请测试你的示例。
  3. 为非明显部分添加注释：但不要过度注释
  4. 使用真实合理的取值：使用
    apiKey: 'YOUR_API_KEY'
    而非
    apiKey: 'xxx'

Language Tags

语言标签

Content TypeTag
TypeScript
typescript
JavaScript
javascript
Shell commands
bash
.env content
dotenv
Configuration
yaml
or 
json
MDX examples
mdx
内容类型标签
TypeScript
typescript
JavaScript
javascript
Shell命令
bash
.env内容
dotenv
配置文件
yaml
或
json
MDX示例
mdx

Code fence titles

代码块标题

Use 
title="..."
when the filename or location matters:
ts
export default defineConfig({ /* ... */ });
Common titles: 
inkeep.config.ts
, 
.env
, 
sandbox.ts
, 
index.ts
, 
package.json
当文件名或路径重要时，使用
title="..."
：
ts
export default defineConfig({ /* ... */ });
常见标题：
inkeep.config.ts
、
.env
、
sandbox.ts
、
index.ts
、
package.json

Example quality

示例质量

❌ Bad:
javascript
// This sets up the config
const c = {k: 'x'}; // key
doThing(c); // do it
✅ Good:
typescript
const config = {
  apiKey: 'YOUR_API_KEY',
  organizationDisplayName: 'Acme Inc',
};

const client = createClient(config);
❌ 不推荐：
javascript
// 配置设置
const c = {k: 'x'}; // 密钥
doThing(c); // 执行操作
✅ 推荐：
typescript
const config = {
  apiKey: 'YOUR_API_KEY',
  organizationDisplayName: 'Acme Inc',
};

const client = createClient(config);

Mermaid diagrams

Mermaid图表

Use 
```mermaid
for flows that are clearer as visuals than prose:
mermaid
graph LR
    A[CLI flags] --> B[Environment variables]
    B --> C[Config file values]
    C --> D[Built-in defaults]
Keep diagrams simple (5-10 nodes max).
对于用可视化比文字更清晰的流程，使用
```mermaid
：
mermaid
graph LR
    A[CLI参数] --> B[环境变量]
    B --> C[配置文件值]
    C --> D[内置默认值]
保持图表简洁（最多5-10个节点）。

Step 6: Tables and Structured Data

步骤6：表格和结构化数据

Parameter Tables

参数表格

Always use this format for API parameters or configuration options:
markdown
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `apiKey` | string | Yes | Your Inkeep API key |
| `baseURL` | string | No | Custom API endpoint. Default: `https://api.inkeep.com` |
API参数或配置选项请始终使用以下格式：
markdown
| 参数 | 类型 | 必填 | 描述 |
|-----------|------|----------|-------------|
| `apiKey` | string | 是 | 你的Inkeep API密钥 |
| `baseURL` | string | 否 | 自定义API端点。默认值：`https://api.inkeep.com` |

When to Use Tables vs Lists

表格与列表的选择

  • Tables: Data comparing multiple items with shared attributes (type/required/default)
  • Lists: Narrative or irregular items
  • 表格：用于比较具有共同属性（类型/必填/默认值）的多个项
  • 列表：用于叙述性内容或不规则项

Step 7: Links and Navigation

步骤7：链接与导航

Internal Links

内部链接

Use relative paths, omit 
.mdx
:
markdown
See [Project Management](/typescript-sdk/project-management)
使用相对路径，省略
.mdx
后缀：
markdown
查看[项目管理](/typescript-sdk/project-management)

External Links

外部链接

Descriptive text, never "click here":
markdown
Check our [cookbook templates](https://github.com/inkeep/agents/tree/main/agents-cookbook/template-projects)
使用描述性文本，不要使用“点击这里”：
markdown
查看我们的[模板项目食谱](https://github.com/inkeep/agents/tree/main/agents-cookbook/template-projects)

When to link

链接时机

  • Inline links: When reader needs a prerequisite immediately or you're referencing a concept defined elsewhere
  • "Next steps" links: When reader is done with this page and should continue a journey (1-3 links, Cards work well)
  • 内联链接：读者需要立即了解前置知识，或你引用了别处定义的概念时
  • “后续步骤”链接：读者完成当前页面后，需要继续学习时（1-3个链接，使用Cards组件效果佳）

Writing Style Rules

写作风格规则

Do

推荐做法

  • Be concise: Get to the point in the first sentence
  • Use active voice: "Configure the agent" not "The agent can be configured"
  • Be directive: "Run this command" not "You might want to run"
  • Include examples: Every concept needs a code example
  • Explain why: "Use connection pooling to avoid exhausting connections"
  • 简洁：第一句话就点明主题
  • 使用主动语态：“Configure the agent”而非“The agent can be configured”
  • 指令性语气：“Run this command”而非“You might want to run”
  • 包含示例：每个概念都需要代码示例
  • 解释原因：“Use connection pooling to avoid exhausting connections”

Don't

避免做法

  • Don't use "simply" or "just"
  • Don't assume prior knowledge without stating prerequisites
  • Don't write walls of text without code examples
  • Don't use jargon without explanation on first use
  • 不要使用“simply”或“just”
  • 不要在未说明前提条件的情况下假设读者具备前置知识
  • 不要编写无代码示例的大段文字
  • 首次使用行话时不做解释

Formatting conventions

格式约定

  • Paragraphs: 1-2 sentences typical before a visual break
  • Steps: One action per step, imperative mood
  • Contractions: Use "don't", "you'll", etc.
  • Person: Address reader as "you"; use "we" when speaking as Inkeep
  • Bullets: Capital letter start, no trailing period unless full sentence, bold lead keywords for scannability
  • UI references: Bold labels (
    **Save**
    ), use 
    →
    between hierarchy levels
  • 段落：通常1-2句话后添加视觉分隔
  • 步骤：每个步骤一个动作，使用祈使语气
  • 缩写：使用“don't”、“you'll”等
  • 人称：用“你”称呼读者；用“我们”代表Inkeep团队
  • 项目符号：首字母大写，完整句子才加句号，关键词加粗以提高可读性
  • UI引用：标签加粗（
    **Save**
    ），层级之间使用
    →
    分隔

File Organization

文件组织

Directory structure

目录结构

  • agents-docs/content/
    — main docs pages (
    .mdx
    )
  • agents-docs/_snippets/
    — reusable snippet content (
    .mdx
    )
  • agents-docs/public/images/
    — screenshots/diagrams
  • agents-docs/public/videos/
    — MP4 demos
  • agents-docs/public/gifs/
    — short UI walkthroughs
  • agents-docs/content/
    — 主文档页面（
    .mdx
    格式）
  • agents-docs/_snippets/
    — 可复用的代码片段内容（
    .mdx
    格式）
  • agents-docs/public/images/
    — 截图/图表
  • agents-docs/public/videos/
    — MP4演示视频
  • agents-docs/public/gifs/
    — 简短UI演示动图

File Renames, Moves, and Redirects

文件重命名、移动与重定向

When you rename or move a file, add a redirect to 
agents-docs/redirects.json
:
json
{
  "source": "/old-path/old-page",
  "destination": "/new-path/new-page",
  "permanent": true
}
Also update any internal links referencing the old path.
重命名或移动文件时，必须在
agents-docs/redirects.json
中添加重定向规则：
json
{
  "source": "/old-path/old-page",
  "destination": "/new-path/new-page",
  "permanent": true
}
同时更新所有引用旧路径的内部链接。

Navigation (meta.json)

导航配置（meta.json）

Edit the nearest parent 
meta.json
when you:
  • Add a page and need it in the sidebar
  • Control ordering or group pages
  • Set a folder-level icon
Common patterns:
  • Explicit list: 
    ["project-management", "agent-settings", ...]
  • Group markers: 
    "(observability)"
  • Remainder marker: 
    "..."
    to include remaining pages
  • Section headers: 
    "---TUTORIALS---"
    (visual separators)
以下情况需编辑最近的父级
meta.json
：
  • 添加页面并需要在侧边栏显示时
  • 控制页面排序或分组时
  • 设置文件夹级别的图标时
常见模式：
  • 显式列表：
    ["project-management", "agent-settings", ...]
  • 分组标记：
    "(observability)"
  • 剩余页面标记：
    "..."
    用于包含剩余所有页面
  • 章节标题：
    "---TUTORIALS---"
    （视觉分隔符）

Where should a new page go?

新页面的存放位置

Is it about shipping/hosting/running infra?
├─ Yes → deployment/
│
Is it a code-first SDK/API usage guide?
├─ Yes → typescript-sdk/
│
Is it a Visual Builder UI workflow?
├─ Yes → visual-builder/
│
Is it about embedding chat / chat UI components?
├─ Yes → talk-to-your-agents/(chat-components)/
│
Is it connecting external data sources?
└─ Yes → connect-your-data/
Top-level buckets: 
get-started/
, 
tutorials/
, 
typescript-sdk/
, 
visual-builder/
, 
talk-to-your-agents/
, 
connect-your-data/
, 
deployment/
, 
api-reference/
, 
community/
, 
comparisons/
是否与部署/托管/基础设施运行相关？
├─ 是 → deployment/
│
是否为代码优先的SDK/API使用指南？
├─ 是 → typescript-sdk/
│
是否为可视化构建器UI工作流？
├─ 是 → visual-builder/
│
是否与嵌入聊天/聊天UI组件相关？
├─ 是 → talk-to-your-agents/(chat-components)/
│
是否为连接外部数据源？
└─ 是 → connect-your-data/
顶级分类：
get-started/
、
tutorials/
、
typescript-sdk/
、
visual-builder/
、
talk-to-your-agents/
、
connect-your-data/
、
deployment/
、
api-reference/
、
community/
、
comparisons/

When to create a new folder

何时创建新文件夹

Create a folder when:
  • Adding 3+ pages that should be navigated together
  • You need folder-level ordering (
    meta.json
    )
  • You want a folder-level icon/title in sidebar
Use parentheses folders like 
(docker)
to group pages without changing the URL.
以下情况创建新文件夹：
  • 添加3个及以上需要一起导航的页面时
  • 需要文件夹级别的排序（
    meta.json
    ）时
  • 希望在侧边栏显示文件夹级别的图标/标题时
使用带括号的文件夹名如
(docker)
来分组页面，且不改变URL。

Images and Media

图片与媒体

When to use screenshots

何时使用截图

Screenshots earn their place when the reader needs spatial context — where to find something in a UI, what a result looks like, or what state to expect. Not every step needs an image.
SituationScreenshot?Why
User must locate a button, menu, or setting in the UIYesSpatial context is the fastest way to orient
Step produces a visible result the user should verifyYes"You should see this" builds confidence
Before/after comparison for a configuration changeYesVisual diff is clearer than description
Step is a CLI command or code-only actionNoCode blocks are sufficient
UI is self-explanatory (single prominent button, obvious form)NoScreenshot adds noise, not signal
Content changes frequently (dashboard metrics, timestamps)AvoidScreenshots go stale fast — describe the pattern instead
Rule of thumb: If you can describe the action in one sentence without the reader getting lost, skip the screenshot.
截图的价值在于为读者提供空间上下文——帮助读者在UI中找到某个元素、查看结果样式，或了解预期状态。并非每个步骤都需要截图。
场景是否使用截图？原因
用户必须在UI中找到按钮、菜单或设置项是空间上下文是最快的定位方式
步骤产生的可见结果需要用户验证是“你应该看到这样的结果”能增强用户信心
配置变更的前后对比是视觉差异比文字描述更清晰
步骤仅为CLI命令或代码操作否代码块已足够说明
UI内容一目了然（单个显眼按钮、简单表单）否截图会增加冗余信息，而非有效信号
内容频繁变化（控制台指标、时间戳）避免截图容易过时——改用描述模式
经验法则：如果能用一句话描述操作且不会让读者困惑，就不要使用截图。

Screenshot quality standards

截图质量标准

  • Viewport: Capture at 1280x720 with 2x device scale for retina clarity
  • Format: PNG for UI screenshots; keep under 200KB (crop tightly)
  • Crop: Show only the relevant panel or section — never a full browser window with empty space
  • Sensitive data: Mask API keys, emails, and user-specific data before capture. Use realistic but clearly fake values (e.g., 
    sk-test-...
    , 
    user@example.com
    )
  • Browser chrome: Exclude browser toolbars, tabs, and OS chrome — capture the page content only
  • Consistent state: Use a clean, predictable UI state (default theme, no notification badges, standard viewport)
  • 视口：以1280x720分辨率、2倍设备缩放比捕获，确保视网膜屏幕清晰度
  • 格式：UI截图使用PNG格式；文件大小控制在200KB以内（精准裁剪）
  • 裁剪：仅显示相关面板或区域——不要捕获包含空白区域的完整浏览器窗口
  • 敏感数据：捕获前遮盖API密钥、邮箱和用户特定数据。使用真实但明显为虚构的值（如
    sk-test-...
    、
    user@example.com
    ）
  • 浏览器界面：排除浏览器工具栏、标签页和系统界面——仅捕获页面内容
  • 一致状态：使用干净可预测的UI状态（默认主题、无通知标记、标准视口）

Screenshot composition

截图排版

  • Text before image: Always describe what the screenshot shows before displaying it. The reader should know what to look for.
  • One concept per screenshot: Don't try to show two unrelated things in one image. If a step involves two parts of the UI, use two screenshots.
  • Max 3-4 annotations: If you need callouts (arrows, circles, numbered markers), keep them minimal. Over-annotated screenshots are harder to parse than un-annotated ones.
  • Never two screenshots consecutively: Put explanatory text between images. Back-to-back screenshots without context are a wall of images.
  • Caption via alt text, not 
    <figcaption>
    : The 
    <Image>
    component handles display; write meaningful alt text.
  • 先文后图：显示截图前，先描述截图内容。让读者知道需要关注什么。
  • 一图一概念：不要在一张截图中展示两个不相关的内容。如果步骤涉及UI的两个部分，使用两张截图。
  • 最多3-4个标注：如果需要添加标注（箭头、圆圈、数字标记），请尽量精简。过度标注的截图比无标注的更难理解。
  • 不要连续放置两张截图：在图片之间添加说明文字。无上下文的连续截图会形成视觉墙。
  • 通过alt文本添加说明：
    <Image>
    组件负责显示；编写有意义的alt文本，而非使用
    <figcaption>
    。

Image file conventions

图片文件约定

  • Storage: 
    agents-docs/public/images/
    — use kebab-case filenames
  • Naming: 
    {feature}-{what-it-shows}.png
    (e.g., 
    traces-live-debugger.png
    , 
    project-settings-api-keys.png
    )
  • Alt text: Describe what's shown with key details, not what it "is." Under 125 characters when possible.
    • Good: 
      "Project settings page with API keys section highlighted"
    • Avoid: 
      "Image of the settings page"
      or 
      "Screenshot"
  • 存储位置：
    agents-docs/public/images/
    — 使用短横线分隔的文件名
  • 命名规则：
    {feature}-{what-it-shows}.png
    （例如
    traces-live-debugger.png
    、
    project-settings-api-keys.png
    ）
  • Alt文本：描述截图内容及关键细节，而非仅说明“这是一张截图”。尽量控制在125字符以内。
    • 推荐：
      "项目设置页面，突出显示API密钥区域"
    • 避免：
      "设置页面图片"
      或
      "截图"

Image component

图片组件

mdx
<Image
  src="/images/live-traces.png"
  alt="Live traces interface showing real-time agent execution"
/>
The 
<Image>
component renders full-width with rounded corners and click-to-zoom. No extra styling needed.
mdx
<Image
  src="/images/live-traces.png"
  alt="实时追踪界面，显示Agent的实时执行情况"
/>
<Image>
组件会渲染为全屏宽度、带圆角的图片，支持点击放大。无需额外样式。

Videos

视频

mdx
<Video
  src="https://www.youtube.com/watch?v=..."
  title="What the user will learn"
/>
Use video (
<BigVideo>
for MP4, 
<Video>
for YouTube) when the interaction involves multi-step flows where timing and transitions matter — e.g., drag-and-drop, real-time streaming responses, or complex UI sequences that screenshots can't convey.
mdx
<Video
  src="https://www.youtube.com/watch?v=..."
  title="用户将学到的内容"
/>
当交互涉及多步骤流程，且时间和过渡效果很重要时（例如拖放、实时流响应、复杂UI序列，截图无法完整展示），使用视频（
<BigVideo>
用于MP4，
<Video>
用于YouTube）。

Icons

图标

Icons resolve as 
Lu...
(Lucide), 
Tb...
(react-icons/tb), or 
brand/...
(custom in 
brand-icons.tsx
).
  • Section icon (folder 
    meta.json
    ): When whole section needs nav identity
  • Page icon (frontmatter): For landing/overview pages or frequently linked cards
To add a brand icon: export a component in 
agents-docs/src/components/brand-icons.tsx
, reference as 
icon: "brand/<ExportName>"
图标可使用
Lu...
（Lucide）、
Tb...
（react-icons/tb）或
brand/...
（
brand-icons.tsx
中的自定义图标）。
  • 章节图标（文件夹的
    meta.json
    ）：整个章节需要导航标识时使用
  • 页面图标（前置元数据）：首页/概述页面或频繁在卡片中链接的页面使用
添加品牌图标：在
agents-docs/src/components/brand-icons.tsx
中导出组件，引用格式为
icon: "brand/<ExportName>"

Snippets

代码片段

Use 
<Snippet>
when content must stay identical across pages:
mdx
<Snippet file="pull-prereq.mdx" />
Paths resolve relative to 
agents-docs/_snippets/
. Use this to prevent duplication and divergence.
当内容需要在多个页面保持完全一致时，使用
<Snippet>
：
mdx
<Snippet file="pull-prereq.mdx" />
路径相对于
agents-docs/_snippets/
。使用此功能可避免内容重复和不一致。

Source-derived docs

源衍生文档

Use 
AutoTypeTable
for TypeScript types that change:
mdx
<AutoTypeTable
  path="./content/typescript-sdk/types.ts"
  name="NestedInkeepConfig"
/>
This keeps reference tables accurate as code evolves.
对于会变化的TypeScript类型，使用
AutoTypeTable
：
mdx
<AutoTypeTable
  path="./content/typescript-sdk/types.ts"
  name="NestedInkeepConfig"
/>
这样可确保参考表格随代码演变保持准确。

SkillRule — extracting skills from docs

SkillRule — 从文档中提取技能

Use 
<SkillRule>
when a page is mostly narrative but contains a checklist, table, or decision framework valuable for AI agents. Avoid extracting purely narrative or marketing sections.
Why: Skills should be high-signal and procedural. Extract only the parts that help an agent make correct decisions or produce correct code.
当页面以叙述内容为主，但包含对AI Agent有价值的清单、表格或决策框架时，使用
<SkillRule>
。避免提取纯叙述或营销内容。
原因：技能应是高信号、流程化的内容。仅提取有助于Agent做出正确决策或生成正确代码的部分。

Examples

示例

✅ Good: extract a checklist from a longer narrative
mdx
<SkillRule id="setup" skills="typescript-sdk" title="Setup checklist">
✅ 推荐：从长叙述中提取清单
mdx
<SkillRule id="setup" skills="typescript-sdk" title="设置清单">

Before you begin

开始之前

  1. Install dependencies
  2. Configure 
    inkeep.config.ts
</SkillRule> ```
❌ Avoid: wrapping the whole page in SkillRule
mdx
<!-- Don't do this - too much content, not high-signal -->
<SkillRule id="overview" skills="typescript-sdk" title="SDK Overview">
  [entire page content...]
</SkillRule>
  1. 安装依赖
  2. 配置
    inkeep.config.ts
</SkillRule> ```
❌ 避免：将整个页面包裹在SkillRule中
mdx
<!-- 不要这样做 - 内容过多，信号不强 -->
<SkillRule id="overview" skills="typescript-sdk" title="SDK概述">
  [整个页面内容...]
</SkillRule>

API Reference (OpenAPI-driven)

API参考（由OpenAPI驱动）

Recognize by 
full: true
and 
_openapi:
frontmatter. Edit only to adjust presentation; change endpoints/schemas at the OpenAPI source.
通过前置元数据中的
full: true
和
_openapi:
识别。仅调整展示方式；如需修改端点/架构，请在OpenAPI源文件中操作。

Verification Checklist

验证清单

Before completing any documentation, verify:
完成任何文档前，请验证以下内容：

Frontmatter

前置元数据

  • Has 
    title
    (descriptive, sentence case)
  • Has 
    sidebarTitle
    if title is long or redundant in nav
  • Description added if page is important for SEO
  • 包含
    title
    （描述性、句子大小写）
  • 若标题过长或在导航中重复，添加了
    sidebarTitle
  • 若页面对SEO重要，添加了描述

Content

内容

  • Opens with what this page covers (not "In this guide...")
  • Code examples are complete and runnable
  • All code blocks have language specified
  • Prerequisites listed (if applicable)
  • Links to related docs included
  • 开篇说明页面涵盖的内容（不要使用“在本指南中...”）
  • 代码示例完整且可运行
  • 所有代码块都指定了语言
  • 列出了前提条件（如适用）
  • 包含相关文档的链接

Structure

结构

  • Appropriate pattern used (reference/tutorial/integration/overview)
  • Components used correctly (Tabs for variants, Steps for sequences)
  • Tables used for parameters/options
  • Headings are scannable and descriptive
  • 使用了合适的模式（参考/教程/集成/概述）
  • 组件使用正确（多版本代码用Tabs，分步说明用Steps）
  • 参数/选项使用表格展示
  • 标题清晰易扫描

Quality

质量

  • No "click here" links
  • No assumed knowledge without prerequisites
  • Active voice throughout
  • Examples show realistic values
  • 没有“click here”这类链接
  • 没有未说明前提条件的假设性知识
  • 全程使用主动语态
  • 示例使用真实合理的取值

Navigation (if applicable)

导航（如适用）

  • meta.json
    updated to include new page
  • Redirects added for any moves/renames
  • 更新
    meta.json
    以包含新页面
  • 为任何移动/重命名的页面添加了重定向