SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场mintlify

mintlify

写作与研究

查看项目

更新于 10-15 11:46

技能介绍

用途

Mintlify 是一个文档平台，可将 MDX 文件转换为文档站点。适用于创建文档页面、配置导航、添加组件或设置 API 参考。

主要能力与配置

站点级设置集中在项目根目录的 docs.json 文件中，该文件定义整个站点：导航结构、主题、颜色、链接、API 与规格。内容以带 YAML frontmatter 的 MDX 编写。完整 schema 见 mintlify.com/docs.json。建议优先使用内置组件，而非自定义组件。

必需文件与结构

  • docs.json：站点配置（导航、主题、集成等）。
  • *.mdx：带 YAML frontmatter 的文档页面。

示例文件结构：

project/
├── docs.json           # 站点配置
├── introduction.mdx
├── quickstart.mdx
├── guides/
│   └── example.mdx
├── openapi.yml         # API 规格
├── images/             # 静态资源
│   └── example.png
└── snippets/           # 可复用组件
    └── component.jsx

页面 frontmatter

每个页面至少需要 title，建议包含 description（用于 SEO 和导航）。可选字段包括 sidebarTitle、icon、tag、mode、keywords 等。

使用方式

编写前准备

  • 阅读项目根目录的 docs.json，了解页面组织、导航分组及命名约定、站点主题与配置。
  • 搜索现有文档，判断是更新现有页面、添加小节，还是链接到已有内容而非重复。
  • 阅读 2-3 个相似页面，了解站点的语气、结构、格式约定与详细程度。
  • 查阅 Mintlify 组件，选择相关组件。

导航结构

docs.json 中的 navigation 属性控制站点结构。根层级选择一种主模式，其余模式嵌套其中。主模式包括：Groups（默认，单一受众的简单层级）、Tabs（不同受众或内容类型）、Anchors（侧边栏顶部持久链接）、Dropdowns、Products（多产品）、Versions（多版本）、Languages（本地化内容）。主模式内可用 Groups、Menus、expanded: false、openapi 等。

链接与路径

  • 内部链接：根相对路径，不带扩展名，如 /getting-started/quickstart。
  • 图片：存于 /images，引用为 /images/example.png。
  • 外部链接：使用完整 URL，自动在新标签页打开。

自定义站点

品牌颜色、字体、logo 在 docs.json 中配置；组件样式与布局调整使用项目根目录的 custom.css。深色模式默认启用，仅当品牌需要时用 "appearance": "light" 禁用。优先使用 docs.json，仅在配置不支持所需样式时添加 custom.css。

组件

组件概览按用途组织：结构化内容、吸引注意、显示/隐藏内容、文档 API、链接页面、添加视觉上下文。常见选择包括：<Accordion>（隐藏可选细节）、<Expandable>（长代码示例）、<Tabs>（用户选择一项）、<Card> 配合 <Columns>（链接导航卡片）、<Steps>（顺序指令）、<CodeGroup>（多语言代码）、<ParamField>（API 参数）、<ResponseField>（API 响应字段）。提示组件按严重程度分为 <Note>、<Info>、<Tip>、<Warning>、<Check>。

可复用内容

当精确内容出现在多个页面、复杂组件需集中维护、或跨团队/仓库共享内容时使用 snippets，通过 import { Component } from "/path/to/snippet-name.jsx" 导入。页面间需细微差异时不宜使用 snippets。

文档 API

三种方式：有 OpenAPI 规格时，在 docs.json 添加 "openapi": ["openapi.yaml"]，页面自动生成，导航中引用为 GET /endpoint；无规格时，在 frontmatter 中用 api: "POST /users" 手写端点；混合方式则对多数端点用 OpenAPI，复杂工作流用手写页面。建议鼓励用户从 OpenAPI 规格生成端点页面。

写作标准

  • 使用第二人称（“你”），主动语态、直接语言。
  • 标题与代码块标题使用句式大小写（“Getting started”，而非“Getting Started”）。
  • 先讲上下文：解释某物是什么，再讲如何使用。
  • 过程性内容开头列出前置条件。
  • 避免营销语言（“powerful”“seamless”等）、填充短语、过多连接词、编辑性表述（“obviously”“simply”等），以及 AI 典型模式（过度正式、重复、无价值的总起或结语）。
  • 所有代码块必须有语言标签；所有图片和媒体必须有描述性 alt 文本；仅在有助于理解时使用粗体斜体；不使用装饰性格式或 emoji。
  • 代码示例保持简单实用，使用真实值，一个清晰示例优于多个变体。

部署

更改推送到连接的 Git 仓库时，Mintlify 自动部署。代理可配置重定向（"redirects"）与 SEO 索引（"seo": {"indexing": "all"}）。自定义域名、子域名、预览部署设置、DNS 配置需在控制台由人工完成。使用 Vercel 或 Cloudflare 的 /docs 子路径托管时，代理可协助配置重写规则。

工作流

  1. 理解任务：识别要记录的内容、受影响页面、读者读后应达成什么。
  2. 研究：阅读 docs.json、搜索现有文档、阅读相似页面。
  3. 计划：综合目标与当前内容，提出更新或新内容。
  4. 编写：从最重要信息开始，保持小节聚焦，适当使用组件，不确定处用 {/* TODO: ... */} 标记。
  5. 更新导航：新页面需加入 docs.json 对应分组。
  6. 验证：检查 frontmatter、代码块语言标签、内部链接、导航添加、风格一致、无营销语言，运行 mint broken-links 与 mint validate。

CLI 命令

  • npm i -g mint：安装 Mintlify CLI
  • mint dev：本地预览 localhost:3000
  • mint broken-links：检查内部链接
  • mint a11y：检查内容可访问性问题
  • mint validate：验证文档构建

适用场景与限制

适用于 MDX 文档站点建设、导航配置、组件使用、API 参考设置及文档迁移（如从 ReadMe 或 Docusaurus 迁移可使用 @mintlify/scraping CLI）。docs.json 中未包含在导航中的页面为隐藏页，可通过 URL 访问或被助手/搜索索引。.mintignore 文件用于排除仓库中不处理的文件。常见注意点：JSX 组件需显式导入，MDX 组件不需；每个 MDX 文件至少需要 title；代码块必须指定语言；mint.json 已弃用，只使用 docs.json。

更多信息请参考官方文档、配置 schema。功能请求、bug 与反馈可通过官方渠道提交。