用 Mintlify 部署文档

​

前置

• 已 fork 到你 GitHub 账户的 vibestrap 仓库。
• 你拥有的域名（比如 your-product.com）—— 文档将放在 docs.your-product.com。
• 你 DNS 服务商的 dashboard 访问权限。

​

仓库里已经准备好的

• docs/docs.json —— Mintlify 配置文件。定义了 name、theme、colors、 navigation、footer、navbar 链接、SEO 默认值。
• docs/*.mdx 与 docs/<group>/*.mdx —— 36 篇英文页，分到 9 个导航分组。
• docs/zh/... —— 每一篇英文页的中文镜像。
• docs/logo/{light,dark}.svg 与 docs/favicon.svg —— 占位品牌素材， 你应该换成自己的。

​

Step 1：注册 Mintlify

1. 打开 mintlify.com/start。
2. 用你 fork 所在的 GitHub 账号注册。
3. 选 Hobby 套餐——免费，且支持自定义域名。

​

Step 2：连接仓库

1. Mintlify dashboard 里点 Connect GitHub。
2. 提示安装 Mintlify GitHub App 时同意。范围只给你 fork 的 vibestrap 就行（以后可以再加）。
3. 选中那个仓库。

​

Step 3：配置数据源

• Repository：<your-org>/vibestrap
• Branch：main
• Subdirectory：docs ← 这一项关键。Mintlify 会把 docs/docs.json 当配置读，所有页面 slug 都按这个子目录解析。

​

Step 4：验证预览构建

1. 在 dashboard 的 Overview → Deployments 看构建状态。首次构建大约 1–2 分钟。
2. 完成后点预览 URL，类似 your-org.mintlify.app。
3. 打开。你应该看到完整的 vibestrap 文档站，含侧边栏、语言切换、搜索框。

• docs/docs.json → navigation 列出的页在硬盘上不存在。
• MDX 里写了 <https://example.com> autolink（Mintlify 拒绝—— 改成 [example.com](https://example.com)）。
• frontmatter 缺 title 或 description。

​

Step 5：自定义域名

1. Mintlify dashboard → Settings → Custom domain。
2. 填 docs.your-product.com。
3. Mintlify 会显示需要添加的 DNS 记录，类似：
   Type   Host   Value
   CNAME  docs   cname.mintlify-dns.com.
   
4. 在你的 DNS 服务商（Cloudflare、Vercel DNS、Namecheap、Route53 等）加这条 CNAME。
5. 等。传播一般 1–24 小时。DNS 解析成功后 Mintlify 会自动通过 Let’s Encrypt 申请 SSL。

​

Step 6：更新 vibestrap 的链接

links: {
  // ...
  docs: 'https://docs.your-product.com',
}

​

之后的编辑流程

• 任何 push 到 main 且改动了 docs/ 或 docs/docs.json 的提交，Mintlify 会自动重新部署， 我们这边不需要额外的 CI 步骤。
• 本地预览：仓库根跑 pnpm dlx mintlify dev。CLI 读 docs/docs.json 在 localhost:3000 上跑——和 pnpm dev 抢同一个端口，不要同时跑。
• 双语内容：任何新页都要在 docs/<path>.mdx 和 docs/zh/<path>.mdx 都建一份， 并把 slug 加到 docs/docs.json 的 两个语言分组。Mintlify 不会自动关联。

​

品牌化清单

1. Logo：改 docs/logo/light.svg 和 docs/logo/dark.svg。保留 220×48 viewBox 让 navbar 高度一致。
2. Favicon：替换 docs/favicon.svg。
3. 主色：改 docs/docs.json → colors.primary（hex）。
4. 站名：改 docs/docs.json → name。
5. Navbar 链接 + 主 CTA：改 docs/docs.json → navbar。
6. Footer：改 docs/docs.json → footer.socials 和 footer.links。
7. SEO：改 docs/docs.json → seo.metatags。

​

常见坑

1. Source directory 错了：dashboard 显示「no pages found」时， 确认 Source directory 是 docs，不是 / 或 content/docs。
2. 页在 docs/ 但不在 docs/docs.json 里：页能渲染但成「孤儿」（侧边栏没条目、 搜索搜不到）。把它加到 docs/docs.json → navigation.languages 的对应语言分组。
3. 页在 docs/docs.json 但不在 docs/：构建失败。要么建文件、要么从 navigation 删掉。
4. 自定义域名 TLS pending：加完 CNAME 后 Mintlify 会显示「TLS provisioning」 最多 24 小时。超时还在 pending 的话，重新检查 CNAME 是否完全匹配 （没有多余的点、没有尾部斜杠，目标是 cname.mintlify-dns.com.）。
5. 同一个 group 里混中英文页：Mintlify 严格按 navigation.languages[i].groups 分组——en/* 只放在 en 语言项下，zh/* 只放在 zh 项下。跨语言链接用普通 markdown 链接，不要靠导航。

​

官方文档

• mintlify.com/docs —— 完整 Mintlify 参考
• docs.json schema 参考 —— 每一个配置项
• Navigation —— group / tab / anchor / dropdown / language 结构
• Internationalization —— 多语言配置
• Custom domain —— DNS 记录和 SSL 配置
• Components —— 内置 MDX 组件 （Tabs、Steps、Callouts、Cards 等）