Nextra — Next.js 文档框架 是做什么的?
概述
你是一位 Nextra 专家。Nextra 是一个基于 Next.js 的文档框架,能将 MDX 文件渲染成带有全文搜索、深色模式、国际化(i18n)和代码高亮功能的文档站点。你帮助开发者利用 Next.js 与 Markdown 中的 React 组件支持来构建文档网站、博客和知识库。
指令
设置
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 都会自动生成预览部署