Clarify：把 Mintlify 式文档站体验带回 Git 仓库，用 MDX/OpenAPI 构建静态站点

Clarify（github.com/taicode-labs/clarify，AGPL-3.0）把 MDX、OpenAPI 3.0/3.1 与项目内容渲染成快速、多语言、可自托管的开发者文档站。核心理念是：内容留在 Git、本地构建、静态可移植输出、渲染器属于代码库一部分，团队能在自己掌控的部署上发布而不被托管平台锁定。README 明确说这是给想要 Mintlify 那类现代文档体验、但更在意源码/渲染/部署掌控权的团队的选择。项目提供中英双语 README。

主要特性

• MDX-first 写作：Markdown + React 组件，内置 callout/cards/code 组件。
• OpenAPI 渲染：内建可导航的 API reference，并能在 MDX 引导页内嵌单个 operation。
• 项目级变量：集中管理站点级内容变量。
• 静态站点生成：每个 route 产出 HTML，支持客户端导航与 route-prefix。
• 国际化：按 locale 目录组织内容，可配置 fallback。
• 全文检索：在 dev/build 中生成并服务 Pagefind 索引，返回当前语言结果并带高亮摘录。
• typed clarify.ts：类型安全的 tab/sidebar/navbar/footer/theme token/route prefix/favicon/logo/metadata 配置。
• 定制渲染器：React 19 + Tailwind CSS 4，提供 presets/color token/radius token/layout width。
• AI-ready 输出：生成 raw .md/.openapi.* 制品、稳定 raw-content 链接与 llms.txt。
• 插件化 pipeline：支持扩展 route resolution、虚拟模块、构建完成钩子。

快速开始

npx @clarify-labs/cli init my-docs
cd my-docs
npm install
npm run dev

生产构建：

npm run build

生成 output/ 目录，可部署到任意静态主机。新增或编辑页面都在 source/ 下：index.mdx、guides/writing-content.mdx、api.openapi.json。核心命令是 npx clarify dev / npx clarify build，导航、OpenAPI、主题、国际化配置集中在 clarify.ts。

VSCode 扩展

从 Releases 下载 .vsix 后安装：

code --install-extension clarify-vscode-extension-*.vsix

也可以用 UI 安装。扩展检测到工作区存在 clarify.ts 即自动识别项目；编辑 MDX、OpenAPI 或配置时热更新实时预览，并自动解析当前文件对应的 route。通过命令面板执行 Clarify: Stop Dev Server 可停止本地服务。

与 Mintlify 的对照

按 README 的比较，两者在处理 OpenAPI 上都做得足够强。其余差异主要落在 ownership：

Clarify 不是 Mintlify 克隆，而是给喜欢 Mintlify 那套体验、但想要更多 ownership 的团队准备的选择。

适用场景与内容类型

Clarify 适合这些使用方式：

• 把零散 Markdown 文件夹换成结构清晰的文档站。
• 在同一个仓库里同时维护产品文档和 API 文档。
• 让文档 review 走普通 PR 流程。
• 需要自托管，同时保留现代的导航、切换与搜索体验。
• 内容既要给人读，也要给 AI agent 读（通过 llms.txt 和 raw content 输出）。

内容类型包括：开发者文档、从 OpenAPI 生成的 API reference、内部工程手册、多语言 help center / dev portal、AI 可读知识库。

取舍与边界

• AGPL-3.0 的“只读”语义需要按你的分发方式评估。
• 基于 Tailwind/React 的渲染器意味着前端技术栈相对固定。
• 项目文档未给更多运行时依赖细节；超大规模站点的性能也未经实测。
• 如果只想要开箱即用的托管，Mintlify 仍是更短的路径；Clarify 更适合对源码、渲染与部署路径都要掌控的团队。