InsForge 文档写作规范：doc-author Skill 覆盖层与 Mintlify 文档约定实战-二趣网

InsForge 文档写作规范：doc-author Skill 覆盖层与 Mintlify 文档约定实战

【免费下载链接】InsForgeThe all-in-one, open-source backend platform for agentic coding. InsForge gives your coding agent database, auth, storage, compute, hosting, and AI gateway to ship full-stack apps end-to-end.项目地址: https://gitcode.com/GitHub_Trending/in/InsForge

本指南围绕 InsForge 仓库中的文档协作 Skill 覆盖层 INSFORGE.md 展开，讲清 InsForge 在引入 Mintlify 的 doc-author 写作 Skill 之后，如何通过一份本地覆盖文件定义自己的文档规范。读完你会掌握 InsForgedocs/*.mdx的 frontmatter 结构、参数列表写法、SDK 安装片段复用方式，以及一套可以检查"AI 味"的写作自查规则，并能在贡献文档时直接套用。

背景：vendored Skill 与本地覆盖层的分工

InsForge 把 Mintlify 的 doc-author 写作 Skill 原样收录进了仓库，入口是 SKILL.md。这份文件头部有一段明确的 vendored 说明：

上游来源是mintlify/docs，当前收录版本对应一个固定的 commit SHA（877f90193ea1）；
文件正文是上游的逐字拷贝（verbatim copy），禁止手改；
本地约定统一放在旁边的 INSFORGE.md，只在与上游建议冲突时做本地覆盖；
上游文本是权威（"Upstream prose is authoritative"），覆盖层只增不删。

这套"上游 + 本地覆盖"的结构有配套的维护脚本 update-mintlify-skill.sh。脚本每次执行会做四件事：校验上游仓库许可证仍是 MIT（不是则报错退出）、抓取最新 commit SHA、重新下载上游 SKILL.md、重组出带新归属头的新文件。如果本地 attribution 头已经指向最新 SHA 且没有--force，脚本会直接跳过，避免无意义重写。仓库的.claude/skills/README.md也明确要求：不要手改 SKILL.md，InsForge 特有的规则一律写进 INSFORGE.md。

覆盖层共定义了五条约定，下面逐条展开，并给出仓库中的实际证据。

约定一：frontmatter 只保留`title`和`description`

InsForge 的docs/*.mdx页面在 YAML frontmatter 里只用title和description两个键。不要添加icon、sidebarTitle、keywords等 Mintlify 支持的键，除非相邻页面已经在用。

覆盖层给了两个示范：

docs/quickstart.mdx 是常规页面范例，frontmatter 只有三行：

--- title: "CLI setup" sidebarTitle: "CLI setup · Recommended" description: "Install the InsForge CLI, link a project, and generate types from the terminal in about five minutes to start building against your backend." ---

注意它多了一个sidebarTitle，用于侧边栏展示更友好的短标题，这是"相邻页面已经在用"时允许的例外。

docs/sdks/typescript/auth.mdx 是 SDK 参考页风格，严格只有两个键：

--- title: Authentication SDK Reference description: Sign up, sign in, manage sessions, and update user profiles from web and Node.js apps with the InsForge TypeScript SDK auth client and JWT tokens. ---

仓库范围内的搜索结果也印证了这条约定：绝大多数.mdx页面只出现title/description（部分加上sidebarTitle），全仓没有出现keywords或icon键。保持 frontmatter 精简的目的很实际：页面标题和 SEO 描述由内容作者掌控，导航、图标这类展示层配置交给站点框架统一处理，避免每个页面维护一套互不一致的导航元数据。

约定二：不用`<ParamField>`，参数一律写成`### Parameters`下的无序列表

Mintlify 文档系统提供了<ParamField>组件用于渲染参数说明，但 InsForge 全仓对该组件的使用次数为0（在docs/目录下搜索ParamField无任何匹配）。因此参数说明统一用纯 Markdown 无序列表，挂在### Parameters标题之下。

以 docs/sdks/typescript/auth.mdx 的signUp()为例，这是覆盖层指定的规范写法：

### Parameters - `email` (string, required) - User's email address - `password` (string, required) - User's password - `name` (string, optional) - User's display name - `redirectTo` (string, optional) - Used for link-based email verification...

每个条目遵循统一模板：反引号包裹的参数名，括号内标注类型和是否必填，短横线后跟一句功能说明。redirectTo这样的可选参数还写清了使用约束：当verifyEmailMethod设为link时必须提供，且 URL 必须出现在allowedRedirectUrls白名单里。这种写法的好处是纯文本即可渲染，不需要依赖组件库版本，任何 Markdown 渲染器、搜索引擎和阅读 Agent 都能稳定解析。

参数说明之外，方法返回值也用带注释的 TypeScript 类型块给出，例如signUp()的返回值结构里明确标注了requireEmailVerification为 true 时accessToken会是 null，并用<Note>组件提示开发者如何处理邮箱验证流程。这就是"参数列表 + 类型注释 + 行为提示"的完整组合，覆盖层要求的所有页面照此模式写作。

约定三：SDK 安装代码统一 import 共享片段，不内联

任何展示 SDK 安装步骤的页面，都必须 import 共享片段 docs/snippets/sdk-installation.mdx，而不是在页面里复制粘贴安装命令。

规范写法：

import Installation from '/snippets/sdk-installation.mdx'; <Installation />

共享片段的内容用<CodeGroup>同时给出三种包管理器的命令，并附上初始化示例：

npm install @insforge/sdk@latest yarn add @insforge/sdk@latest pnpm add @insforge/sdk@latest

import { createClient } from '@insforge/sdk'; const insforge = createClient({ baseUrl: 'https://your-app.insforge.app', anonKey: 'your-anon-key' // Optional: for public/unauthenticated requests });

片段末尾还说明了 anonKey 的获取方式：用npx @insforge/cli secrets get ANON_KEY，或在仪表盘的 Install 页打开 API Keys。

实际使用该片段的位置包括 docs/sdks/typescript/auth.mdx、docs/sdks/typescript/overview.mdx、docs/examples/framework-guides/react.mdx 等多处。这套机制的价值在于单点维护：SDK 包名、安装命令或初始化参数一旦变化，只改片段一处，全站所有引用页面同步更新，杜绝各页安装代码漂移。

约定四：语气用第二人称祈使句

覆盖层要求文档以 "you" 称呼读者，动词用祈使语气。最典型的示范是 docs/quickstart.mdx，整篇从 "Create your project"、"Link the CLI" 到 "Verify installation"，全部是直接可执行的指令：

npx @insforge/cli link --project-id <your-project-id>

指令后面紧跟一句行为解释（"Running throughnpxkeeps the CLI out of your global install path"），读者既知道怎么执行，也知道执行后发生了什么。写作时保持"前置条件放开头、步骤用祈使句、先讲是什么再讲怎么做"的节奏。

约定五：写得像人，不写得像 AI

覆盖层专列一节防"机器味"，依据是 Wikipedia 关于 AI 写作特征的总结（来自仓库的 humanizer skill）。需要主动清除的 AI 痕迹包括六类：

破折号（em dash）：不在插入语或强调处使用—，改用逗号、句号、冒号或括号。
三段排比（rule of three）：不要自动凑"快速、可靠、可扩展"这类三连，只点名真正重要的那一个。
否定式平行（"不只是 X，还是 Y"）：直接陈述正面结论，不要绕。
虚高措辞（"扮演了关键角色"、"凸显了重要性"这类空话）。
模糊归因（"研究表明"、"被广泛认为"）：要么点名出处，要么删掉这句话。
AI 高频词黑名单：delve、leverage、utilize、underscore、foster、realm、landscape、tapestry、seamless、robust、pivotal 一律换成平实词。

最后一句自查标准很直白："读一遍，如果读起来像新闻稿或学期论文，就把它压平。"（If it sounds like a press release or a term paper, flatten it.）这份指南本身也应按此执行：比如本文描述共享片段机制时说"单点维护、一处变更全站同步"，直接陈述收益，不堆形容词。

写作工作流：验证、匹配、标注不确定

覆盖层虽短，但它挂靠的上游 SKILL.md 给出了完整的写作流程，两者配合使用：

只写能验证的内容：无法从代码库或明确的用户输入确认的东西，不要写进文档，宁可留 TODO 注释。例如{/* TODO: Verify the default timeout value - couldn't find in codebase */}。
动手前读周边内容：先读 2 到 3 个相似页面，摸清语气、结构和组件用法，一致性优先于个人偏好。
匹配现有模式：不要发明新写法，### Parameters无序列表示例、<Installation />import 片段、<Note>/<Warning>/<Tip>/<Info>提示组件都是现成模式。
明确标注不确定性：默认值拿不准、边界情况没测过、配置项不确定，都用 TODO 注释标出。
发布前自查：所有代码块带语言标签、frontmatter 齐全、内部链接正确、无营销词与废话、新页面登记进导航。

维护与同步：vendored 内容的更新机制

SKILL.md 的更新不靠手改，而是执行：

scripts/update-mintlify-skill.sh

脚本的防漂移设计值得注意：它通过 GitHub API 校验上游许可证，若 Mintlify 不再以 MIT 发布，脚本会在更新前大声报错并要求人工评估，防止无意中引入许可证冲突的内容。仓库的 CI 也会在lint-and-format.yml中运行scripts/sync-skills.sh --check，用于检测另一组insforge-devSkill 在三套 Agent 目录（.claude/、.codex/、.agents/）中的拷贝是否漂移。

对贡献者而言，维护边界很清晰：SKILL.md 是 vendored 上游文件的逐字拷贝，只能通过脚本更新；INSFORGE.md 是 InsForge 自己的覆盖层，是存放本地规范的位置；docs/*.mdx页面则按覆盖层五条约定写作。三层各司其职，既保留了上游最佳实践，又让项目拥有自己的文档风格。

总结

INSFORGE.md 用极短的篇幅定义了 InsForge 文档的可执行标准：frontmatter 只保留title和description、参数用### Parameters无序列表、SDK 安装一律 import 共享片段、第二人称祈使语气、以及一整套去除 AI 痕迹的写作自查规则。每条约定都在docs/目录里有真实页面作为范例，也都有对应的维护脚本和 CI 检查兜底。无论你是给 InsForge 提交文档贡献，还是在自己的项目里借鉴这套 vendored Skill 模式，这份覆盖层都是一个可以直接复用的模板。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析