Formbricks 文档本地开发与贡献指南：基于 Mintlify 的 docs 工作流解析

Formbricks 是一个开源的体验管理（Experience Management）平台，其完整文档站点托管在仓库的 docs/ 目录下，并使用 Mintlify 构建与渲染。本文面向希望在本地预览、编写并贡献 Formbricks 文档的开发者，完整讲解从环境准备、本地启动、页面验证到提交流程的每一步操作，并结合仓库中 docs/docs.json 配置与真实文档页面，说明 Mintlify 站点的组织方式与常见故障排查方法。

文档站点的技术底座：Mintlify 与仓库结构

Formbricks 的文档不是静态生成的独立站点，而是与主代码库共存于同一仓库中。从仓库根目录看，docs/ 目录即文档源码的所在地，其中 docs/docs.json 是 Mintlify 的核心配置文件，定义了站点的外观主题、导航结构、API 文档挂载与历史重定向规则；docs/README.md 则是面向文档贡献者的速查入口。

formbricks/
├── docs/                  # Mintlify 文档源码
│   ├── README.md          # 本文所依托的本地开发与贡献说明
│   ├── docs.json          # 站点导航、主题、重定向等全局配置
│   ├── formbricks.js      # 文档站点自身的反馈调查脚本（基于 Formbricks SDK）
│   ├── platform/          # 平台总览与功能文档
│   ├── surveys/           # 问卷功能文档
│   ├── self-hosting/      # 自托管文档
│   ├── api-reference/     # OpenAPI 规范与 API 参考
│   └── development/       # 面向代码贡献者的开发文档
└── ...                    # 其余为应用代码（apps/web 等）

几点值得注意的细节：

• docs/docs.json 中 navigation.tabs 将文档划分为 Platform、Surveys (Ask)、Unify Feedback (Analyze)、Workflows (Act)、Self Hosting、Development、MCP、API v1/v2/v3 Reference 等多个标签页，并声明了 openapi 目录挂载点（如 /api-reference/openapi.json、/api-v2-reference/openapi.yml），这些页面会在 Mintlify 渲染时自动生成 API 参考。
• 该配置还包含大量 redirects 规则，将旧版文档路径（如 /docs/xm-and-surveys/...、/docs/developer-docs/...）映射到当前路径，保证历史链接不失效。这也解释了本地预览时「404 页会重定向」的行为。
• docs/formbricks.js 展示了文档站点本身也在使用 Formbricks 的 JS SDK 收集页面反馈——它通过 window.formbricks.setup({ workspaceId, appUrl }) 初始化，是 Formbricks「文档即用例」的直观体现。

本地开发：三步启动文档站点

在撰写或修改任何文档页面前，先在本地把站点跑起来。整个过程只需要三组命令。

1. 安装 Mintlify CLI

Mintlify 提供全局安装的 mint 命令：

npm i -g mint

安装后建议确认版本可用：

mint --version

mint 是当前推荐的 Mintlify CLI 包名。如果机器上同时装有旧版的 mintlify 包，二者可能互相干扰，需卸载旧包（见下文 Troubleshooting 一节）。

2. 获取仓库并进入 docs 目录

git clone https://github.com/formbricks/formbricks.git
cd formbricks/docs

文档源码与主项目共用同一仓库，因此无需单独安装任何 npm 依赖——Mintlify 直接读取 docs.json 与各 .mdx 文件即可渲染。若你只需要阅读和编写文档，这比搭建整个 Formbricks 应用（需要 Node.js、pnpm、Docker 与 PostgreSQL）轻量得多。

3. 启动本地开发服务器

mint dev

站点启动后默认监听 http://localhost:3000，浏览器打开即可预览。Mintlify 支持热更新：修改 .mdx 文件后刷新页面即可看到变更，无需重启服务。

页面 404 的判定逻辑：docs.json 才是「根」

本地开发最常见的困惑是「明明文件存在，却访问不到」。Troubleshooting 一节给出了明确指引：

If a page loads as a 404, ensure you're in the docs folder with the docs.json file

Mintlify 以 docs.json 所在的目录作为文档根目录。如果启动命令不在包含该文件的目录下执行，或者 docs.json 缺失/损坏，站点的导航结构将无法解析，页面自然表现为 404。因此排查顺序是：

1. 确认当前 shell 工作目录为 formbricks/docs；
2. 确认 docs/docs.json 存在且为合法 JSON（可用 jq . docs.json >/dev/null 快速校验）；
3. 确认要访问的页面路径已被 navigation 声明（Mintlify 对未声明路径的页面不会纳入导航）。

另外，docs/docs.json 中设置了 "errors": { "404": { "redirect": true } }，意味着本地站点对未知路径会尝试按重定向规则解析，符合预期而非故障。

编写与贡献：分支、修改、提交 PR

贡献流程与常规开源项目一致，docs/README.md 将其归纳为三步：

1. 创建分支：基于主仓库 main 拉出一个新分支，用于隔离你的文档改动；

   git checkout -b docs/my-improvement
   

2. 修改文档：在 docs/ 下编辑或新增 .mdx 页面。Formbricks 文档页面使用带 frontmatter 的 MDX 格式，例如 docs/platform/introduction.mdx 顶部就包含 title、description、icon 字段，其中 description 会被 Mintlify 用于 SEO 与索引，建议每个新页面都认真填写；

3. 提交 Pull Request：推送分支后向主仓库发起 PR，等待维护者评审。

仓库的 CONTRIBUTING.md 进一步说明：对于 bug 报告请走 issue 模板，对于新功能/文档改进请创建带 Enhancement 标签的 issue；目前社区代码贡献仅在例外情况下被接受，而文档类改进是被明确鼓励的参与方式。因此，对大多数贡献者而言，从文档入手是参与 Formbricks 最实际的路径。

扩展阅读：文档内容的组织脉络

docs/README.md 本身只有 38 行，其价值在于指向整套文档体系的入口。为了让本地编写时心中有数，这里给出仓库中几个代表性文档的路径与主题，均与 Mintlify 站点导航一一对应：

文档主题	仓库路径	说明
平台总览	docs/platform/introduction.mdx	Ask / Analyze / Act 三段式体验管理套件介绍
自托管入门	docs/self-hosting/overview.mdx	系统要求、Docker / K8s 部署选项、授权对比
Docker 部署	docs/self-hosting/setup/docker.mdx	完整的 Compose 快速启动与排障流程
开发文档入口	docs/development/overview.mdx	代码库架构（Technical Handbook）与工程规范（Standards）
开源许可说明	docs/platform/open-source.mdx	AGPLv3 核心与 Enterprise Edition 的区别

这些页面使用的 MDX 语法（如 <CardGroup>、<Card>、<Info>、<Warning>、<Note> 组件）都是 Mintlify 的内置能力，编写新页面时可以参考现有文件保持风格一致。

常见问题排查

综合 docs/README.md 的 Troubleshooting 与 docs/self-hosting/setup/docker.mdx 的 Debug 思路，整理以下高频问题与解法：

症状	可能原因	处理方式
mint dev 无法启动	CLI 版本过旧，或与旧版 mintlify 冲突	先执行 mint update 升级；若同时装有 mintlify，卸载旧包后重试
页面 404	未在包含 docs.json 的 docs 目录下启动，或路径未被导航声明	确认工作目录与 docs/docs.json 存在，检查页面路径是否在 navigation 中
样式/布局异常	本地缓存或 CLI 版本不一致	mint update 后重启 mint dev
其他问题	贡献流程、PR 规范疑问	查阅 CONTRIBUTING.md，或到 GitHub Discussions 提问

需要提醒的是：本文描述的所有操作均只涉及「查看、运行与配置」文档站点，不要求也不建议修改仓库中的任何文件作为使用前提；所有改动都应遵循标准的 fork + PR 流程提交回上游。

小结

• Formbricks 文档基于 Mintlify 构建，源码位于仓库 docs/ 目录，docs/docs.json 决定站点的导航、重定向与 API 挂载。
• 本地开发只需 npm i -g mint → cd formbricks/docs → mint dev 三步，默认地址 http://localhost:3000。
• 遇到 404 时优先确认是否身处含 docs.json 的文档根目录；遇到 CLI 异常时优先 mint update。
• 文档贡献走「建分支 → 改 MDX → 提 PR」的标准流程，是参与 Formbricks 开源社区最轻量的方式。