跳转到主要内容
Mintlify 的无头模式让你在使用 Mintlify 管理内容的同时,掌控文档的外观和行为。你无需使用 Mintlify 托管的前端,而是可以用 Astro 构建自己的自定义前端,并按你想要的任何方式渲染 MDX 内容和 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

  1. 在 Git settings 页面中,选择你通过 starter 模板创建的存储库。
  2. 启用 Set up as monorepo 开关。
  3. 将 /docs 填写为包含 docs.json 文件的目录路径。
  4. 点击 Save changes。
5

Configure environment variables

将你的新存储库克隆到本地后,在项目根目录创建一个 .env 文件,并填入你的 Mintlify 凭据:
.env
你的子域 (subdomain) 是项目的域名部分,即在控制台 URL 中组织名称之后的那一段。比如,如果你的控制台 URL 是 https://app.mintlify.com/org-name/domain-name,那么你的子域就是 domain-name。在控制台的 API keys 页面生成一个 AI 助手 API key。该 API key 以 mint_dsc_ 开头。
不要为 MINTLIFY_ASSISTANT_KEY 添加 PUBLIC_ 前缀。Astro 会将 PUBLIC_ 变量打包进客户端代码。任何从你的站点复制该密钥的人都可以使用你的 AI 助手额度,并读取你项目中受保护的页面。
6

Start the dev server

在你克隆的存储库中安装依赖并启动本地开发服务器:
你的站点现在将在本地的 http://localhost:4321 上运行。

工作原理

该集成连接了三个部分:Astro 构建系统、docs/ 目录中的内容,以及用于处理并渲染这些内容的 Mintlify 包。

Astro 配置

在 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 项目相同:
MDX 文件使用标准 Mintlify frontmatter,并且可以在无需导入它们的情况下使用 Mintlify 组件。

路由与导航

使用一个 catch-all 路由来渲染每个 MDX 页面。@mintlify/astro/helpers 包提供了一些函数,用于从你的 docs.json 中解析导航状态。
  • resolvePageData():为指定的页面路径返回标签页 (tabs) 、侧边栏导航、页脚链接和页内锚点。
  • unwrapNav():将导航树扁平化为列表,以便用于侧边栏渲染。

布局和样式

你可以完全掌控呈现层。起始模板包含布局、侧边栏、目录以及使用 Tailwind CSS 构建的样式,但你可以将其中任何部分替换为你自己的实现。 需要自定义的关键文件:

连接搜索和 AI 助手

入门模板包含搜索和 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 助手将无法工作。

后续步骤

完成项目设置后:
  1. 将 docs/ 目录中的示例内容替换为你自己的 MDX 文件和 docs.json 配置。
  2. 自定义布局和样式,使其符合你的设计系统。
  3. 部署你的站点到你的托管服务商。