为什么选择 Canofold
Canofold 面向希望用源码管理知识内容、又不想维护独立文档前端的团队。Markdown 和 MDX 是可版本管理的源；一次构建把同一份源展开成网站、搜索索引和 AI-ready 知识输出。
从交付形态看，Canofold 同时提供静态文档生成器和可独立使用的 Markdown SDK；平台本身不局限于技术文档，也适合产品说明、团队知识库和操作手册。
知识留在现有工作流里
文档可以和代码、产品规范、操作手册或其他项目资产放在同一个仓库，也可以拥有独立仓库。分支、评审、CI 和发布记录继续由现有 Git 工作流管理。
接入已有仓库时，canofold init 只补齐配置和必要文件，不移动已有内容，也不要求修改业务源码。团队不必为了文档再维护一个单独的前端项目。
静态优先，部署边界简单
Canofold 在构建阶段完成页面渲染、导航、搜索索引和 AI 数据生成。生产环境只需要托管静态文件，不依赖 Canofold 服务、Node.js 服务器或数据库。
静态交付降低了运行时维护成本，也让缓存、回滚和访问控制留在托管平台中处理。私有知识库仍需由托管平台保护整个输出目录。
一份源，服务多种入口
Canofold 只解析一份 Markdown 和 MDX。页面结构、导航、搜索文本、多语言与版本路由、Markdown 镜像、llms.txt 和分片语料都从这份源展开。
网站、站内搜索和 AI 工具因此读取相同的标题、正文与元数据。内容修订只需完成一次，不必维护多份同步脚本。
CLI 与 Markdown SDK 分层
需要完整知识站点时使用 canofold CLI；需要在现有 React、SSR 或静态生成流程中渲染内容时，直接使用 @canofold/markdown SDK。两者共享内容语义和主题契约，但可以独立接入。
@canofold/plugins 提供数学、图表、链接处理、阅读时长和 Pagefind 等可选能力。项目只安装当前需要的部分。
扩展职责有明确边界
| 增加 Markdown 语法、数学或图表 | Markdown 插件 |
| 修改整个站点的构建规则或生成额外文件 | Extension |
| 替换索引和查询实现 | Search Provider |
| 调整整个站点视觉 | 官方或第三方主题包、项目 CSS |
| 定制独立 Markdown 渲染 | React components、classNames 与 slots |
这些入口分别处理内容、构建、搜索和展示，避免一个插件同时控制整条构建链。
什么时候适合使用
以下情况适合选择 Canofold：
- 知识内容以 Markdown 或 MDX 维护，并需要进入 Git 评审流程。
- 需要多语言、多版本、站内搜索或 AI-ready 知识输出。
- 希望生成结果可部署到任意静态托管平台。
- 需要完整站点，同时也希望保留独立使用 Markdown SDK 的能力。
如果团队依赖浏览器内多人协作编辑、逐页权限、审批评论或动态内容 API，在线 CMS 或托管知识库会更合适。Canofold 也不应执行来源不可信的 MDX、本地组件或构建扩展。
用一个小范围试点验证
先在现有仓库中选择几篇真实文档，完成以下检查：
- 安装 Canofold并初始化配置。
- 接入三到五篇包含链接、代码和静态资源的内容。
- 运行
canofold check、canofold build和canofold preview。 - 检查导航、搜索、多语言或版本路由，以及生成的 AI 输出。
试点通过后，再把其余知识内容接入同一结构。具体步骤见快速开始。