Nextra 文档模板

一个基于 Next.js 和 Nextra 构建的简洁、易用的文档网站模板,帮助你快速搭建专业的文档站点。

✨ 项目意义

本项目旨在提供一个开箱即用的文档模板,让开发者能够专注于内容创作,而不是花费时间在配置和搭建上。通过组件化的架构设计,使得定制化和维护变得更加简单高效。

核心优势:

• 🚀 快速启动 - 几分钟即可完成配置并运行
• 📦 组件化设计 - 核心功能模块化,易于定制和扩展
• 🎨 现代化 UI - 内置深色模式、响应式设计
• 🔍 强大功能 - 支持全文搜索、MDX、多级导航
• 📝 易于维护 - 清晰的目录结构,代码职责分离

📦 项目结构

nextra-docs-template/
├── app/                        # 应用目录
│   ├── components/            # 自定义组件
│   │   ├── icons/            # 图标组件
│   │   │   ├── CustomGitHubIcon.tsx
│   │   │   ├── CustomGiteaIcon.tsx
│   │   │   └── CustomGiteeIcon.tsx
│   │   ├── Logo.tsx          # Logo 组件
│   │   ├── CustomFooter.tsx  # 页脚组件
│   │   ├── CustomNavbar.tsx  # 导航栏组件
│   │   └── sidebar.ts        # 侧边栏配置
│   ├── _meta.js              # 主导航配置
│   ├── layout.tsx            # 布局组件
│   ├── page.mdx              # 首页
│   ├── getting-started/      # 入门指南
│   └── guide/                # 使用指南
├── public/                    # 静态资源
├── theme.config.tsx           # 主题配置
├── next.config.mjs            # Next.js 配置
├── package.json               # 项目配置
└── tsconfig.json              # TypeScript 配置

🚀 快速开始

环境要求

• Node.js 18.x 或更高版本
• pnpm 8.x 或更高版本

安装步骤

1. 克隆项目

git clone <your-repo-url>
cd nextra-docs-template

2. 安装依赖

pnpm install

3. 启动开发服务器

pnpm dev

4. 打开浏览器 访问 http://localhost:3000

构建生产版本

pnpm build
pnpm start

🧩 组件使用说明

1. 图标组件 (Icons)

位置: app/components/icons/

CustomGitHubIcon

GitHub 图标组件,用于在导航栏或页面中显示 GitHub 链接。

使用方式:

import { CustomGitHubIcon } from "./components/icons/CustomGitHubIcon";

// 在导航栏中使用
<Navbar
    projectLink="https://github.com/your-username/repo"
    projectIcon={<CustomGitHubIcon />}
/>

// 在页面中使用
<a href="https://github.com/your-username/repo">
    <CustomGitHubIcon />
</a>

CustomGiteaIcon

Gitea 图标组件,用于显示 Gitea 代码托管平台的链接。

使用方式:

import { CustomGiteaIcon } from "./components/icons/CustomGiteaIcon";

<Navbar
    projectLink="https://gitea.example.com/your-username/repo"
    projectIcon={<CustomGiteaIcon />}
/>

CustomGiteeIcon

Gitee 图标组件,用于显示 Gitee 代码托管平台的链接。

使用方式:

import { CustomGiteeIcon } from "./components/icons/CustomGiteeIcon";

<Navbar
    projectLink="https://gitee.com/your-username/repo"
    projectIcon={<CustomGiteeIcon />}
/>

2. Logo 组件

位置: app/components/Logo.tsx

Logo 组件包含项目的 SVG 图标和标题文本。

自定义 Logo: 编辑 app/components/Logo.tsx 文件:

export const Logo = () => (
    <>
        {/* 替换为你的 SVG 图标 */}
        <svg width="24" height="24" viewBox="0 0 24 24">
            {/* 你的 SVG 路径 */}
        </svg>
        {/* 修改标题文本 */}
        <span style={{ marginLeft: ".4em", fontWeight: 800 }}>
            你的项目名称
        </span>
    </>
);

使用方式:

import { Logo } from "./components/Logo";

<Navbar
    logo={<Logo />}
    logoLink="/"
/>

3. CustomFooter 组件

位置: app/components/CustomFooter.tsx

自定义页脚组件,显示版权信息。

自定义页脚: 编辑 app/components/CustomFooter.tsx 文件:

import { Footer } from "nextra-theme-docs";

export const CustomFooter = () => (
    <Footer>
        {/* 自定义版权信息 */}
        MIT © {new Date().getFullYear()} 你的公司/名称.
    </Footer>
);

使用方式:

import { CustomFooter } from "./components/CustomFooter";

<Layout footer={<CustomFooter />}>
    {children}
</Layout>

4. CustomNavbar 组件

位置: app/components/CustomNavbar.tsx

自定义导航栏组件,包含 Logo、项目链接、聊天链接等。

自定义导航栏: 编辑 app/components/CustomNavbar.tsx 文件:

import { Navbar } from "nextra-theme-docs";
import { DiscordIcon } from "nextra/icons";
import { Logo } from "./Logo";
import { CustomGiteaIcon } from "./icons/CustomGiteaIcon";

export const CustomNavbar = () => (
    <Navbar
        logo={<Logo />}
        logoLink="/"
        // 修改为你的项目链接
        projectLink="https://gitea.example.com/your-username/repo"
        // 修改为你使用的图标
        projectIcon={<CustomGiteaIcon />}
        // 修改为你的聊天链接
        chatLink="https://discord.gg/your-server"
        chatIcon={<DiscordIcon />}
        align="right"
    />
);

使用方式:

import { CustomNavbar } from "./components/CustomNavbar";

<Layout navbar={<CustomNavbar />}>
    {children}
</Layout>

5. Sidebar 配置

位置: app/components/sidebar.ts

侧边栏配置对象,控制菜单的折叠行为。

自定义侧边栏: 编辑 app/components/sidebar.ts 文件:

export const sidebar = {
    // 默认折叠菜单层级 (1 = 折叠二级菜单)
    defaultMenuCollapseLevel: 1,
    // 是否启用手风琴效果 (true = 只能展开一个菜单)
    autoCollapse: true,
};

使用方式:

import { sidebar } from "./components/sidebar";

<Layout sidebar={sidebar}>
    {children}
</Layout>

📝 添加新页面

1. 创建 MDX 文件

在 app 目录下创建 page.mdx 文件:

app/
└── your-page-folder/
    └── page.mdx       

2. 配置导航

编辑对应目录的 _meta.js 文件:

// app/_meta.js
export default {
    index:  "首页",
    your-page: "你的页面",
    your-folder: "你的文件夹",

};

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个模板!

📄 许可证

MIT License

🔗 相关链接

• Nextra 官方文档
• Next.js 文档
• MDX 文档