|
| 1 | +# RocketMQ-Rust 网站 |
| 2 | + |
| 3 | +RocketMQ-Rust 的官方文档网站,使用 Docusaurus 3.9.2 构建。 |
| 4 | + |
| 5 | +## 🚀 技术栈 |
| 6 | + |
| 7 | +- **框架**: [Docusaurus 3.9.2](https://docusaurus.io/) |
| 8 | +- **语言**: TypeScript |
| 9 | +- **Node 版本**: v24.13.0 (参见 `.nvmrc`) |
| 10 | +- **样式**: CSS Modules + 自定义 CSS |
| 11 | + |
| 12 | +## 📋 前置要求 |
| 13 | + |
| 14 | +- Node.js v24.13.0 或更高版本 |
| 15 | +- npm 或 yarn 包管理器 |
| 16 | + |
| 17 | +## 🛠️ 安装 |
| 18 | + |
| 19 | +```bash |
| 20 | +# 安装依赖 |
| 21 | +npm install |
| 22 | +``` |
| 23 | + |
| 24 | +## 💻 开发 |
| 25 | + |
| 26 | +### 启动开发服务器 |
| 27 | + |
| 28 | +```bash |
| 29 | +# 启动英文版本(默认) |
| 30 | +npm run start |
| 31 | + |
| 32 | +# 启动中文版本 |
| 33 | +npm run start:zh |
| 34 | +``` |
| 35 | + |
| 36 | +网站将在以下地址可用: |
| 37 | + |
| 38 | +- **英文**: http://localhost:3000/ |
| 39 | +- **中文**: http://localhost:3000/zh-CN/ |
| 40 | + |
| 41 | +### 生产构建 |
| 42 | + |
| 43 | +```bash |
| 44 | +# 构建所有语言版本 |
| 45 | +npm run build |
| 46 | + |
| 47 | +# 构建特定语言版本 |
| 48 | +npm run build -- --locale en |
| 49 | +npm run build -- --locale zh-CN |
| 50 | +``` |
| 51 | + |
| 52 | +### 清理缓存 |
| 53 | + |
| 54 | +```bash |
| 55 | +npm run clear |
| 56 | +``` |
| 57 | + |
| 58 | +## 🌍 国际化 (i18n) |
| 59 | + |
| 60 | +本网站支持两种语言: |
| 61 | + |
| 62 | +- **English** (默认): `/` |
| 63 | +- **简体中文**: `/zh-CN/` |
| 64 | + |
| 65 | +### 翻译文件结构 |
| 66 | + |
| 67 | +``` |
| 68 | +i18n/ |
| 69 | +├── en/ |
| 70 | +│ ├── code.json # UI 文本翻译 |
| 71 | +│ ├── docusaurus-theme-classic/ # 主题翻译 |
| 72 | +│ └── docusaurus-plugin-content-docs/ |
| 73 | +└── zh-CN/ |
| 74 | + ├── code.json |
| 75 | + ├── docusaurus-theme-classic/ |
| 76 | + │ ├── navbar.json # 导航栏翻译 |
| 77 | + │ └── footer.json # 页脚翻译 |
| 78 | + └── docusaurus-plugin-content-docs/ |
| 79 | + └── current/ # 翻译后的文档 |
| 80 | +``` |
| 81 | + |
| 82 | +### 添加翻译 |
| 83 | + |
| 84 | +1. **UI 文本**: 编辑 `i18n/{locale}/code.json` |
| 85 | +2. **导航栏/页脚**: 编辑 `i18n/{locale}/docusaurus-theme-classic/` 中的文件 |
| 86 | +3. **文档**: 在 `i18n/{locale}/docusaurus-plugin-content-docs/current/` 中添加/编辑文件 |
| 87 | + |
| 88 | +## 📁 项目结构 |
| 89 | + |
| 90 | +``` |
| 91 | +rocketmq-website/ |
| 92 | +├── docs/ # 文档源文件(英文) |
| 93 | +│ ├── author.md |
| 94 | +│ ├── introduction.md |
| 95 | +│ ├── getting-started/ |
| 96 | +│ ├── architecture/ |
| 97 | +│ ├── producer/ |
| 98 | +│ ├── consumer/ |
| 99 | +│ ├── configuration/ |
| 100 | +│ ├── contributing/ |
| 101 | +│ └── faq/ |
| 102 | +├── releases/ # 版本发布说明 |
| 103 | +│ └── 2024-01-28-v0.1.0.md → 2025-12-07-v0.7.0.md |
| 104 | +├── i18n/ # 国际化文件 |
| 105 | +│ ├── en/ # 英文翻译 |
| 106 | +│ └── zh-CN/ # 中文翻译 |
| 107 | +├── src/ # 自定义 React 组件 |
| 108 | +│ ├── components/ # UI 组件 |
| 109 | +│ ├── css/ # 自定义样式 |
| 110 | +│ ├── pages/ # 自定义页面 |
| 111 | +│ └── theme/ # 主题定制 |
| 112 | +├── static/ # 静态资源(图片、CNAME 等) |
| 113 | +├── .docusaurus/ # 构建输出(自动生成) |
| 114 | +├── docusaurus.config.ts # Docusaurus 配置 |
| 115 | +├── sidebars.ts # 侧边栏配置 |
| 116 | +├── package.json # 依赖和脚本 |
| 117 | +└── tsconfig.json # TypeScript 配置 |
| 118 | +``` |
| 119 | + |
| 120 | +详细结构请参见 [PROJECT_STRUCTURE_zh-CN.md](./PROJECT_STRUCTURE_zh-CN.md)。 |
| 121 | + |
| 122 | +## 🎨 自定义 |
| 123 | + |
| 124 | +### 主题颜色 |
| 125 | + |
| 126 | +编辑 `src/css/custom.css` 来自定义主题颜色和样式。 |
| 127 | + |
| 128 | +### 组件 |
| 129 | + |
| 130 | +自定义 React 组件位于 `src/components/`: |
| 131 | + |
| 132 | +- `HomepageFeatures.tsx` - 首页特性卡片 |
| 133 | +- `DeveloperStyleHero.tsx` - 开发者风格的 Hero 区块 |
| 134 | +- `AnnouncementBanner.tsx` - 全站公告横幅 |
| 135 | +- `DevWarningBanner.tsx` - 开发环境警告横幅 |
| 136 | +- `OrbBackground.tsx` - 动画球体背景效果 |
| 137 | +- `SimpleOrb.tsx` - 简单球体组件 |
| 138 | + |
| 139 | +## 📝 编写文档 |
| 140 | + |
| 141 | +1. 在 `docs/` 目录中创建/编辑 Markdown 文件 |
| 142 | +2. 使用 `_category_.json` 文件添加分类元数据 |
| 143 | +3. 对于中文翻译,在 `i18n/zh-CN/docusaurus-plugin-content-docs/current/` 中创建对应文件 |
| 144 | + |
| 145 | +### 文档 Frontmatter 示例 |
| 146 | + |
| 147 | +```markdown |
| 148 | +--- |
| 149 | +sidebar_position: 1 |
| 150 | +title: 你的标题 |
| 151 | +description: 你的描述 |
| 152 | +--- |
| 153 | + |
| 154 | +# 你的内容 |
| 155 | +``` |
| 156 | + |
| 157 | +## 🚢 部署 |
| 158 | + |
| 159 | +网站配置为部署到 GitHub Pages: |
| 160 | + |
| 161 | +```bash |
| 162 | +npm run deploy |
| 163 | +``` |
| 164 | + |
| 165 | +配置信息: |
| 166 | + |
| 167 | +- 组织: `apache` |
| 168 | +- 项目: `rocketmq-rust` |
| 169 | +- 分支: `gh-pages` |
| 170 | + |
| 171 | +## 📚 其他资源 |
| 172 | + |
| 173 | +- [Docusaurus 文档](https://docusaurus.io/docs) |
| 174 | +- [RocketMQ-Rust 仓库](https://github.com/mxsm/rocketmq-rust) |
| 175 | +- [项目结构](./PROJECT_STRUCTURE_zh-CN.md) |
| 176 | +- [快速开始指南](QUICKSTART_zh-CN.md) |
| 177 | + |
| 178 | +## 🤝 贡献 |
| 179 | + |
| 180 | +欢迎贡献!在提交 Pull Request 之前,请阅读我们的[贡献指南](../CONTRIBUTING.md)。 |
| 181 | + |
| 182 | +### 帮助翻译 |
| 183 | + |
| 184 | +如果您想帮助翻译文档,请: |
| 185 | + |
| 186 | +1. 检查 `i18n/zh-CN/` 中现有的翻译文件 |
| 187 | +2. 提交包含您翻译的 Issue 或 Pull Request |
| 188 | +3. 查看我们的 [GitHub Issues](https://github.com/mxsm/rocketmq-rust/issues/new/choose) 了解翻译需求 |
| 189 | + |
| 190 | +## 📄 许可证 |
| 191 | + |
| 192 | +本项目与 RocketMQ-Rust 使用相同的许可证。详情请参见根目录中的 [LICENSE](../LICENSE-APACHE) 文件。 |
| 193 | + |
| 194 | +## 📧 联系方式 |
| 195 | + |
| 196 | +- GitHub: https://github.com/mxsm/rocketmq-rust |
| 197 | +- Issues: https://github.com/mxsm/rocketmq-rust/issues |
| 198 | + |
| 199 | +--- |
| 200 | + |
| 201 | +使用 [Docusaurus](https://docusaurus.io/) 用 ❤️ 构建 |
| 202 | + |
| 203 | +基于 Apache License 2.0 许可。详情请参见 [LICENSE](LICENSE)。 |
| 204 | + |
| 205 | +## 链接 |
| 206 | + |
| 207 | +- [RocketMQ-Rust GitHub](https://github.com/mxsm/rocketmq-rust) |
| 208 | +- [Apache RocketMQ](https://rocketmq.apache.org/) |
| 209 | +- [Docusaurus 文档](https://docusaurus.io/docs) |
| 210 | + |
| 211 | +## 支持 |
| 212 | + |
| 213 | +- GitHub Issues: https://github.com/mxsm/rocketmq-rust/issues |
| 214 | +- 邮件列表: general@mxsm.apache.org |
0 commit comments