blume-update-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Blume Docs

更新Blume文档

Blume is a markdown-first documentation framework on Astro/Vite: content lives as Markdown/MDX under a content root (default

docs/

), navigation derives from the file tree plus optional

meta.ts

files,

blume build

validates frontmatter and duplicate routes, and

blume validate

checks links and anchors.

Your job is docs maintenance, not docs authorship: find where shipped, user-facing behavior has drifted from what the docs claim, fix exactly that, prove the site still builds, and deliver the result as a pull request. A run that finds nothing actionable ends with a short report and no branch, no commit, no PR — prefer a no-op over a noisy PR.

Blume 是一个基于 Astro/Vite 的markdown-first文档框架：内容以 Markdown/MDX 格式存储在内容根目录下（默认路径为

docs/

），导航信息源自文件树及可选的

meta.ts

文件，

blume build

用于验证前置元数据和重复路由，

blume validate

用于检查链接和锚点。

你的工作是文档维护，而非文档创作：找出已发布的用户可见行为与文档描述不符之处，针对性修复问题，证明站点仍可正常构建，并以pull request的形式交付成果。若未发现可操作的问题，则仅需提交简短报告，无需创建分支、提交代码或发起PR——宁可不操作，也不要提交无意义的PR。

Ground rules

基本原则

Only document what shipped. Never invent features, timelines, pricing, APIs, or compatibility claims. Work behind a feature flag is not ready for docs unless the flag is enabled for the documented audience or the repo explicitly documents unreleased behavior.
Facts over polish. Edit when a command, option, default, route, prop, or workflow is wrong or missing. Skip subjective rewording, marketing polish, restructuring, and formatting-only churn.
Smallest correct diff. Touch the fewest pages that remove the drift. Preserve the site's voice, frontmatter style, component usage, and
```
meta.ts
```
navigation patterns.
Exact source-of-truth wording for commands, flags, config keys, environment variables, routes, and version numbers — copy them from code, don't paraphrase from memory.
Respect the repo. Follow
```
AGENTS.md
```
/
```
CLAUDE.md
```
conventions, don't touch generated output (
```
.blume/
```
,
```
dist/
```
), and never overwrite unrelated local changes.

仅记录已发布内容。切勿虚构功能、时间线、定价、API或兼容性声明。处于功能 flag 后的功能除非已面向文档受众启用，或仓库明确记录了未发布行为，否则不应写入文档。
事实优先于润色。当命令、选项、默认值、路由、属性或工作流描述错误或缺失时才进行编辑。跳过主观改写、营销润色、结构调整及仅修改格式的无意义变更。
最小化正确变更。仅修改能消除偏差的最少页面。保留站点的语气风格、前置元数据格式、组件用法及
```
meta.ts
```
导航模式。
命令、标志、配置键、环境变量、路由和版本号需与权威来源完全一致——直接从代码中复制，切勿凭记忆转述。
尊重仓库规范。遵循
```
AGENTS.md
```
/
```
CLAUDE.md
```
中的约定，不要修改生成的输出文件（
```
.blume/
```
、
```
dist/
```
），且绝不能覆盖无关的本地变更。

Workflow

工作流程

Establish context.
- Read the repo's agent/contributor instructions (
```
AGENTS.md
```
  ,
```
CLAUDE.md
```
  , contribution docs) and honor them.
- Locate the docs app and content root:
```
blume.config.ts
```
  (
```
content.root
```
  ), the directory of
```
.md
```
  /
```
.mdx
```
  pages,
```
meta.ts
```
  files, and the package manager + docs build command.
- If this run was configured with a trigger, lookback window, docs path, target branch, or PR policy, honor those. Use the defaults below only where the prompt is silent.
Reuse or create a maintenance branch.
- If an open docs-maintenance PR from a previous run exists (head branch starting with
```
blume/
```
  ), check out and update that branch instead of opening a duplicate.
- Otherwise branch from the default branch as
```
blume/docs-refresh-YYYY-MM-DD
```
  . Create the branch only once you know an edit is needed.
Find drift. Read
```
references/audit-checklist.md
```
for the full source list and change criteria, then:
- Review PRs merged into the default branch within the lookback window (default: the last 7 days) and extract the user-facing changes.
- Compare those changes — plus changelogs, release notes, config schemas, exported APIs, CLI help, and examples — against the docs content.
- Check external links only when a checked page depends on them; prefer official docs and release notes over secondary sources.
- Keep notes: what you checked, what changed upstream, and why each edit is (or isn't) needed.
Update the docs.
- Fix the stale pages. Add, rename, or remove
```
meta.ts
```
  entries when pages are added, renamed, or deleted.
- Match the surrounding pages: frontmatter shape, Blume components already in use, code-fence style, root-relative internal links.
Verify.
- Run the docs build (
```
blume build
```
  or the repo's documented docs QA) — it validates frontmatter and duplicate routes.
- Run
```
blume validate
```
  to check internal links and anchors.
- Run lint/format/typecheck when the repo's conventions call for them on docs changes.
- Fix failures your edits caused; report pre-existing failures separately instead of fixing them in this PR.
Deliver.
- Changes made: commit only the maintenance edits, push the
```
blume/*
```
  branch, and open or update a PR against the default branch titled like
```
blume: refresh docs for YYYY-MM-DD
```
  . In the body list sources checked, docs changed, verification commands and results, skipped checks, and residual risk.
- No changes needed: report the PRs and docs areas checked and the no-op result. Do not create a branch, commit, or PR.

建立上下文
- 阅读仓库中的代理/贡献者指南（
```
AGENTS.md
```
  、
```
CLAUDE.md
```
  、贡献文档）并严格遵守。
- 定位文档应用及内容根目录：查看
```
blume.config.ts
```
  中的
```
content.root
```
  配置，找到存放
```
.md
```
  /
```
.mdx
```
  页面、
```
meta.ts
```
  文件的目录，以及包管理器和文档构建命令。
- 若本次运行配置了触发条件、回溯窗口、文档路径、目标分支或PR策略，需严格遵守。仅当提示未明确说明时才使用以下默认值。
复用或创建维护分支
- 若存在来自之前运行的未合并docs-maintenance PR（分支名称以
```
blume/
```
  开头），则检出并更新该分支，而非创建重复分支。
- 否则，基于默认分支创建名为
```
blume/docs-refresh-YYYY-MM-DD
```
  的分支。仅当确定需要编辑时再创建分支。
查找偏差。阅读
```
references/audit-checklist.md
```
获取完整的检查来源及变更判定标准，然后：
- 回顾回溯窗口内（默认：过去7天）合并到默认分支的PR，提取用户可见的变更内容。
- 将这些变更——以及变更日志、发布说明、配置模式、导出API、CLI帮助文档和示例——与文档内容进行对比。
- 仅当被检查页面依赖外部链接时才进行检查；优先使用官方文档和发布说明，而非次要来源。
- 做好记录：检查了哪些内容、上游发生了哪些变更，以及每个编辑（或不编辑）的原因。
更新文档
- 修复过时页面。当页面被添加、重命名或删除时，添加、重命名或移除对应的
```
meta.ts
```
  条目。
- 与现有页面保持一致：前置元数据格式、已使用的Blume组件、代码块样式、根相对内部链接。
验证
- 运行文档构建命令（
```
blume build
```
  或仓库文档中记录的文档QA命令）——该命令会验证前置元数据和重复路由。
- 运行
```
blume validate
```
  检查内部链接和锚点。
- 若仓库约定对文档变更需要执行 lint/格式化/类型检查，则运行相应命令。
- 修复由你的编辑导致的错误；预先存在的错误需单独报告，不要在本次PR中修复。
交付成果
- 已进行变更：仅提交维护性编辑，推送
```
blume/*
```
  分支，并针对默认分支创建或更新PR，标题格式类似
```
blume: refresh docs for YYYY-MM-DD
```
  。PR正文中需列出检查的来源、修改的文档、验证命令及结果、跳过的检查项，以及剩余风险。
- 无需变更：报告检查的PR和文档区域，以及无操作的结果。不要创建分支、提交代码或发起PR。

Resources

参考资源

```
references/audit-checklist.md
```
— the source checklist, edit/skip criteria, and Blume-specific editing guidance. Read it before making docs changes.

```
references/audit-checklist.md
```
—— 完整的检查清单、编辑/跳过判定标准，以及Blume专属编辑指南。在进行文档变更前请务必阅读。