docs.json 配置。
当你需要完全掌控文档的设计、布局或行为,以匹配现有的设计系统或将文档嵌入到更大的网站中时,这种无头方式会非常有用,同时你仍然可以使用 Mintlify 的发布、搜索、MDX 组件和 AI 功能。
@mintlify/astro 集成会在构建时读取你的 docs.json 配置和 MDX 内容,然后将所有内容处理成 Astro 可渲染的格式。在此基础上构建你自己的布局、组件和样式。
本指南将带你完成使用入门模板设置无头 Mintlify 项目并在本地运行它的过程。
- 拥有一个 Mintlify 账号
- 拥有一个 GitHub 账号
- 安装 Node.js v20.17.0 或更高版本 (推荐使用 LTS 版本)
- 熟悉 Astro
- 一个能运行服务器端代码 (例如 Node.js) 的托管服务商,用于搜索和 AI 助手
1
Create a repository from the starter template
在 GitHub 上打开 mintlify-astro-starter 存储库,并点击 Use this template,在你的账户下创建一个新的存储库。将该存储库克隆到本地环境。
2
Sign up for Mintlify
如果你还没有 Mintlify 账户,请前往 app.mintlify.com/signup 注册。
3
Install the GitHub App
在 Mintlify 控制台的 Git settings 页面中,安装 Mintlify GitHub 应用。如果你已经安装了该应用,请先卸载再重新安装,以便为连接新存储库做好准备。
4
Connect your repository
- 在 Git settings 页面中,选择你通过 starter 模板创建的存储库。
- 启用 Set up as monorepo 开关。
- 将
/docs填写为包含docs.json文件的目录路径。 - 点击 Save changes。
5
Configure environment variables
将你的新存储库克隆到本地后,在项目根目录创建一个 你的子域 (subdomain) 是项目的域名部分,即在控制台 URL 中组织名称之后的那一段。比如,如果你的控制台 URL 是
.env 文件,并填入你的 Mintlify 凭据:.env
https://app.mintlify.com/org-name/domain-name,那么你的子域就是 domain-name。在控制台的 API keys 页面生成一个 AI 助手 API key。该 API key 以 mint_dsc_ 开头。6
Start the dev server
在你克隆的存储库中安装依赖并启动本地开发服务器:你的站点现在将在本地的
http://localhost:4321 上运行。docs/ 目录中的内容,以及用于处理并渲染这些内容的 Mintlify 包。
在 astro.config.mjs 中配置 mintlify() 集成,并指定文档目录的路径:
astro.config.mjs
docsDir 路径读取你的 docs.json 和 MDX 文件,将它们处理为 .mintlify/docs/ 中的内容,供 Astro 的内容集合使用。
Astro 会将你的页面预渲染为静态 HTML。Node.js 适配器负责提供这些页面,并运行搜索和 AI 助手的服务器路由。env schema 将 MINTLIFY_ASSISTANT_KEY 声明为服务器密钥,因此服务器会在运行时读取它,Astro 永远不会将其写入构建输出。
你的文档内容存放在 docs/ 目录中,其结构与其他 Mintlify 项目相同:
@mintlify/astro/helpers 包提供了一些函数,用于从你的 docs.json 中解析导航状态。
resolvePageData():为指定的页面路径返回标签页 (tabs) 、侧边栏导航、页脚链接和页内锚点。unwrapNav():将导航树扁平化为列表,以便用于侧边栏渲染。
入门模板包含搜索和 AI 助手组件,它们通过你站点中的服务器路由连接到 Mintlify 的 API。浏览器从不直接调用 Mintlify 的 API,因此你的 AI 助手 API key 始终保留在你的服务器上。
- Search (搜索):
src/components/SearchBar.tsx中的SearchBar组件将查询发送到/api/search路由。 - Assistant (AI 助手):
src/components/Assistant/中的Assistant组件提供一个 AI 聊天界面,使用你的文档内容回答问题。它将消息发送到/api/assistant路由,该路由以流式方式返回响应。
src/pages/api/ 中,并需要 PUBLIC_MINTLIFY_SUBDOMAIN 和 MINTLIFY_ASSISTANT_KEY 这两个环境变量。每个路由都会将你的 API key 添加到请求中,并将请求转发给 Mintlify。这些路由会设置请求选项 (例如搜索筛选条件) ,因此访问者无法更改它们。
任何能打开你站点的人都可以调用这些路由,每次调用都会消耗你的 AI 助手额度。
入门模板使用 Node.js 适配器,因此你可以将其部署到任何运行 Node.js 服务器的托管服务商。构建站点并启动服务器:
PUBLIC_MINTLIFY_SUBDOMAIN。在托管服务商的环境变量中设置 MINTLIFY_ASSISTANT_KEY。生产服务器不会读取你的 .env 文件。
如需部署到 Vercel、Netlify 或 Cloudflare 等平台,请将 astro.config.mjs 中的 Node.js 适配器替换为该平台的 Astro 适配器。没有适配器时,搜索和 AI 助手将无法工作。
完成项目设置后:
- 将
docs/目录中的示例内容替换为你自己的 MDX 文件和docs.json配置。 - 自定义布局和样式,使其符合你的设计系统。
- 部署你的站点到你的托管服务商。