Skip to Content
cfstack
CTRL K
指南文档系统

文档系统

本项目使用 Nextra、MDX 内容与文档主题提供 /docs 阅读体验。

功能

📚 基于 MDX 的内容

使用 MDX（Markdown + JSX）编写文档，支持：

  • 丰富 Markdown 语法，包括 GitHub Flavored Markdown（GFM）
  • 直接嵌入文档的 React 组件
  • Shiki 代码语法高亮
  • 标题、描述等 frontmatter metadata

🎨 界面

基于 Nextra 主题构建：

  • 可折叠分区的响应式侧边导航
  • 方便页内跳转的目录
  • 页面之间的上一篇/下一篇导航
  • 全文搜索
  • 简洁、专业的设计

🚀 开发体验

支持高效开发：

  • 热重载：开发时即时查看修改
  • 类型安全：完整 TypeScript 支持
  • 快速构建：通过 OpenNext 面向 Cloudflare Workers 优化
  • Git 管理：文档与代码一同纳入版本控制

目录结构

中文文档内容组织在 src/app/zh-CN/docs/ 目录中：

src/app/zh-CN/docs/
├── layout.tsx             # 绑定共享 Nextra 文档布局
├── (overview)/
│   └── page.mdx           # 文档首页
├── _meta.js               # 根导航配置
├── getting-started/
│   ├── _meta.js           # 分区导航
│   ├── installation/
│   │   └── page.mdx
│   ├── configuration/
│   │   └── page.mdx
│   └── deployment/
│       └── page.mdx
└── guides/
    ├── _meta.js
    ├── authentication/
    │   └── page.mdx
    ├── blog-system/
    │   └── page.mdx
    └── documentation/
        └── page.mdx

该目录只放面向用户的内容。内部贡献者指引放在路由内 AGENTS.md 文件中；维护者文档的位置遵循 docs/AGENTS.md。

创建文档

添加页面

  1. 在合适目录中创建新文件夹与 page.mdx 文件：
mkdir -p src/app/zh-CN/docs/guides/my-guide
touch src/app/zh-CN/docs/guides/my-guide/page.mdx
  1. 添加 frontmatter 与内容：
---
locale: zh-CN
translationKey: guides.my-guide
title: 我的指南
description: 一篇实用指南
---
 
# 我的指南
 
在此使用 **Markdown** 编写内容！
 
## 章节
 
使用标题组织内容。
  1. 更新父目录的 _meta.js：
export default {
  authentication: "认证",
  "blog-system": "博客系统",
  "my-guide": "我的指南",
};

添加分区

  1. 创建新目录：
mkdir -p src/app/zh-CN/docs/my-section/page-1
mkdir -p src/app/zh-CN/docs/my-section/page-2
  1. 创建导航配置 _meta.js：
export default {
  "page-1": "页面一",
  "page-2": "页面二",
};
  1. 为分区添加页面：
touch src/app/zh-CN/docs/my-section/page-1/page.mdx
touch src/app/zh-CN/docs/my-section/page-2/page.mdx

Frontmatter 选项

每个 MDX 文件顶部都应包含 frontmatter：

---
locale: zh-CN
translationKey: guides.my-guide
title: 页面标题
description: 用于 SEO 和预览的简短描述
---

可用字段

  • title（必填）：导航与页首显示的页面标题
  • description：SEO 使用的页面描述；已发布语言资源必须填写
  • locale（必填）：资源语言 en 或 zh-CN
  • translationKey（必填）：完整对应版本共用的主题身份

Markdown 功能

代码块

支持语法高亮：

```tsx
import { Button } from "@t3template/ui/button";
 
export function Example() {
  return <Button>点击我</Button>;
}
```

链接

链接到其他文档页面：

另请参阅：[认证指南](/zh-CN/docs/guides/authentication)

表格

创建数据表格：

| 功能 | 描述 |
| --- | --- |
| MDX | 包含 JSX 的 Markdown |
| 搜索 | 全文搜索 |
| 主题 | 可定制设计 |

列表

有序与无序列表：

- 项目一
- 项目二
  - 嵌套项目
  - 另一个嵌套项目
 
1. 第一步
2. 第二步
3. 第三步

图片

在文档中添加图片：

![替代文本](/images/screenshot.png)

引用

突出重要信息：

> **说明：**这是一条需要读者关注的重要说明。

配置

定制主题

编辑项目根目录的 theme.config.tsx：

import { Footer, Navbar } from "nextra-theme-docs";
 
const docsThemeConfig = {
  navbar: (
    <Navbar
      logo={<span>你的文档标志</span>}
      logoLink="/zh-CN/docs"
      projectLink="https://github.com/aigotowork/cfstack"
    />
  ),
  footer: <Footer>你的页脚文字</Footer>,
  docsRepositoryBase: "https://github.com/aigotowork/cfstack/tree/main/src/app",
};

导航结构

侧边导航自动从以下内容生成：

  1. src/app/zh-CN/docs/ 中的文件结构
  2. 各目录的 _meta.js 文件

_meta.js 示例：

export default {
  index: "介绍",
  "getting-started": "开始使用",
  guides: "指南",
  "api-reference": "API 参考",
};

样式

自定义样式

在 src/styles/docs-custom.css 中添加自定义样式：

/* 自定义文档样式 */
.nextra-content {
  /* 你的自定义样式 */
}

主题颜色

文档继承 src/styles/globals.css 中的全局主题颜色。

编写建议

1. 按功能组织

将相关文档放在同一文件夹中。

2. 使用明确标题

标题应描述具体内容，便于浏览：

  • ✅ “安装依赖”
  • ❌ “安装”

3. 提供示例

为每个概念提供代码示例。

4. 连接相关页面

使用站内链接连接相关文档：

另请参阅：[配置指南](/zh-CN/docs/getting-started/configuration)

5. 保持更新

在以下情况下审阅并更新文档：

  • 新增功能时
  • API 改变时
  • 用户报告理解困难时

故障排查

MDX 编译错误

出现 MDX 错误时：

  1. 检查是否有未闭合 JSX 标签
  2. 确认 frontmatter 的 YAML 格式正确
  3. 确认代码块使用正确的三反引号边界

导航未更新

侧边导航未反映修改时：

  1. 重启开发服务器
  2. 检查 _meta.js 是否有语法错误
  3. 清理 Next.js 缓存：rm -rf .next

样式问题

样式未生效时：

  1. 检查共享 src/app/docs/reading-layout.tsx 中的 CSS 导入
  2. 检查 Tailwind 配置
  3. 配置变化后重启开发服务器

下一步

  • 编写第一篇文档
  • 定制主题配置
  • 为文档添加自定义组件

参考资源

语言资源与搜索

英文资源位于 src/app/en/docs，中文资源位于 src/app/zh-CN/docs。原 /docs 入口将已知页面重定向到英文。两棵目录树共用 src/app/docs/reading-layout.tsx、Nextra MDX 组件注册与站点页首。每个已发布页面在 frontmatter 声明 locale、translationKey、title 与 description。完整对应版本使用同一翻译键，并提供本语言 _meta.js 标签和链接。

未发布 Docs 应放在公开 App Router 树之外：构建会拒绝公开 page.mdx 中的 draft: true，不会悄悄发布它。缺译时显示明确的 noindex 阅读链接页面，不进入 sitemap 或搜索索引。

根布局按请求解析语言，因此生产 Docs 页面动态渲染。npm run build 通过 postbuild 运行 scripts/docs-search.ts，使用已安装 MDX parser 直接从作者资源生成 Pagefind 记录。索引省略代码、导入、可执行表达式与组件属性，不执行 MDX。Pagefind 负责语言分词，Nextra 负责搜索 UI。搜索只读取当前语言的索引与筛选条件，使用规范语言 URL。无需 Worker 文件系统扫描或实时内容索引。

博客系统