网站开发

本文档介绍 Cirno 文档网站的项目架构和开发最佳实践。

项目架构

项目性质

这是 Cirno 的官方文档和下载网站，基于 Next.js 构建。Cirno 本身是一个基于 Linux cgroup v2 的 Android 后台冻结工具，其 Android 应用源码托管在独立仓库。

目录结构

cirno-update/
├── src/
│   ├── app/              # Next.js App Router 页面
│   ├── components/       # UI 组件
│   ├── content/          # MDX 文档内容
│   └── lib/              # 工具函数
├── public/               # 静态资源
├── scripts/              # 构建脚本
└── next.config.ts        # Next.js 配置

核心模块

路由 (src/app/)

路径说明
/产品首页
/docs文档页面
/download下载页面
/api/*后端 API（代理 GitHub Actions）

组件 (src/components/)

  • navbar.tsx — 全局导航栏
  • drawer.tsx — 抽屉组件（移动端侧边栏）
  • docs/ — 文档专用组件（侧边栏、目录、搜索）

内容系统 (src/content/)

文档以 MDX 格式存储，通过 _meta.json 定义导航结构。每个 MDX 文件导出 metadata 对象作为元数据。

工具函数 (src/lib/)

  • docs.ts — 文档读取、解析、导航树构建
  • toc.ts — 从 MDX 提取目录标题

技术栈

技术用途
Next.js 16React 框架（App Router）
React 19UI 库
MDX文档内容格式
Tailwind CSS v4样式框架
remark/rehypeMDX 处理链

构建流程

  1. next build 预渲染所有文档页面
  2. postbuild 脚本扫描 MDX 生成 search-index.json
  3. 部署后可通过 /docs 路径访问文档

最佳实践

MDX 文档编写

文件结构

每个 MDX 文件必须在顶部导出 metadata 对象：

export const metadata = {
  title: "页面标题",
  description: "页面描述（用于 SEO）",
  order: 1, // 在导航中的排序
}

内容规范

  • 使用中文编写
  • 标题层级：# 为页面标题，## 为一级小节，### 为二级小节
  • 代码块使用三个反引号并标注语言类型
  • 表格使用 GFM 语法
  • 重要提示使用引用块（>）

导航配置

在 src/content/_meta.json 中定义导航：

{
  "section-name": {
    "title": "显示标题",
    "order": 1,
    "children": {
      "page-name": "页面标题"
    }
  }
}

新增文档步骤

  1. 在 src/content/ 下创建目录（如 development/）
  2. 创建 MDX 文件并导出 metadata
  3. 在 _meta.json 中注册目录和页面
  4. 构建后自动生成搜索索引

代码风格

TypeScript

  • 使用 TypeScript 编写所有组件和工具函数
  • 优先使用 interface 定义对象类型
  • 导出的函数和组件使用具名导出

React 组件

  • 客户端组件使用 'use client' 指令
  • 样式使用 Tailwind CSS 类名
  • 组件文件使用小写加连字符命名（如 sidebar.tsx）

工具函数

  • 服务端工具函数放在 src/lib/
  • 使用 async/await 处理异步操作
  • 文件读取使用 Node.js fs 模块

测试与验证

  • 构建前运行 npm run build 确保无错误
  • 检查所有文档链接是否正确
  • 验证搜索索引是否包含新页面