first commit

2026-03-04 13:14:40 +08:00
commit 96e65a9b43
26 changed files with 5068 additions and 0 deletions
--- 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