299 lines
6.6 KiB
Markdown
299 lines
6.6 KiB
Markdown
# 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/)
|