维护产品文档

文档在哪里

面向使用者的公开手册位于 content/docs/*.md。docs/ 中的内部工程记录、审查附件和上游归档不会自动公开；维护者应有意选择公开的内容。

手册与博客在同一个 Astro 应用中构建，部署入口为 /docs/。不需要第二个 Node 应用、主题或托管账户。

新增章节

文件名使用小写连字符，成为稳定路由；overview.md 是唯一首页 /docs/。

title: 新章节
description: 一句话说明读者能在这里完成什么。
section: extend
order: 40

把以上字段写入文件顶部的 YAML front matter。仅接受 title、description、section 与 order；未知字段和同组重复 order 会在构建时失败。

导航按分组固定顺序、组内 order 升序生成。修改已有文件名会改变 URL，应谨慎处理旧链接。

正文和链接

布局输出 h1，正文只使用 h2–h4。沿用博客 Markdown 安全策略、Shiki 代码块、表格容器与共享 TOC。不要将任意 HTML 或 MDX 执行代码加入手册。

## 发布流程

先阅读[快速开始](./quick-start.md)。
也可直接定位[图片迁移](./publishing.md#图片与依赖迁移)。

同目录 Markdown 链接被转换为包含部署 base 和尾斜杠的网页链接，保留锚点。不要链接到内部 docs/ 文件或用 ../ 跳出公开手册。HTTPS 外部链接保持不变。

搜索与 SEO

文档沿用 Spotlight，但只加载 docs-pagefind 索引；博客继续加载 pagefind，两者不会混搜。导航、上一篇/下一篇和页脚不作为文档正文索引。

Pagefind 对部分中文短词的分词会与浏览器不同。中文查询无结果时，文档搜索按需读取公开正文的原词索引，支持空格分隔多个关键词、优先显示标题命中；不提供拼写纠错或模糊匹配。兜底文件的 gzip 大小限制为 100 KiB，超过预算需要拆分索引，不能移除门禁。

每个文档有独立 title、description、canonical、Open Graph 与 TechArticle JSON-LD，并加入 sitemap。它不进入文章 RSS、标签与创作热力图。

发布前检查

inkstack build
inkstack check --full
pnpm test:e2e

检查新增文档在导航、翻页、sitemap 和文档搜索中存在；核验所有链接和锚点。在宽屏、1024 px 和 390 px 视口验证导航与无页面级横向溢出。截图基线仅在固定 Linux Playwright 环境中审核更新，不在 CI 自动接受。

功能行为改变时同步修改相应产品章节。内部设计决策仍保留在 docs/adr/，公开手册避免泄漏账号、令牌、本机路径或未公开文章。