moai-library-nextra

快速参考

用途：使用 Nextra 和 Next.js 构建专业的文档站点。

Nextra 的优势：

• 零配置 MDX，无缝集成 Markdown 和 JSX
• 基于文件系统的路由，自动生成路由
• 通过代码拆分和预取优化性能
• 主题系统，支持可插拔和自定义主题
• 内置国际化支持

核心文件：

• pages 目录包含 MDX 格式的文档页面
• theme.config.tsx 文件包含站点配置
• _meta.js 文件控制导航结构

实施指南

功能

本技能涵盖 Nextra 3.x 和 4.x 文档框架的架构模式、Next.js 14 和 15 的集成及其最佳配置、通过 theme.config.tsx 或 Layout 属性自定义主题、集成 FlexSearch 的高级搜索、国际化支持、由 MDX 驱动并支持 React 组件的内容，以及 Nextra 4.x 中兼容 Turbopack 的 App Router 支持。

适用场景

在以下场景中使用本技能：借助现代 React 功能构建文档站点、创建具备高级搜索功能的知识库、开发多语言文档门户、实现自定义文档主题，或在技术文档中集成交互式示例。

项目设置

要初始化 Nextra 文档站点，请使用 npx 运行 create-nextra-app 命令，并指定 docs 模板。生成的项目结构包含 pages 目录，其中有自定义 App 组件文件、作为首页的 index MDX 文件，以及文档分区的子目录。每个分区都包含用于内容的 MDX 文件，以及用于导航配置的 _meta.json 文件。

主题配置

theme.config.tsx 文件导出一个配置对象，其中包含多个关键属性。logo 属性用于定义站点品牌元素。project 属性包含指向项目代码库的链接。docsRepositoryBase 属性指定编辑链接功能的基础 URL。useNextSeoProps 函数返回 SEO 配置，其中包括标题模板。

基本配置选项包括：用于 logo 和 logoLink 的品牌设置、用于项目链接和代码库基础 URL 的导航设置、用于默认折叠层级和切换按钮可见性的侧边栏设置、包含返回顶部功能的目录设置，以及用于自定义页脚文本的页脚设置。

导航结构

_meta.js 文件控制侧边栏菜单的排序和显示名称。每个文件都导出一个默认对象，其中的键代表文件或目录名称，值代表显示标签。特殊条目包括以三个连字符作为键、空字符串作为值的分隔线；外部链接则可通过包含 title、href 和 newWindow 属性的嵌套对象进行配置。

MDX 内容与 JSX 集成

Nextra 支持在 MDX 文件中直接混合 Markdown 和 React 组件。可以在文件顶部导入组件，并在 Markdown 内容中内联使用。自定义组件可以在 MDX 文件本身定义并导出。来自 nextra/components 的 Callout 组件可提供带样式的提示框，用于呈现备注、警告和提示。

搜索与 SEO 优化

主题配置支持内置搜索，并可自定义占位文本。可以通过 head 属性配置 SEO 元数据；该属性接受用于 meta 标签的 JSX，包括 Open Graph 标题、描述和图片。useNextSeoProps 函数提供动态标题模板配置。

---

高级文档

本技能采用渐进式披露。如需了解详细模式，请参阅 modules 目录：

• modules/configuration.md 提供完整的 theme.config 参考
• modules/mdx-components.md 介绍 MDX 组件库
• modules/i18n-setup.md 包含国际化指南
• modules/deployment.md 介绍托管和部署

主题选项

内置主题包括适用于文档站点的 nextra-theme-docs（推荐使用），以及适用于博客的 nextra-theme-blog。

自定义选项包括用于设置颜色的 CSS 变量、自定义侧边栏组件、页脚自定义和导航布局调整。

---

部署

常见的部署平台包括配置为零的 Vercel（推荐）、提供免费可自托管选项的 GitHub Pages、支持灵活 CI/CD 集成的 Netlify，以及可完全掌控的自定义服务器。

要部署到 Vercel，请使用 npm 全局安装 Vercel CLI，然后运行 vercel 命令来选择项目并部署。

---

与其他技能集成

互补技能包括用于从代码自动生成文档的 moai-docs-generation、用于验证文档质量的 moai-workflow-docs，以及用于 Markdown 格式设置的 moai-cc-claude-md。

---

版本历史

Version 2.2.0 于 2026-01-11 发布，移除了代码块，以符合 CLAUDE.md Documentation Standards，并将所有示例改为叙述性描述。

Version 2.1.0 于 2025-12-30 发布，更新了 configuration.md，加入完整的 Nextra 专属 theme.config.tsx 模式；添加了 Nextra 4.x App Router 配置模式；更新了 Next.js 14 和 15 的版本兼容性；并添加了 Turbopack 支持文档。

Version 2.0.0 于 2025-11-23 发布，采用 Progressive Disclosure 进行了重构，突出显示配置模式，并添加了 MDX 集成指南。

Version 1.0.0 于 2025-11-12 发布，提供了初始版 Nextra 架构指南、主题配置和 i18n 支持。

---

维护者：MoAI-ADK Team 领域：文档架构 生成方式：MoAI-ADK Skill Factory

---

配合使用

Agents：

• workflow-docs 用于生成文档
• code-frontend 用于实现 Nextra
• workflow-spec 用于架构文档

Skills：

• moai-docs-generation 用于生成内容
• moai-workflow-docs 用于验证文档
• moai-library-mermaid 用于集成图表

Commands：

• moai:3-sync 用于部署文档
• moai:0-project 用于初始化 Nextra 项目