Oadin Docs - 现代化文档系统

基于 Docusaurus 3 构建的现代化静态文档站点，采用 TypeScript + pnpm + CSS 技术栈。

🚀 快速开始

环境要求

• Node.js: >= 18.0
• pnpm: >= 9.0 (推荐使用 pnpm 作为包管理器)

安装依赖

# 使用 pnpm 安装依赖（已配置淘宝镜像源）
pnpm install

本地开发

# 启动开发服务器
pnpm start

# 指定端口启动
pnpm start --port 3000

开发服务器启动后会自动打开浏览器，大部分更改会实时生效，无需重启服务器。

📖 文档编写

创建新文档

1. 在 docs/ 目录下创建 .md 或 .mdx 文件
2. 文件头部添加 frontmatter：

---
sidebar_position: 1
title: 文档标题
description: 文档描述
---

# 文档标题

文档内容...

文档结构

docs/
├── intro.md                 # 介绍页面
├── tutorial-basics/         # 基础教程目录
│   ├── create-a-page.md
│   └── markdown-features.mdx
└── advanced/                # 高级功能目录
    ├── theming.md
    └── deployment.md

添加图片和资源

1. 将图片放入 static/img/ 目录
2. 在文档中引用：

![图片描述](/img/your-image.png)

🎨 样式自定义

修改主题色彩

编辑 src/css/custom.css 中的 CSS 变量：

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  /* 更多颜色变量... */
}

添加自定义样式

在 src/css/custom.css 中添加你的自定义 CSS 样式。

🏗️ 构建与部署

生产构建

# 构建静态文件
pnpm build

构建产物将生成在 build/ 目录中，可以部署到任何静态文件托管服务。

本地预览构建结果

# 预览构建后的站点
pnpm serve

部署选项

1. GitHub Pages

# 设置 GitHub 用户名并部署
GIT_USER=<你的GitHub用户名> pnpm deploy

2. Vercel

1. 连接 GitHub 仓库到 Vercel
2. 构建命令：pnpm build
3. 输出目录：build

3. Netlify

1. 连接 GitHub 仓库到 Netlify
2. 构建命令：pnpm build
3. 发布目录：build

4. 静态文件服务器

将 build/ 目录的内容上传到任何静态文件托管服务（如 Nginx、Apache 等）。

⚙️ 配置说明

主配置文件

docusaurus.config.ts - 站点的主要配置文件：

const config: Config = {
  title: 'Oadin Docs',
  tagline: '基于 Docusaurus 的现代化文档系统',
  favicon: 'img/favicon.ico',
  url: 'https://your-domain.com',
  baseUrl: '/',
  // 更多配置...
};

侧边栏配置

sidebars.ts - 配置文档的侧边栏结构：

const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    'intro',
    'hello',
    {
      type: 'category',
      label: '教程',
      items: ['tutorial-basics/create-a-page'],
    },
  ],
};

🛠️ 开发工具

TypeScript 检查

# 运行 TypeScript 类型检查
pnpm typecheck

清理缓存

# 清理 Docusaurus 缓存
pnpm clear

生成翻译文件

# 生成翻译模板
pnpm write-translations

📁 项目结构

oadin-docs/
├── docs/                    # 文档内容
├── src/                     # 源代码
│   ├── css/                # 样式文件
│   ├── pages/              # 自定义页面
│   └── components/         # React 组件
├── static/                  # 静态资源
├── docusaurus.config.ts     # 主配置文件
├── sidebars.ts             # 侧边栏配置
├── package.json            # 依赖配置
└── README.md               # 项目说明

🔧 常见问题

1. 端口被占用

# 指定其他端口启动
pnpm start --port 3001

2. 构建失败

# 清理缓存后重试
pnpm clear && pnpm build

3. 样式不生效

检查 src/css/custom.css 文件是否正确配置在 docusaurus.config.ts 中。

4. 文档路径问题

确保文档文件的路径和 sidebars.ts 中的配置一致。

🌐 多语言支持指南

添加英文文档

要为现有中文文档添加英文翻译版本，按照以下步骤操作：

1. 确保已启用多语言配置

首先，确保docusaurus.config.ts文件中已正确配置多语言支持：

i18n: {
  defaultLocale: 'zh-Hans',
  locales: ['zh-Hans', 'en'],
  localeConfigs: {
    'zh-Hans': {
      label: '简体中文',
      direction: 'ltr',
      htmlLang: 'zh-Hans',
    },
    en: {
      label: 'English',
      direction: 'ltr',
      htmlLang: 'en',
    },
  },
}

2. 生成翻译文件（如果尚未生成）

# 生成英文翻译文件
pnpm write-translations -- --locale en

# 生成中文翻译文件
pnpm write-translations -- --locale zh-Hans

这将在i18n/[locale]目录下创建必要的翻译文件。

3. 添加英文文档内容

英文文档应放在以下目录：

i18n/en/docusaurus-plugin-content-docs/current/

例如，如果要为docs/architecture.md创建英文版本，应创建：

i18n/en/docusaurus-plugin-content-docs/current/architecture.md

4. 翻译UI组件文本

网站界面元素的翻译位于：

• 导航栏翻译：i18n/en/docusaurus-theme-classic/navbar.json
• 页脚翻译：i18n/en/docusaurus-theme-classic/footer.json
• 其他组件翻译：i18n/en/code.json

5. 构建并测试

# 构建多语言网站
pnpm build

# 本地预览
pnpm serve

翻译文件结构

翻译文件采用JSON格式，键值对形式表示原文和译文：

{
  "link.title.Documentation": {
    "message": "Documentation",
    "description": "The title of the footer links column with title=Documentation in the footer"
  }
}

注意事项

• 确保所有页面元素（导航栏、页脚、按钮等）都有对应的翻译
• 翻译文档时保持原文格式（标题层级、列表、代码块等）
• 锚点链接(#)在不同语言之间需要相应调整

📚 相关资源

• Docusaurus 官方文档
• Markdown 语法指南
• MDX 文档
• Infima CSS 框架

🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。