Cursor rule

1---
2description: "文档站编写规范 — 改 docs/** 时遵守的写作风格、链接规则、VitePress 注意事项"
3globs:
4  - "docs/**"
5alwaysApply: false
6---
7 
8# 文档编写规范（docs/**）
9 
10## VitePress 配置约束
11 
12`docs/.vitepress/config.mts` 关键设置：
13 
14```typescript
15cleanUrls: false   // 必须保留：让 R2 直接命中 .html 文件
16```
17 
18如果改成 `cleanUrls: true`，`docs.cutcli.com/guide/installation` 就需要 worker 强行重写到 `.html`，但 worker 已经做了路径回退（`/foo` → `foo.html` → `foo/index.html`），这层回退是为了兼容 cleanUrls 风格的链接，不要因此关掉路径回退。
19 
20## 中文文档风格
21 
22- 中英文之间 1 个空格：「使用 cutcli 创建草稿」
23- 数字与中文之间 1 个空格：「3 秒后退出」
24- 标点：使用全角中文标点（，。？！）；代码 / 命令内保持半角
25- 引号：内容用「」，引用用 ""
26 
27## 标题层级
28 
29- 每篇 markdown **唯一** H1（用文件 frontmatter `title` 也行，但要么 frontmatter 要么 H1，二选一不要双写）
30- H2 用作主要章节
31- H3 / H4 用作小节
32- 不要直接跳层（H2 → H4）
33 
34## 文件名 / URL 风格
35 
36- 文件名 kebab-case：`first-draft.md`、`time-units.md`
37- URL 不带扩展名（VitePress 自动加 `.html`）
38- 内部链接用相对路径：`./first-draft` 或 `/guide/first-draft`
39- 引用案例用绝对 GitHub 链接：`https://github.com/xuliang2024/cutcli-cookbook/tree/main/examples/...`
40 
41## 链接规则
42 
43| 场景 | 写法 |
44|---|---|
45| 同侧栏内的 guide 互链 | `[一节](./time-units)` |
46| 跨侧栏（guide → reference） | `[CLI](/reference/cli)` |
47| 引用案例目录 | `[`examples/01-hello-caption`](https://github.com/xuliang2024/cutcli-cookbook/tree/main/examples/01-hello-caption)` |
48| 外链（cutcli.com、GitHub） | 直接 `<https://...>` 或 `[文字](https://...)` |
49| 引用图片资源 | 放 `docs/public/` 下，URL 用 `/foo.svg`（不是 `./public/foo.svg`） |
50 
51CI 用 `scripts/check-links.mjs` 校验内部链接，不通过 fail。
52 
53## 命令示例
54 
55- 命令名严格 `cutcli`，不写 `cut`
56- 多行命令换行用 `\` 续行
57- 复杂 JSON 用 `--captions @data/captions.json` 文件引用，避免 shell 转义噩梦
58- 时间字段必须是整数微秒（`3000000`）；不写 `3s` / `3000ms`
59 
60## 表格
61 
62- 用纯 markdown 表格（`| ... |`）
63- 不要拿 HTML table
64- 列对齐用 `|---|`、`|:---|`、`|---:|`、`|:---:|`
65 
66## 代码块
67 
68- 都加语言：`bash`、`json`、`typescript`、`yaml`
69- shell 命令前不加 `$` 提示符（VitePress 主题已视觉化）
70- 引用本地文件路径用 `inline code`，例如 `` `docs/.vitepress/config.mts` ``
71 
72## VitePress 特有语法
73 
74```markdown
75::: tip
76小提示
77:::
78 
79::: warning
80警告
81:::
82 
83::: danger
84危险操作
85:::
86 
87::: details 折叠展开
88里面写细节
89:::
90```
91 
92适度用，不要每段都包。
93 
94## 自动生成区域 ⚠
95 
96`docs/reference/cli.md`、`docs/reference/api.md`、`docs/reference/concepts.md` 由 `jy_cli/scripts/sync-to-cookbook.mjs` 单向覆盖。**不要直接编辑**：
97 
98- 改这些文件 → 下次同步会被覆盖回去
99- 真要改 → 改 `jy_cli/docs/cli.md`（或 api.md / README.md）→ 跑 `node scripts/sync-to-cookbook.mjs`
100 
101文件顶部有 `<!-- THIS FILE IS GENERATED ... DO NOT EDIT. -->` 标识。
102 
103## 新增页面
104 
1051. 在 `docs/<section>/` 加新 `.md` 文件
1062. 在 `docs/.vitepress/config.mts` 的对应 `sidebar` 数组里加链接
1073. 跑 `npm run docs:build` 看是否成功
1084. 跑 `npm run lint:links` 看新链接是否可达
109 
110## 国际化（i18n）
111 
112**英文为默认 locale**，中文是第二语言。
113 
114| 内容 | 英文（root） | 中文 |
115|---|---|---|
116| 文档站 | `docs/<section>/*.md` | `docs/zh/<section>/*.md` |
117| 仓库门面 | `README.md` | `README.zh.md` |
118| 治理文档 | `CONTRIBUTING.md` / `CHANGELOG.md` | `CONTRIBUTING.zh.md` / `CHANGELOG.zh.md` |
119| 子目录 README | `templates/README.md` 等 | `templates/README.zh.md` 等 |
120| 案例 README | `examples/<id>/README.md` | `examples/<id>/README.zh.md` |
121| 提示词 | `prompts/system/cutcli-expert.md` | `prompts/system/cutcli-expert.zh.md` |
122| GitHub Issue / PR 模板 | 单文件双语（English / 中文 同行写） | 同左 |
123| 维护者文档 | — | `.github/RELEASE_GUIDE.md`、`showcase/launch.md`、`.cursor/rules/*` 都保留中文 |
124 
125VitePress `locales`：
126 
127```typescript
128locales: {
129  root: { label: 'English', lang: 'en-US', themeConfig: { ... } },
130  zh:   { label: '简体中文', lang: 'zh-CN', link: '/zh/', themeConfig: { ... } },
131}
132```
133 
134新建任何面向用户的 markdown，**默认要写英文 + 一份中文 .zh.md**。`scripts/check-i18n-pairs.mjs` 会扫成对存在；`npm run lint:i18n` 失败时不能合并。
135 
136`docs/reference/{cli,api,concepts}.md` 由闭源仓 `jy_cli/scripts/sync-to-cookbook.mjs` 写入，因此暂时跳过 i18n-pairs 检查；闭源仓同步脚本升级后会双语输出（详见 `.cursor/rules/open-source-boundary.mdc`）。
137 
138每个 README / docs / prompts 的顶部加双语切换链接：
139 
140```markdown
141[English](README.md) · [简体中文](README.zh.md)
142```
143 
144## 静态资源
145 
146- SVG / PNG / GIF 放 `docs/public/`
147- 文件大小：单图 ≤ 200 KB，超过用 R2 + CDN 链接
148- 命名：kebab-case，`hero.svg` / `case-thumbnail-01.png`
149 
150## 字数控制
151 
152- 单页 ≤ 1500 字（中文计算）
153- 超过就拆 2 篇
154- 章节排版：先 1-2 句概述 → 表格/列表 → 代码示例 → 进阶链接
155 
156## 生成 gallery
157 
158如果加了新 case，跑：
159 
160```bash
161npm run build:gallery   # 重新生成 docs/public/gallery.json
162npm run docs:build
163```
164