mintlify

Mintlify 參考文件

使用 Mintlify 建立文件的參考。本檔案涵蓋所有任務通用的基本事項。如需特定主題的詳細參考，請閱讀下方參考索引所列的檔案。

參考索引

僅在任務需要時才閱讀這些檔案。它們位於此檔案旁的 reference/ 目錄中。若要找到它們，請查看與此技能檔案相同的目錄（例如 .claude/skills/mintlify/reference/）。

檔案	何時閱讀
reference/components.md	新增或修改元件（callouts、cards、steps、tabs、accordions、code groups、fields、frames、icons、tooltips、badges、trees、mermaid、panels、prompts、colors、tiles、updates、views）。
reference/configuration.md	變更 docs.json 設定（主題、顏色、標誌、字型、外觀、導覽列、頁尾、橫幅、重新導向、SEO、整合、API 設定）。也涵蓋 snippets、隱藏頁面、.mintignore、自訂 CSS/JS 以及完整的 frontmatter 欄位表格。
reference/navigation.md	修改網站導覽結構（groups、tabs、anchors、dropdowns、products、versions、languages、導覽中的 OpenAPI）。
reference/api-docs.md	設定 API 文件（OpenAPI、AsyncAPI、MDX 手動 API 頁面、擴充功能、playground 設定）。

開始之前

請先閱讀專案的 docs.json 檔案。它定義了網站的導覽、主題、顏色和設定。

在建立新頁面前，請先搜尋現有內容。您可能需要更新現有頁面、新增章節或連結到現有內容，而非重複建立。

閱讀 2-3 個類似頁面，以符合網站的語氣、結構和格式。

檔案格式

Mintlify 使用帶有 YAML frontmatter 的 MDX 檔案（.mdx 或 .md）。

project/
├── docs.json           # 網站設定（必要）
├── index.mdx
├── quickstart.mdx
├── guides/
│   └── example.mdx
├── openapi.yml         # API 規格（選用）
├── images/             # 靜態資源
│   └── example.png
└── snippets/           # 可重複使用的元件
    └── component.jsx

檔案命名

• 符合目錄中現有的命名模式
• 如果沒有現有檔案或檔案命名模式混雜，請使用 kebab-case：getting-started.mdx
• 將新頁面加入 docs.json 的導覽中，否則它們不會出現在側邊欄

內部連結

• 使用根目錄相對路徑，不含副檔名：/getting-started/quickstart
• 內部頁面請勿使用相對路徑（../）或絕對 URL

圖片

將圖片存放在 images/ 目錄中。使用根目錄相對路徑引用。所有圖片都需要描述性的替代文字。

![顯示分析總覽的儀表板](/images/dashboard.png)

頁面 Frontmatter

每個頁面都需要在 frontmatter 中包含 title。加入 description 和 keywords 以利 SEO。

---
title: "清晰、具描述性的標題"
description: "用於 SEO 和導覽的簡潔摘要。"
keywords: ["相關", "搜尋", "詞彙"]
---

常見 Frontmatter 欄位

欄位	型別	必要	說明
title	string	是	導覽和瀏覽器分頁中的頁面標題。
description	string	否	用於 SEO 的簡短說明。顯示在標題下方。
sidebarTitle	string	否	側邊欄導覽的簡短標題。
icon	string	否	Lucide、Font Awesome 或 Tabler 圖示名稱。也接受 URL 或檔案路徑。
tag	string	否	側邊欄中頁面標題旁的標籤（例如 "NEW"）。
hidden	boolean	否	從側邊欄隱藏。頁面仍可透過 URL 存取。
mode	string	否	頁面版面：default、wide、custom、frame、center。
keywords	array	否	用於內部搜尋和 SEO 的搜尋詞。
api	string	否	互動式 playground 的 API 端點（例如 "POST /users"）。
openapi	string	否	OpenAPI 端點參考（例如 "GET /endpoint"）。

快速元件參考

以下是最常用的元件。如需完整屬性和全部 24 個元件，請閱讀 reference/components.md。

Callouts

<Note>補充資訊，可略過。</Note>
<Info>有用的背景資訊，例如權限或先決條件。</Info>
<Tip>建議或最佳做法。</Tip>
<Warning>可能造成破壞的動作或重要注意事項。</Warning>
<Check>成功確認或完成狀態。</Check>
<Danger>關於資料遺失或重大變更的嚴重警告。</Danger>

Steps

<Steps>
  <Step title="第一步">
    步驟一的說明。
  </Step>
  <Step title="第二步">
    步驟二的說明。
  </Step>
</Steps>

Tabs 與 Code Groups

<Tabs>
  <Tab title="npm">
    ```bash
    npm install package-name
    ```
  </Tab>
  <Tab title="yarn">
    ```bash
    yarn add package-name
    ```
  </Tab>
</Tabs>

<CodeGroup>

```javascript example.js
const greeting = "Hello, world!";

greeting = "Hello, world!"

</CodeGroup>

#### Cards 與 Columns

```mdx
<Columns cols={2}>
  <Card title="第一張卡片" icon="rocket" href="/quickstart">
    卡片說明文字。
  </Card>
  <Card title="第二張卡片" icon="book" href="/guides">
    卡片說明文字。
  </Card>
</Columns>

使用 <Columns> 將卡片（或其他內容）排列成網格。cols 接受 1-4。

Accordions

<AccordionGroup>
  <Accordion title="第一節">內容一。</Accordion>
  <Accordion title="第二節">內容二。</Accordion>
</AccordionGroup>

CLI 指令

• npm i -g mint — 安裝 Mintlify CLI。
• mint dev — 在本機 localhost:3000 預覽。
• mint broken-links — 檢查內部連結。
• mint a11y — 檢查無障礙問題。
• mint validate — 驗證文件建置。
• mint upgrade — 從 mint.json 升級至 docs.json。

寫作標準

• 使用第二人稱（「你」）。
• 主動語態，直接明瞭。
• 標題使用 sentence case（「Getting started」，而非「Getting Started」）。
• 程式碼區塊標題使用 sentence case。
• 所有程式碼區塊必須有語言標籤。
• 所有圖片必須有描述性的替代文字。
• 不使用行銷語言、填充詞或表情符號。
• 保持程式碼範例簡單、實用且經過測試。

常見錯誤

• 程式碼區塊缺少語言標籤（應使用 ```python，而非 ```）。
• 使用相對路徑（../page）而非根目錄相對路徑（/section/page）。
• 忘記將新頁面加入 docs.json 的導覽中。
• 圖片缺少替代文字。
• 在內部連結中加入副檔名（應使用 /page 而非 /page.mdx）。