基于 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

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

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

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

将 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 类型检查
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               # 项目说明

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

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

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

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

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

首先，确保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',
    },
  },
}

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

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

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

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

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

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

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

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

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

# 构建多语言网站
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 文件了解详情。