贡献指南
感谢你对 PNTHUB 文档站点的关注！本文档将帮助你快速上手开发环境，并了解如何贡献和维护文档。
提示
如果你只想快速修复一个错别字或调整措辞，可以直接在 GitHub 上编辑对应文件并提交 Pull Request，无需搭建本地环境。
开发环境搭建
前置条件
- Node.js >= 18（推荐使用 LTS 版本）
- npm >= 9（随 Node.js 一起安装）
- Git
安装与启动
# 克隆仓库
git clone https://github.com/apkpai/rtkhub-portal.git
cd rtkhub-portal
# 安装依赖
npm install
# 启动本地开发服务器
npm start
启动后浏览器会自动打开 http://localhost:3000，支持热重载——修改文件后页面会自动刷新。
常用命令
npm start # 启动开发服务器
npm run build # 构建生产版本
npm run serve # 本地预览生产构建
npm run clear # 清除 .docusaurus 缓存
项目文件结构
rtkhub-portal/
├── docs/ # 文档 Markdown/MDX 文件
│ ├── intro.md # 文档中心
│ ├── platform/ # PNTHUB 平台、架构、源码构建、安全
│ ├── rtkhub/ # RTKHUB 快速开始、配置、部署、API、运维
│ ├── products/ # STRHUB、EPHUB、SCRHUB 文档
│ ├── tools/ # RNX2RTKP、RNX2RTCM 文档
│ └── reference/ # 端口、CLI、API 索引、版本能力等参考资料
├── src/
│ ├── components/ # 自定义 React 组件
│ ├── css/ # 全局样式
│ │ └── custom.css # 自定义 CSS 覆盖
│ └── pages/ # 独立页面（about, products 等）
├── static/
│ └── img/ # 静态图片资源
├── sidebars.ts # 侧边栏配置
├── docusaurus.config.ts # 站点全局配置
└── package.json
添加/编辑文档
新建文档
- 在
docs/platform/、docs/rtkhub/、docs/products/、docs/tools/或docs/reference/中创建.md或.mdx文件。 - 在文件顶部添加 frontmatter 元数据：
---
sidebar_position: 5
title: 文档标题
---
- 在
sidebars.ts中将新文件的文档 ID 添加到对应分类的items数组中。分类目录下的文档 ID 通常是目录/文件名，例如rtkhub/docker。 - 使用
npm start验证文档是否正常渲染。
编辑已有文档
直接修改对应的 .md 或 .mdx 文件，保存后浏览器会自动刷新。
删除文档
- 删除
docs/下的文件。 - 从
sidebars.ts中移除对应的条目。
Markdown/MDX 约定
标题层级
- 每个文档只用一个
#一级标题（H1），对应文档主标题。 - 用
##（H2）划分主要章节，###（H3）划分小节。 - 不要跳级使用标题（如直接从 H2 跳到 H4）。
Admonitions（提示框）
使用 :::type 语法创建提示框，支持以下类型：
:::tip[提示]
用于给出建议或最佳实践。
:::
:::note[注意]
用于补充说明。
:::
:::caution[注意]
用于提醒可能导致问题的操作。
:::
:::warning[警告]
用于高风险操作或不可逆行为。
:::
Tabs（标签页）
在文档顶部导入 Tab 组件，用于展示多平台或多方案的对比内容：
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="windows" label="Windows" default>
Windows 平台的操作步骤。
</TabItem>
<TabItem value="linux" label="Linux">
Linux 平台的操作步骤。
</TabItem>
</Tabs>
备注
Tab 内的 Markdown 内容必须缩进两个空格，否则可能渲染异常。
文档摘要块
使用 doc-summary 自定义 CSS 类为文档添加摘要信息：
<div class="doc-summary">
<div>
<strong>适合谁</strong>
<span>目标读者描述。</span>
</div>
<div>
<strong>你会理解</strong>
<span>读完本文能获得的知识。</span>
</div>
</div>
代码块
使用围栏代码块并标注语言：
```bash
# Bash 命令
npm start
```
```text
# 纯文本内容（配置文件等）
[Network]
dir=results
```
文件路径引用
使用 text 语言标注纯文本内容（如配置文件、目录结构），而非 bash。
本地预览
开发模式
npm start
开发模式支持热重载，适合日常编辑。
生产构建预览
npm run build
npm run serve
生产构建会执行链接检查、死链检测等，建议在提交 PR 前运行一次确认没有问题。
警告
npm run build 会在构建时抛出错误（onBrokenLinks: 'throw'），如果文档中存在无效链接，构建会失败。请务必在本地验证通过后再提交。
Pull Request 指南
提交流程
- Fork 仓库并克隆到本地。
- 从
main分支创建特性分支：git checkout -b docs/your-feature。 - 进行修改并测试。
- 提交更改并推送到你的 Fork。
- 在 GitHub 上创建 Pull Request，目标分支为
main。
提交规范
使用语义化提交信息：
docs: 添加 RNX2RTKP 快速入门指南
fix: 修正配置指南中的目录路径
style: 调整侧边栏分类顺序
常用前缀：
docs:— 新增或大改文档内容fix:— 修正错误、错别字style:— 样式或格式调整refactor:— 文档结构调整（无内容变化）
PR 检查清单
- 文档在本地
npm start中正常渲染 -
npm run build构建通过，无断链警告 - 新增文档已在
sidebars.ts中添加对应条目 - 标题层级符合规范（一个 H1，无跳级）
- 代码块标注了正确的语言
- 中英文之间有空格（如
使用 npm install而非使用npm install） - 如涉及安全修复或 P0 级别的问题，已使用主项目中的验证脚本测试（如
tools/verify_ephub_fixes.ps1）
常见问题
构建时出现断链错误
检查 docusaurus.config.ts 中 onBrokenLinks 配置。本地开发时可以临时改为 'warn' 以忽略断链，但提交前应修复所有问题。
修改 sidebars.ts 后文档不显示
运行 npm run clear 清除缓存后重新启动。
如何预览未提交的更改
开发模式下所有本地修改都会实时反映在浏览器中，无需额外操作。