---
description: "文档站编写规范 — 改 docs/** 时遵守的写作风格、链接规则、VitePress 注意事项"
globs:
  - "docs/**"
alwaysApply: false
---

# 文档编写规范（docs/**）

## VitePress 配置约束

`docs/.vitepress/config.mts` 关键设置：

```typescript
cleanUrls: false   // 必须保留：让 R2 直接命中 .html 文件
```

如果改成 `cleanUrls: true`，`docs.cutcli.com/guide/installation` 就需要 worker 强行重写到 `.html`，但 worker 已经做了路径回退（`/foo` → `foo.html` → `foo/index.html`），这层回退是为了兼容 cleanUrls 风格的链接，不要因此关掉路径回退。

## 中文文档风格

- 中英文之间 1 个空格：「使用 cutcli 创建草稿」
- 数字与中文之间 1 个空格：「3 秒后退出」
- 标点：使用全角中文标点（，。？！）；代码 / 命令内保持半角
- 引号：内容用「」，引用用 ""

## 标题层级

- 每篇 markdown **唯一** H1（用文件 frontmatter `title` 也行，但要么 frontmatter 要么 H1，二选一不要双写）
- H2 用作主要章节
- H3 / H4 用作小节
- 不要直接跳层（H2 → H4）

## 文件名 / URL 风格

- 文件名 kebab-case：`first-draft.md`、`time-units.md`
- URL 不带扩展名（VitePress 自动加 `.html`）
- 内部链接用相对路径：`./first-draft` 或 `/guide/first-draft`
- 引用案例用绝对 GitHub 链接：`https://github.com/xuliang2024/cutcli-cookbook/tree/main/examples/...`

## 链接规则

| 场景 | 写法 |
|---|---|
| 同侧栏内的 guide 互链 | `[一节](./time-units)` |
| 跨侧栏（guide → reference） | `[CLI](/reference/cli)` |
| 引用案例目录 | `[`examples/01-hello-caption`](https://github.com/xuliang2024/cutcli-cookbook/tree/main/examples/01-hello-caption)` |
| 外链（cutcli.com、GitHub） | 直接 `<https://...>` 或 `[文字](https://...)` |
| 引用图片资源 | 放 `docs/public/` 下，URL 用 `/foo.svg`（不是 `./public/foo.svg`） |

CI 用 `scripts/check-links.mjs` 校验内部链接，不通过 fail。

## 命令示例

- 命令名严格 `cutcli`，不写 `cut`
- 多行命令换行用 `\` 续行
- 复杂 JSON 用 `--captions @data/captions.json` 文件引用，避免 shell 转义噩梦
- 时间字段必须是整数微秒（`3000000`）；不写 `3s` / `3000ms`

## 表格

- 用纯 markdown 表格（`| ... |`）
- 不要拿 HTML table
- 列对齐用 `|---|`、`|:---|`、`|---:|`、`|:---:|`

## 代码块

- 都加语言：`bash`、`json`、`typescript`、`yaml`
- shell 命令前不加 `$` 提示符（VitePress 主题已视觉化）
- 引用本地文件路径用 `inline code`，例如 `` `docs/.vitepress/config.mts` ``

## VitePress 特有语法

```markdown
::: tip
小提示
:::

::: warning
警告
:::

::: danger
危险操作
:::

::: details 折叠展开
里面写细节
:::
```

适度用，不要每段都包。

## 自动生成区域 ⚠

`docs/reference/cli.md`、`docs/reference/api.md`、`docs/reference/concepts.md` 由 `jy_cli/scripts/sync-to-cookbook.mjs` 单向覆盖。**不要直接编辑**：

- 改这些文件 → 下次同步会被覆盖回去
- 真要改 → 改 `jy_cli/docs/cli.md`（或 api.md / README.md）→ 跑 `node scripts/sync-to-cookbook.mjs`

文件顶部有 `<!-- THIS FILE IS GENERATED ... DO NOT EDIT. -->` 标识。

## 新增页面

1. 在 `docs/<section>/` 加新 `.md` 文件
2. 在 `docs/.vitepress/config.mts` 的对应 `sidebar` 数组里加链接
3. 跑 `npm run docs:build` 看是否成功
4. 跑 `npm run lint:links` 看新链接是否可达

## 国际化（i18n）

**英文为默认 locale**，中文是第二语言。

| 内容 | 英文（root） | 中文 |
|---|---|---|
| 文档站 | `docs/<section>/*.md` | `docs/zh/<section>/*.md` |
| 仓库门面 | `README.md` | `README.zh.md` |
| 治理文档 | `CONTRIBUTING.md` / `CHANGELOG.md` | `CONTRIBUTING.zh.md` / `CHANGELOG.zh.md` |
| 子目录 README | `templates/README.md` 等 | `templates/README.zh.md` 等 |
| 案例 README | `examples/<id>/README.md` | `examples/<id>/README.zh.md` |
| 提示词 | `prompts/system/cutcli-expert.md` | `prompts/system/cutcli-expert.zh.md` |
| GitHub Issue / PR 模板 | 单文件双语（English / 中文 同行写） | 同左 |
| 维护者文档 | — | `.github/RELEASE_GUIDE.md`、`showcase/launch.md`、`.cursor/rules/*` 都保留中文 |

VitePress `locales`：

```typescript
locales: {
  root: { label: 'English', lang: 'en-US', themeConfig: { ... } },
  zh:   { label: '简体中文', lang: 'zh-CN', link: '/zh/', themeConfig: { ... } },
}
```

新建任何面向用户的 markdown，**默认要写英文 + 一份中文 .zh.md**。`scripts/check-i18n-pairs.mjs` 会扫成对存在；`npm run lint:i18n` 失败时不能合并。

`docs/reference/{cli,api,concepts}.md` 由闭源仓 `jy_cli/scripts/sync-to-cookbook.mjs` 写入，因此暂时跳过 i18n-pairs 检查；闭源仓同步脚本升级后会双语输出（详见 `.cursor/rules/open-source-boundary.mdc`）。

每个 README / docs / prompts 的顶部加双语切换链接：

```markdown
[English](README.md) · [简体中文](README.zh.md)
```

## 静态资源

- SVG / PNG / GIF 放 `docs/public/`
- 文件大小：单图 ≤ 200 KB，超过用 R2 + CDN 链接
- 命名：kebab-case，`hero.svg` / `case-thumbnail-01.png`

## 字数控制

- 单页 ≤ 1500 字（中文计算）
- 超过就拆 2 篇
- 章节排版：先 1-2 句概述 → 表格/列表 → 代码示例 → 进阶链接

## 生成 gallery

如果加了新 case，跑：

```bash
npm run build:gallery   # 重新生成 docs/public/gallery.json
npm run docs:build
```