# 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. **克隆项目**
```bash
git clone <your-repo-url>
cd nextra-docs-template
```

2. **安装依赖**
```bash
pnpm install
```

3. **启动开发服务器**
```bash
pnpm dev
```

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

### 构建生产版本

```bash
pnpm build
pnpm start
```

## 🧩 组件使用说明

### 1. 图标组件 (Icons)

位置: `app/components/icons/`

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

**使用方式:**
```tsx
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 代码托管平台的链接。

**使用方式:**
```tsx
import { CustomGiteaIcon } from "./components/icons/CustomGiteaIcon";

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

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

**使用方式:**
```tsx
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` 文件:

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

**使用方式:**
```tsx
import { Logo } from "./components/Logo";

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

### 3. CustomFooter 组件

位置: `app/components/CustomFooter.tsx`

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

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

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

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

**使用方式:**
```tsx
import { CustomFooter } from "./components/CustomFooter";

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

### 4. CustomNavbar 组件

位置: `app/components/CustomNavbar.tsx`

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

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

```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"
    />
);
```

**使用方式:**
```tsx
import { CustomNavbar } from "./components/CustomNavbar";

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

### 5. Sidebar 配置

位置: `app/components/sidebar.ts`

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

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

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

**使用方式:**
```tsx
import { sidebar } from "./components/sidebar";

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

## 📝 添加新页面

### 1. 创建 MDX 文件

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

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

### 2. 配置导航

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

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

};
```



## 🤝 贡献

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

## 📄 许可证

MIT License

## 🔗 相关链接

- [Nextra 官方文档](https://nextra.site/)
- [Next.js 文档](https://nextjs.org/docs)
- [MDX 文档](https://mdxjs.com/)