> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibestrap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 用 Mintlify 部署文档

> 把这个仓库连到 Mintlify，把 docs.your-domain.com 指过去，一小时内上线。

你正在阅读的这个站就是跑在 Mintlify 上的。配置和 MDX 内容都在仓库的 `docs/`
子目录里：`docs/docs.json` 是配置，`docs/<page>.mdx` 是英文内容，`docs/zh/<page>.mdx`
是中文镜像。fork Vibestrap 之后，为你自己的产品复刻这套部署大概是 30 分钟点鼠标 +
一段 DNS 传播等待。

## 前置

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

## 仓库里已经准备好的

Vibestrap 仓库已经为 Mintlify 接好了，你不用从零搭：

* `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](https://mintlify.com/start)。
2. 用你 fork 所在的 GitHub 账号注册。
3. 选 **Hobby** 套餐——免费，且支持自定义域名。

## Step 2：连接仓库

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

## Step 3：配置数据源

在 Mintlify dashboard 进 **Settings → Git settings**，填：

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

保存。Mintlify 会触发首次构建。

## Step 4：验证预览构建

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

构建失败时 dashboard 会展示 Zod / 解析错误并指向具体文件。最常见的原因：

* `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。

`docs.your-product.com` 解析成功后，Mintlify 会把 `*.mintlify.app` 重定向到你的自定义域名。

## Step 6：更新 Vibestrap 的链接

修改 `src/config/site.ts`，让营销应用指向你真实的文档 URL：

```ts theme={null}
links: {
  // ...
  docs: 'https://docs.your-product.com',
}
```

这一处改动会同步到 header、footer、退款页、服务条款——
营销站里所有指向文档的链接都用 `siteConfig.links.docs`。

commit + push。Vercel 重新部署营销站，你的「文档」导航链接现在指向你品牌化的 Mintlify 域名。

## 之后的编辑流程

* 任何 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 不会自动关联。

## 品牌化清单

把占位的 Vibestrap 品牌素材换成你的：

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](https://mintlify.com/docs) —— 完整 Mintlify 参考
* [docs.json schema 参考](https://mintlify.com/docs/organize/settings) —— 每一个配置项
* [Navigation](https://mintlify.com/docs/organize/navigation) —— group / tab /
  anchor / dropdown / language 结构
* [Internationalization](https://mintlify.com/docs/guides/internationalization)
  —— 多语言配置
* [Custom domain](https://mintlify.com/docs/customize/custom-domain) —— DNS
  记录和 SSL 配置
* [Components](https://mintlify.com/docs/components) —— 内置 MDX 组件
  （Tabs、Steps、Callouts、Cards 等）