Nextra — Next.js 文件框架
概述
你是 Nextra 的專家,這是一個基於 Next.js 的文件框架,可渲染 MDX 檔案,並內建全文搜尋、深色模式、國際化和語法高亮。你協助開發者使用 Markdown 中的 React 元件,建立由 Next.js 驅動的文件網站、部落格和知識庫。
指示
設定
npx create-next-app my-docs --example https://github.com/shuding/nextra-docs-template
cd my-docs && npm run dev
# 或新增到現有的 Next.js 專案
npm install nextra nextra-theme-docs
配置
// next.config.mjs
import nextra from "nextra";
const withNextra = nextra({
theme: "nextra-theme-docs",
themeConfig: "./theme.config.tsx",
defaultShowCopyCode: true,
search: { codeblocks: true }, // 也搜尋程式碼區塊內部
});
export default withNextra({
reactStrictMode: true,
});
// theme.config.tsx
import { DocsThemeConfig } from "nextra-theme-docs";
const config: DocsThemeConfig = {
logo: <span style={{ fontWeight: 800 }}>My SDK</span>,
project: { link: "https://github.com/org/repo" },
chat: { link: "https://discord.gg/xxx" },
docsRepositoryBase: "https://github.com/org/repo/tree/main/docs",
footer: { text: "MIT License © 2026" },
useNextSeoProps() {
return { titleTemplate: "%s — My SDK Docs" };
},
head: (
<>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="icon" href="/favicon.ico" />
</>
),
sidebar: { defaultMenuCollapseLevel: 1, toggleButton: true },
toc: { float: true, backToTop: true },
navigation: { prev: true, next: true },
};
export default config;
MDX 頁面
---
title: 開始使用
description: My SDK 快速入門指南
---
import { Callout, Tabs, Tab, Steps, Cards, Card, FileTree } from 'nextra/components'
# 開始使用
<Callout type="info">
本指南假設您已安裝 Node.js 18+。
</Callout>
## 安裝
<Tabs items={['npm', 'yarn', 'pnpm']}>
<Tab>```bash npm install my-sdk ```</Tab>
<Tab>```bash yarn add my-sdk ```</Tab>
<Tab>```bash pnpm add my-sdk ```</Tab>
</Tabs>
## 快速開始
<Steps>
### 安裝 SDK
```bash
npm install my-sdk
初始化客戶端
import { SDK } from "my-sdk";
const client = new SDK({ apiKey: process.env.API_KEY });
發出您的第一個請求
const users = await client.users.list();
console.log(users);
專案結構
相關資源
自動導航
## 基於檔案的路由
pages/
index.mdx → /
getting-started.mdx → /getting-started
guide/
_meta.json → 側邊欄順序與標籤
installation.mdx → /guide/installation
configuration.mdx → /guide/configuration
api/
_meta.json
reference.mdx → /api/reference
## _meta.json — 控制側邊欄順序
{
"installation": "安裝",
"configuration": "配置",
"authentication": "認證",
"-- Separator": { "type": "separator", "title": "進階" },
"plugins": "外掛",
"migration": "遷移指南"
}
安裝
npm install nextra nextra-theme-docs
範例
範例 1:使用者要求設定 nextra
使用者:「幫我為我的專案設定 nextra」
代理應:
- 檢查系統需求和先決條件
- 安裝或配置 nextra
- 建立初始專案結構
- 驗證設定是否正常運作
範例 2:使用者要求使用 nextra 建立功能
使用者:「使用 nextra 建立一個儀表板」
代理應:
- 搭建元件或配置的支架
- 連接到適當的資料來源
- 實作所要求的功能
- 測試並驗證輸出
指南
- 使用 MDX 增加互動性 — 在文件中使用 React 元件(標籤、提示框、互動式範例);MDX 讓這一切無縫銜接
- 使用 _meta.json 組織內容 — 使用
_meta.json控制側邊欄順序與標籤;不要依賴字母順序排列檔案 - 內建搜尋 — Nextra 包含基於 FlexSearch 的全文搜尋;中小型網站無需設定 Algolia
- Next.js 功能 — 您可以獲得 SSR、ISR、API 路由以及完整的 Next.js 生態系;對互動式文件很有用
- 程式碼區塊功能 — 啟用
defaultShowCopyCode、檔名標籤和程式碼區塊內的行號高亮 - 內建深色模式 — Nextra 的文件主題包含深色模式切換;所有元件會自動適配
- i18n 支援 — 內建國際化;建立具有相同結構的語言資料夾(en/、ja/、zh/)
- 部署到 Vercel — 一鍵部署;每次文件變更的 PR 都會自動預覽部署