49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
# AGENTS.md — @app/docs
|
||
|
||
## 职责
|
||
|
||
**产品文档站**（VitePress）：面向用户的使用说明，中文在根路径、英文在 `/en`。与 `@app/web` 产品页分离——这里是文档，不是应用路由。
|
||
|
||
不依赖 `@app/*` 业务包；纯 Markdown + VitePress 配置，无 tRPC / DB。
|
||
|
||
## 结构
|
||
|
||
```
|
||
.vitepress/
|
||
config.mts # locales（root=zh-CN, en）、nav、sidebar、搜索文案
|
||
theme/index.ts # 扩展默认主题；无本地偏好时默认暗色（与主应用一致）
|
||
theme/custom.css # 自定义样式
|
||
guide/ # 中文文档（权威源）
|
||
what-is.md | quick-start.md | mount.md | browse.md
|
||
library.md | danmaku.md | scrape.md | account.md | faq.md
|
||
en/guide/ # 英文文档（与 guide/ 同构，逐篇对应）
|
||
index.md # 中文首页
|
||
en/index.md # 英文首页
|
||
public/ # 静态资源（favicon 等）
|
||
```
|
||
|
||
## 约定
|
||
|
||
- **双语同构**：`guide/*.md` 与 `en/guide/*.md` 文件名一一对应；新增页面两边同时加，并在 `config.mts` 的 `zhSidebar` / `enSidebar` 登记。
|
||
- 路径用 `cleanUrls: true`（链接不带 `.html`）。
|
||
- 文案语气与产品一致（「帆幕」/「Fanmu」）；中文文档用简体中文，不混繁体。
|
||
- 搜索为 VitePress local provider，UI 文案在 `config.mts` 的 `themeConfig.search` 内联翻译，不另建 i18n 包。
|
||
- 主题默认暗色：`theme/index.ts` 在无 `vitepress-theme-appearance` 时写入 `dark`，与 web 的 `app-theme` 偏好独立。
|
||
|
||
## 修改指南
|
||
|
||
- **加一页文档**：`guide/<slug>.md` + `en/guide/<slug>.md` → 更新 `config.mts` 两侧 sidebar。
|
||
- **改导航顺序**：只改 `config.mts` 的 `zhNav`/`zhSidebar`/`enNav`/`enSidebar`，保持中英结构对称。
|
||
- **加静态资源**：放 `public/`，引用用绝对路径 `/xxx`。
|
||
- 不要引入 Vue 组件或自定义布局（当前只用默认主题 + CSS）；确需扩展时走 `theme/index.ts`。
|
||
- 构建产物 `.vitepress/dist/` 与缓存 `.vitepress/cache/` 勿手改。
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
yarn docs:dev # 本地预览
|
||
yarn docs:build # 构建到 .vitepress/dist/
|
||
yarn workspace @app/docs typecheck
|
||
yarn workspace @app/docs lint
|
||
```
|