其他
构建或维护 Mintlify 文档站点时：创建和修改…
使用 Mintlify 构建文档站点时，按参考文件、配置、组件、CLI 命令和写作规范执行创建与维护任务。
🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）
GDI C 35/100
进化评分（GDI）
综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」
内在质量 55/100 ×0.35
使用度 0/100 ×0.30
口碑 50/100 ×0.20
新鲜度 38/100 ×0.15
适用场景
构建或维护 Mintlify 文档站点时特定
解决思路
- 当任务涉及添加或修改组件时，读 reference/components.md，覆盖 callouts、cards、steps、tabs、accordions、code groups、fields、frames、icons、tooltips、badges、trees、mermaid、panels、prompts、colors、tiles、updates、views。
- 当任务涉及更改 docs.json 设置时，读 reference/configuration.md，覆盖 theme、colors、logo、fonts、appearance、navbar、footer、banner、redirects、SEO、integrations、API config；也覆盖 snippets、hidden pages、.mintignore、custom CSS/JS 和完整 frontmatter 字段表。
- 当任务涉及修改站点导航结构时，读 reference/navigation.md，覆盖 groups、tabs、anchors、dropdowns、products、versions、languages、OpenAPI in nav。
- 当任务涉及设置 API 文档时，读 reference/api-docs.md，覆盖 OpenAPI、AsyncAPI、MDX manual API pages、extensions、playground config。
- 开始前先读项目 docs.json 文件，它定义站点导航、主题、颜色和配置。
- 创建新页面前搜索现有内容，确定应更新已有页面、添加章节还是链接到现有内容，而非重复。
- 阅读 2-3 个相似页面，匹配站点口吻、结构和格式。
- 使用 MDX 文件（.mdx 或 .md）加 YAML frontmatter。
- 遵循项目结构：docs.json 是站点配置且必需；index.mdx、quickstart.mdx、guides/example.mdx；openapi.yml 是可选 API 规范；images/ 存静态资源；snippets/ 存可复用组件。
- 文件命名匹配目录中现有模式。
- 如果无现有文件或命名模式混合，使用 kebab-case，如 getting-started.mdx。
- 将新页面加入 docs.json 导航，否则不会出现在侧边栏。
- 内部链接使用根相对路径且不带文件扩展名，如 /getting-started/quickstart。
- 内部页面不要使用相对路径（../）或绝对 URL。
- 图片存到 images/ 目录，用根相对路径引用，所有图片需要描述性 alt 文本，如 。
- 每个页面 frontmatter 必须包含 title；为 SEO 包含 description 和 keywords。
- 设置 title 为导航和浏览器标签页中的页面标题，必填。
- 设置 description 为 SEO 简短描述，显示在标题下。
- 设置 sidebarTitle 为侧边栏导航短标题。
- 设置 icon 为 Lucide、Font Awesome 或 Tabler 图标名；也可接受 URL 或文件路径。
- 设置 tag 为侧边栏页面标题旁标签，如 NEW。
- 设置 hidden 为 boolean 从侧边栏移除；页面仍可通过 URL 访问。
- 设置 mode 为页面布局：default、wide、custom、frame、center。
- 设置 keywords 为内部搜索和 SEO 的搜索词数组。
- 设置 api 为交互式 playground 的 API endpoint，如 POST /users。
- 设置 openapi 为 OpenAPI endpoint reference，如 GET /endpoint。
- 使用 callouts：<Note> 补充信息，可跳过；<Info> 有用上下文如权限或前置条件；<Tip> 推荐或最佳实践；<Warning> 潜在破坏性操作或重要注意事项；<Check> 成功确认或完成状态；<Danger> 数据丢失或破坏性变更的关键警告。
- 使用 <Steps> 和 <Step> 组织步骤，每个 Step 设置 title。
- 使用 <Tabs> 和 <Tab> 展示多包管理器命令等，每个 Tab 设置 title。
- 使用 <CodeGroup> 组合代码示例，给代码块加语言和文件名，如 javascript example.js 与 python example.py。
- 使用 <Columns> 和 <Card> 排列卡片或内容为网格，cols 接受 1-4；Card 可设置 title、icon、href。
- 使用 <AccordionGroup> 和 <Accordion> 创建可折叠区块，每个 Accordion 设置 title。
- 用 npm i -g mint 安装 CLI。
- 本地开发：运行 mint dev 在 localhost:3000 启动本地预览；--no-open 跳过打开浏览器；--groups <names> 模拟用户组。
- 严格构建验证：运行 mint validate；有警告或错误时以非零退出。
- 导出静态站点 zip 用于气隙部署：运行 mint export；--output <file> 设置输出路径，默认 export.zip。
- 检查坏内部链接：运行 mint broken-links；--check-anchors 验证 # 锚点；--check-external 检查外部 URL；--check-snippets 检查 <Snippet> 组件内链接。
- 可访问性检查：运行 mint a11y 检查 alt 文本、颜色对比度；--skip-contrast 或 --skip-alt-text 缩小范围。
- 分析 KPI：运行 mint analytics stats 获取 views、visitors、searches；选项 --subdomain、--from、--to、--format（table/plain/json/graph）、--agents/--humans 过滤流量、--page 过滤到单个路径。
- 搜索分析：运行 mint analytics search；--query 按搜索词子串过滤。
- 反馈分析：运行 mint analytics feedback；--type（code 或 page）。
- 列出助手会话：运行 mint analytics conversation list。
- 查看单个会话：运行 mint analytics conversation view <id>。
- 列出会话分类桶：运行 mint analytics conversation buckets list。
- 查看桶中会话：运行 mint analytics conversation buckets view <id>。
- 认证：运行 mint login 登录 Mintlify 账户。
- 登出：运行 mint logout。
- 显示认证状态：运行 mint status。
- 持久化配置：运行 mint config set <key> <value>；有效 key：subdomain、dateFrom、dateTo。
- 读取配置：运行 mint config get <key>。
- 清除配置：运行 mint config clear <key>。
- 脚手架新 Mintlify 文档站：运行 mint new [directory]；--theme 和 --name 设置初始配置。
- 向文档仓库添加 workflow：运行 mint workflow。
- 更新 CLI 到最新版：运行 mint update。
- 显示已安装 CLI 和客户端版本：运行 mint version。
- 写作使用第二人称 you。
- 使用主动语态、直接语言。
- 标题使用 sentence case，如 Getting started，而不是 Getting Started。
- 代码块标题使用 sentence case。
- 所有代码块必须有语言标签。
- 所有图片必须有描述性 alt 文本。
- 不要使用营销语言、填充短语或 emoji。
- 保持代码示例简单、实用且经过测试。
- 避免常见错误：代码块缺少语言标签，用 ```python，而不是 ```。
- 避免用相对路径（../page）而非根相对路径（/section/page）。
- 避免忘记将新页面加入 docs.json 导航。
- 避免图片没有 alt 文本。
- 避免内部链接添加文件扩展名，用 /page，而不是 /page.mdx。
适用边界 · 注意事项
- 不适用于非 Mintlify 文档站点或使用 Docusaurus、Nextra、VitePress 等其他框架的项目。
- 不适用于无法安装或使用 Mintlify CLI、无法修改 docs.json、没有 Mintlify 账户或付费权限的场景。
- 不适用于只需写与 Mintlify 配置无关的通用 Markdown 内容。