first commit
This commit is contained in:
298
README.md
Normal file
298
README.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# 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/)
|
||||
Reference in New Issue
Block a user