first commit

2026-03-04 13:14:40 +08:00
commit 96e65a9b43
26 changed files with 5068 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,4 @@
+.next
+node_modules
+
+out
--- a/21
+++ b/21
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shenjianZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/README.md
+++ b/README.md
@@ -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/)
--- a/app/_meta.js
+++ b/app/_meta.js
@@ -0,0 +1,5 @@
+export default {
+  index: "首页",
+  "getting-started": "入门指南",
+  guide: "使用指南"
+}
--- a/app/components/CustomFooter.tsx
+++ b/app/components/CustomFooter.tsx
@@ -0,0 +1,5 @@
+import { Footer } from "nextra-theme-docs";
+
+export const CustomFooter = () => (
+    <Footer>MIT © {new Date().getFullYear()} Nextra Template Docs.</Footer>
+);
--- a/app/components/CustomNavbar.tsx
+++ b/app/components/CustomNavbar.tsx
@@ -0,0 +1,18 @@
+import { Navbar } from "nextra-theme-docs";
+import { DiscordIcon } from "nextra/icons";
+import { Logo } from "./Logo";
+import { CustomGiteaIcon } from "./icons/CustomGiteaIcon";
+import { CustomGitHubIcon } from "./icons/CustomGitHubIcon";
+import { CustomGiteeIcon } from "./icons/CustomGiteeIcon";
+
+export const CustomNavbar = () => (
+    <Navbar
+        logo={<Logo />}
+        logoLink="/"
+        projectLink="https://gitea.shenjianl.cn/shenjianZ/nextra-docs-template"
+        projectIcon={<CustomGiteaIcon />}
+        chatLink="https://discord.gg/your-server"
+        chatIcon={<DiscordIcon />}
+        align="right"
+    />
+);
--- a/app/components/Logo.tsx
+++ b/app/components/Logo.tsx
@@ -0,0 +1,13 @@
+export const Logo = () => (
+    <>
+        <svg width="24" height="24" viewBox="0 0 24 24">
+            <path
+                fill="currentColor"
+                d="M14.683 14.828a4.055 4.055 0 0 1-1.272.858a4.002 4.002 0 0 1-4.875-1.45l-1.658 1.119a6.063 6.063 0 0 0 1.621 1.62a5.963 5.963 0 0 0 2.148.903a6.035 6.035 0 0 0 3.542-.35a6.048 6.048 0 0 0 1.907-1.284c.272-.271.52-.571.734-.889l-1.658-1.119a4.147 4.147 0 0 1-.489.592z M12 2C6.486 2 2 6.486 2 12s4.486 10 10 10s10-4.486 10-10S17.514 2 12 2zm0 2c2.953 0 5.531 1.613 6.918 4H5.082C6.469 5.613 9.047 4 12 4zm0 16c-4.411 0-8-3.589-8-8c0-.691.098-1.359.264-2H5v1a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2h2a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2v-1h.736c.166.641.264 1.309.264 2c0 4.411-3.589 8-8 8z"
+            />
+        </svg>
+        <span style={{ marginLeft: ".4em", fontWeight: 800 }}>
+            Nextra Template Docs
+        </span>
+    </>
+);
--- a/app/components/icons/CustomGitHubIcon.tsx
+++ b/app/components/icons/CustomGitHubIcon.tsx
@@ -0,0 +1,11 @@
+export const CustomGitHubIcon = () => (
+    <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="currentColor"
+        xmlns="http://www.w3.org/2000/svg"
+    >
+        <path d="M12 0.2975C5.3725 0.2975 0 5.67 0 12.2975C0 17.6175 3.438 22.0975 8.205 23.6475C8.805 23.7575 9.025 23.4075 9.025 23.0975C9.025 22.8175 9.015 22.0675 9.01 21.1275C5.6725 21.7975 4.9675 19.5675 4.9675 19.5675C4.4225 18.1475 3.6325 17.7575 3.6325 17.7575C2.5475 17.0375 3.7175 17.0575 3.7175 17.0575C4.9225 17.1475 5.5525 18.2975 5.5525 18.2975C6.6225 20.1075 8.3925 19.5675 9.0725 19.2475C9.1825 18.4675 9.4825 17.9575 9.8225 17.6475C7.1525 17.3375 4.3425 16.2675 4.3425 11.5975C4.3425 10.2775 4.7825 9.1975 5.5525 8.3575C5.4225 8.0475 5.0425 6.8175 5.6625 5.1375C5.6625 5.1375 6.6825 4.7975 9.0025 6.3875C9.9725 6.1075 11.0025 5.9675 12.0325 5.9625C13.0625 5.9675 14.0925 6.1075 15.0625 6.3875C17.3825 4.7975 18.4025 5.1375 18.4025 5.1375C19.0225 6.8175 18.6425 8.0475 18.5125 8.3575C19.2825 9.1975 19.7225 10.2775 19.7225 11.5975C19.7225 16.2775 16.9025 17.3325 14.2225 17.6425C14.6625 18.0075 15.0625 18.7075 15.0625 19.7975C15.0625 21.3575 15.0525 22.6075 15.0525 23.0975C15.0525 23.4075 15.2625 23.7675 15.8725 23.6475C20.6425 22.0975 24.0825 17.6175 24.0825 12.2975C24.0825 5.67 18.71 0.2975 12 0.2975Z" />
+    </svg>
+);
--- a/app/components/icons/CustomGiteaIcon.tsx
+++ b/app/components/icons/CustomGiteaIcon.tsx
@@ -0,0 +1,14 @@
+export const CustomGiteaIcon = () => (
+    <svg
+        className="icon"
+        viewBox="0 0 1024 1024"
+        xmlns="http://www.w3.org/2000/svg"
+        width="32"
+        height="32"
+    >
+        <path
+            d="M178.592 231.296c-78.72-0.16-184.16 49.888-178.336 175.36 9.088 196 209.92 214.176 290.176 215.776 8.8 36.768 103.264 163.584 173.184 170.24h306.336c183.712-12.192 321.28-555.616 219.296-557.664-168.672 7.936-268.64 11.936-354.336 12.64v169.6l-26.72-11.808-0.16-157.696c-98.4-0.032-184.992-4.608-349.408-12.704-20.576-0.128-49.248-3.616-80.032-3.712z m11.136 69.344h9.376c11.168 100.48 29.344 159.232 66.144 248.992-93.856-11.104-173.728-38.368-188.416-140.16-7.584-52.704 18.016-107.68 112.896-108.832z m365.12 98.752c6.4 0.096 12.928 1.28 19.072 4.096l31.968 13.792-22.912 41.76h-0.224a31.872 31.872 0 0 0-10.272 1.696l0.192-0.064c-11.168 3.648-18.976 12.992-18.976 23.968 0 3.104 0.608 6.048 1.76 8.8l-0.064-0.192a24.544 24.544 0 0 0 4.832 7.456l-0.032-0.032-39.52 71.936a31.68 31.68 0 0 0-9.664 1.664l0.192-0.064c-11.168 3.648-18.976 12.992-18.976 23.968 0 3.104 0.608 6.048 1.76 8.8l-0.064-0.192c4.096 9.92 14.624 16.864 26.976 16.864a31.584 31.584 0 0 0 9.92-1.568l-0.192 0.064c11.136-3.648 18.944-12.992 18.944-23.968 0-3.104-0.64-6.08-1.792-8.864l0.064 0.192a25.088 25.088 0 0 0-6.752-9.376l38.496-70.048a31.968 31.968 0 0 0 12.704-1.312l-0.192 0.064a30.144 30.144 0 0 0 9.12-4.8l-0.032 0.032c14.848 6.24 27.008 11.296 35.744 15.616 13.152 6.496 17.792 10.784 19.2 15.584 1.408 4.704-0.128 13.728-7.552 29.6-5.536 11.808-14.72 28.576-25.568 48.352h-0.64a31.712 31.712 0 0 0-10.272 1.696l0.192-0.064c-11.168 3.648-18.976 12.992-18.976 23.968 0 3.104 0.608 6.048 1.76 8.8l-0.064-0.192c4.096 9.92 14.624 16.864 26.976 16.864a31.584 31.584 0 0 0 9.92-1.568l-0.192 0.064c11.136-3.648 18.944-12.992 18.944-23.968a22.496 22.496 0 0 0-1.76-8.8l0.064 0.192a25.664 25.664 0 0 0-5.856-8.64l0.032 0.032c10.72-19.552 19.936-36.352 25.856-48.992 8.032-17.152 12.192-29.92 8.544-42.24s-14.944-20.352-29.856-27.744c-9.824-4.832-22.048-9.952-36.704-16.096a23.136 23.136 0 0 0-1.664-10.368l0.064 0.192a25.344 25.344 0 0 0-6.208-8.928l22.528-41.088 124.768 53.888c22.528 9.76 31.84 33.696 20.896 ... [truncated]"
+            fill="#609926"
+        ></path>
+    </svg>
+);
--- a/app/components/icons/CustomGiteeIcon.tsx
+++ b/app/components/icons/CustomGiteeIcon.tsx
@@ -0,0 +1,14 @@
+export const CustomGiteeIcon = () => (
+    <svg
+        className="icon"
+        viewBox="0 0 1024 1024"
+        xmlns="http://www.w3.org/2000/svg"
+        width="32"
+        height="32"
+    >
+        <path
+            d="M512 1024C229.222 1024 0 794.778 0 512S229.222 0 512 0s512 229.222 512 512-229.222 512-512 512z m259.149-568.883h-290.74a25.293 25.293 0 0 0-25.292 25.293l-0.026 63.206c0 13.952 11.315 25.293 25.267 25.293h177.024c13.978 0 25.293 11.315 25.293 25.267v12.646a75.853 75.853 0 0 1-75.853 75.853h-240.23a25.293 25.293 0 0 1-25.267-25.293V417.203a75.853 75.853 0 0 1 75.827-75.853h353.946a25.293 25.293 0 0 0 25.267-25.292l0.077-63.207a25.293 25.293 0 0 0-25.268-25.293H417.152a189.62 189.62 0 0 0-189.62 189.645V771.15c0 13.977 11.316 25.293 25.294 25.293h372.94a170.65 170.65 0 0 0 170.65-170.65V480.384a25.293 25.293 0 0 0-25.293-25.267z"
+            fill="#C71D23"
+        ></path>
+    </svg>
+);
--- a/app/components/sidebar.ts
+++ b/app/components/sidebar.ts
@@ -0,0 +1,4 @@
+export const sidebar = {
+    defaultMenuCollapseLevel: 1,
+    autoCollapse: true,
+};
--- a/app/getting-started/_meta.js
+++ b/app/getting-started/_meta.js
@@ -0,0 +1,5 @@
+export default {
+    installation: "1. 安装指南",
+    quickstart: "2. 快速开始",
+    configuration: "3. 配置说明",
+};
--- a/app/getting-started/configuration/page.mdx
+++ b/app/getting-started/configuration/page.mdx
@@ -0,0 +1,80 @@
+# 配置说明
+
+## 主题配置
+
+在 `theme.config.tsx` 中配置主题：
+
+```typescript
+export default {
+  logo: <span>你的站点名称</span>,
+  project: {
+    link: "https://github.com/your-username/your-repo",
+  },
+  docsRepositoryBase: "https://github.com/your-username/your-repo",
+  footer: {
+    text: "你的站点名称",
+  },
+  sidebar: {
+    defaultMenuCollapseLevel: 1,
+    autoCollapse: true,
+  },
+}
+```
+
+### 关键配置项
+
+| 配置项 | 说明 |
+|--------|------|
+| `logo` | 站点 Logo |
+| `project.link` | 项目仓库链接 |
+| `docsRepositoryBase` | 文档仓库基础 URL |
+| `footer.text` | 页脚文本 |
+| `defaultMenuCollapseLevel` | 默认菜单折叠级别 |
+| `autoCollapse` | 是否自动折叠 |
+
+## 导航配置
+
+### 主导航
+
+编辑 `app/_meta.js`：
+
+```javascript
+export default {
+  index: "首页",
+  "getting-started": "入门指南",
+  guide: "使用指南"
+}
+```
+
+### 子导航
+
+编辑子目录的 `_meta.js`，例如 `app/getting-started/_meta.js`：
+
+```javascript
+export default {
+  installation: "安装指南",
+  quickstart: "快速开始",
+  configuration: "配置说明"
+}
+```
+
+## Next.js 配置
+
+在 `next.config.mjs` 中配置：
+
+```javascript
+import nextra from 'nextra'
+
+const withNextra = nextra({
+  theme: 'nextra-theme-docs',
+  themeConfig: './theme.config.tsx',
+})
+
+export default withNextra({
+  output: 'export', // 静态导出
+})
+```
+
+## 自定义样式
+
+你可以在 `app/globals.css` 中添加自定义样式。
--- a/app/getting-started/installation/page.mdx
+++ b/app/getting-started/installation/page.mdx
@@ -0,0 +1,47 @@
+# 安装指南
+
+## 环境要求
+
+- 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
+```
+
+如果安装成功，浏览器会自动打开 `http://localhost:3000`。
+
+## 常见问题
+
+### Node.js 版本过低
+
+请升级到 Node.js 18.x 或更高版本：
+
+```bash
+# 使用 nvm 安装
+nvm install 18
+nvm use 18
+```
+
+### pnpm 未安装
+
+```bash
+npm install -g pnpm
+```
--- a/app/getting-started/quickstart/page.mdx
+++ b/app/getting-started/quickstart/page.mdx
@@ -0,0 +1,53 @@
+# 快速开始
+
+本指南将帮助你在 5 分钟内创建你的第一个文档页面。
+
+## 创建文档页面
+
+### 1. 添加新页面
+
+在 `app` 目录下创建新的 `.mdx` 文件：
+
+```
+app/
+└── getting-started/
+    └── my-first-page.mdx  # 新建文件
+```
+
+### 2. 编写内容
+
+在 `my-first-page.mdx` 中添加内容：
+
+```markdown
+# 我的第一个页面
+
+这是我的第一个文档页面！
+
+## 功能特性
+
+- 功能一
+- 功能二
+- 功能三
+```
+
+### 3. 更新导航
+
+编辑 `app/getting-started/_meta.js`：
+
+```javascript
+export default {
+  installation: "安装指南",
+  quickstart: "快速开始",
+  configuration: "配置说明",
+  "my-first-page": "我的页面"
+}
+```
+
+### 4. 查看结果
+
+刷新浏览器，你会在侧边栏看到新页面。
+
+## 下一步
+
+- [配置说明](/getting-started/configuration) - 了解如何自定义配置
+- [基础概念](/guide/basics) - 学习更多使用技巧
--- a/app/guide/_meta.js
+++ b/app/guide/_meta.js
@@ -0,0 +1,4 @@
+export default {
+    basics: "1. 基础概念",
+    "best-practices": "2. 最佳实践",
+};
--- a/app/guide/basics/page.mdx
+++ b/app/guide/basics/page.mdx
@@ -0,0 +1,80 @@
+# 基础概念
+
+## 文件结构
+
+```
+nextra-docs-template/
+├── app/                    # 应用目录
+│   ├── _meta.js           # 主导航配置
+│   ├── layout.tsx         # 布局组件
+│   ├── page.mdx           # 首页
+│   ├── getting-started/   # 入门指南
+│   └── guide/             # 使用指南
+├── public/                # 静态资源
+├── theme.config.tsx       # 主题配置
+├── next.config.mjs        # Next.js 配置
+├── package.json           # 项目配置
+└── tsconfig.json          # TypeScript 配置
+```
+
+## 核心概念
+
+### MDX
+
+Nextra 使用 MDX 格式，支持在 Markdown 中使用 React 组件：
+
+```markdown
+# 标题
+
+普通文本。
+
+<MyComponent />
+
+代码示例：
+
+\`\`\`js
+console.log('Hello, Nextra!');
+\`\`\`
+```
+
+### 导航系统
+
+Nextra 根据文件结构和 `_meta.js` 自动生成导航。
+
+- **主导航**：`app/_meta.js`
+- **子导航**：各子目录的 `_meta.js`
+
+### 侧边栏
+
+侧边栏自动根据文件结构生成，支持：
+- 手风琴式折叠
+- 多级嵌套
+- 自动排序
+
+## 常用组件
+
+### 代码块
+
+使用三个反引号创建代码块：
+
+```javascript
+function hello() {
+  console.log('Hello!');
+}
+```
+
+### 提示框
+
+使用 `>` 创建提示框：
+
+> 这是一个提示框，用于强调重要内容。
+
+### 列表
+
+**无序列表：**
+- 项目一
+- 项目二
+
+**有序列表：**
+1. 第一步
+2. 第二步
--- a/app/guide/best-practices/page.mdx
+++ b/app/guide/best-practices/page.mdx
@@ -0,0 +1,102 @@
+# 最佳实践
+
+## 文档组织
+
+### 合理的目录结构
+
+建议按功能或主题组织文档：
+
+```
+app/
+├── getting-started/     # 入门相关
+├── guide/               # 使用指南
+├── api/                 # API 文档
+└── examples/            # 示例代码
+```
+
+### 清晰的命名
+
+使用简洁、清晰的文件名：
+- ✅ `installation.mdx`
+- ✅ `quick-start.mdx`
+- ❌ `page1.mdx`
+- ❌ `how-to-install-this-thing.mdx`
+
+## 内容编写
+
+### 使用标题层级
+
+- `#` 用于页面标题（每个页面只有一个）
+- `##` 用于主要章节
+- `###` 用于子章节
+
+避免跳级使用标题。
+
+### 添加代码示例
+
+代码示例应清晰、完整、可运行：
+
+```javascript
+// ✅ 好的示例
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+
+console.log(greet('World')); // 输出: Hello, World!
+```
+
+### 使用表格展示数据
+
+| 配置项 | 类型 | 说明 |
+|--------|------|------|
+| `theme` | string | 主题名称 |
+| `logo` | ReactNode | 站点 Logo |
+
+## 性能优化
+
+### 图片优化
+
+使用 WebP 格式，压缩图片大小：
+
+```markdown
+![示例图片](./image.webp)
+```
+
+### 代码高亮
+
+指定语言以启用代码高亮：
+
+\`\`\`javascript
+const code = 'highlighted';
+\`\`\`
+
+## 可访问性
+
+### 语义化 HTML
+
+使用正确的标题层级和语义化标签。
+
+### 描述性链接
+
+避免使用"点击这里"这样的链接文本：
+
+- ✅ [查看安装指南](/getting-started/installation)
+- ❌ [点击这里](/getting-started/installation)
+
+## 部署建议
+
+### 静态托管
+
+推荐使用以下静态托管服务：
+- Vercel
+- Netlify
+- GitHub Pages
+- Cloudflare Pages
+
+### 构建命令
+
+```bash
+pnpm build
+```
+
+构建完成后，`out` 目录包含所有静态文件。
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -0,0 +1,42 @@
+import { Head } from "nextra/components";
+import { Layout } from "nextra-theme-docs";
+import "nextra-theme-docs/style.css";
+import { getPageMap } from "nextra/page-map";
+import { CustomFooter } from "./components/CustomFooter";
+import { CustomNavbar } from "./components/CustomNavbar";
+import { sidebar } from "./components/sidebar";
+
+export const metadata = {
+    title: "Nextra Docs",
+    description: "Nextra Docs",
+};
+
+export default async function RootLayout({
+    children,
+}: {
+    children: React.ReactNode;
+}) {
+    const pageMap = await getPageMap();
+
+    return (
+        <html lang="zh-CN" suppressHydrationWarning>
+            <Head>
+                <meta
+                    name="viewport"
+                    content="width=device-width, initial-scale=1.0"
+                />
+            </Head>
+            <body>
+                <Layout
+                    footer={<CustomFooter />}
+                    pageMap={pageMap}
+                    docsRepositoryBase="https://gitea.shenjianl.cn/shenjianZ/nextra-template-docs"
+                    navbar={<CustomNavbar />}
+                    sidebar={sidebar}
+                >
+                    {children}
+                </Layout>
+            </body>
+        </html>
+    );
+}
--- a/app/page.mdx
+++ b/app/page.mdx
@@ -0,0 +1,42 @@
+# Nextra 文档模板
+
+欢迎使用 Nextra 文档模板！这是一个简洁、易用的文档网站模板，帮助你快速搭建专业的文档站点。
+
+## ✨ 特点
+
+- **简单易用** - 基于 Next.js 和 Nextra，几分钟即可上手
+- **静态生成** - 生成纯静态 HTML，部署简单快捷
+- **响应式设计** - 完美适配桌面和移动设备
+- **深色模式** - 内置主题切换功能
+- **全文搜索** - 支持快速搜索文档内容
+- **MDX 支持** - 在 Markdown 中使用 React 组件
+
+## 🚀 快速开始
+
+```bash
+# 1. 安装依赖
+pnpm install
+
+# 2. 启动开发服务器
+pnpm dev
+
+# 3. 打开浏览器访问
+# http://localhost:3000
+```
+
+## 📚 文档导航
+
+- [入门指南](/getting-started/installation) - 了解如何安装和配置
+- [使用指南](/guide/basics) - 掌握模板的核心用法
+
+## 🎯 适用场景
+
+- 项目文档网站
+- API 文档
+- 技术博客
+- 知识库
+- 教程网站
+
+## 📄 许可证
+
+MIT License
--- a/mdx-components.js
+++ b/mdx-components.js
@@ -0,0 +1,9 @@
+import { useMDXComponents as getThemeComponents } from "nextra-theme-docs";
+// 或者你的主题，比如 nextra-theme-blog
+
+export function useMDXComponents(components) {
+    return {
+        ...getThemeComponents(),
+        ...components,
+    };
+}
--- a/next-env.d.ts
+++ b/next-env.d.ts
@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.
--- a/next.config.mjs
+++ b/next.config.mjs
@@ -0,0 +1,10 @@
+// next.config.mjs
+import nextra from "nextra";
+
+export default nextra({})({
+    // Next.js 配置
+    output: "export", // ⚡ 关键：启用静态导出
+    // 如果需要，你可以加 basePath、images 等配置
+    images: { unoptimized: true }, // 必须！
+    trailingSlash: true, // 建议，使链接行为一致
+});
--- a/package.json
+++ b/package.json
@@ -0,0 +1,26 @@
+{
+    "name": "nextra-docs-template",
+    "version": "0.0.1",
+    "description": "Nextra docs template",
+    "scripts": {
+        "dev": "next dev",
+        "build": "next build",
+        "start": "next start"
+    },
+    "author": "shenjianZ <shenjianZLT@gmail.com>",
+    "license": "MIT",
+    "dependencies": {
+        "next": "^14.2.0",
+        "nextra": "4.3.0",
+        "nextra-theme-docs": "4.3.0",
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1"
+    },
+    "devDependencies": {
+        "@types/node": "^25.3.3",
+        "@types/react": "^19.2.14",
+        "@types/react-dom": "^19.2.3",
+        "typescript": "^5.9.3"
+    },
+    "packageManager": "pnpm@10.17.1+sha512.17c560fca4867ae9473a3899ad84a88334914f379be46d455cbf92e5cf4b39d34985d452d2583baf19967fa76cb5c17bc9e245529d0b98745721aa7200ecaf7a"
+}
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -0,0 +1,31 @@
+{
+    "compilerOptions": {
+        "target": "ES2017",
+        "lib": ["dom", "dom.iterable", "esnext"],
+        "allowJs": true,
+        "skipLibCheck": true,
+        "strict": false,
+        "noEmit": true,
+        "incremental": true,
+        "module": "esnext",
+        "esModuleInterop": true,
+        "moduleResolution": "bundler",
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "jsx": "preserve",
+        "plugins": [
+            {
+                "name": "next",
+            },
+        ],
+    },
+    "include": [
+        "next-env.d.ts",
+        ".next/types/**/*.ts",
+        ".next/dev/types/**/*.ts",
+        "**/*.mts",
+        "**/*.ts",
+        "**/*.tsx",
+    ],
+    "exclude": ["node_modules"],
+}