参与编写

字数

980 字

阅读时间

4 分钟

发现内容过期、写错、或者想补一节，都欢迎直接改。错别字也算贡献。

最快的方式：在网页上改

翻到页面底部，点 「在 GitHub 上编辑此页面」
GitHub 会自动帮你 fork 一份并打开编辑器
改完写一句说明，点 Propose changes
提交 Pull Request，等合并

不用装任何软件，浏览器里就能完成。

本地跑起来

需要改结构、加组件、或者一次改很多页时：

# 需要 Node.js 20+ 和 pnpm
git clone https://github.com/asidjwiaijd/rm-hardware-wiki.git
cd rm-hardware-wiki
pnpm install
pnpm dev

打开终端里给出的地址即可预览，保存文件会自动刷新。

其他命令：

pnpm build     # 构建静态站点，产物在 docs/.vitepress/dist
pnpm preview   # 本地预览构建产物
pnpm format    # 格式化所有 md / ts / vue

📖 信息

本地开发时页面底部的「贡献者」是空的，这是正常的 —— 为了不频繁请求 GitHub API，只有生产构建才会去拉贡献者列表。如果要在本地验证这一块，先 export GITHUB_TOKEN="你的 token" 再启动。

目录约定

txt

docs/
  intro.md              ← 顶层页面直接放 docs/ 下
  training/             ← 一个目录就是侧边栏的一个分组
    index.md            ← 目录的封面页，标题会成为分组名
    week1.md
  .vitepress/
    data/schedule.json  ← 周计划数据，改这里就能更新"本周进度"

新建一个页面 = 新建一个 md 文件，侧边栏会自动出现，不需要改配置。

frontmatter 字段

写在文件最上方的 --- 之间：

---
order: 11
title: 第 1 周 · 环境、器件与电学入门
level: 入门
---

字段	作用
`order`	侧边栏排序，数字越小越靠前。不写默认 100
`title`	侧边栏和标签页标题。不写则取正文第一个 `#` 标题
`level`	侧边栏难度徽标，可选 `入门` / `进阶` / `核心` / `待补充`
`exclude`	设为 `true` 则不出现在侧边栏
`comment`	设为 `false` 则本页不显示评论区

⚠️ 注意

只有标题、没有正文的页面会被自动排除，不会出现在侧边栏，也不会被构建。

想先占个位，用 <ToDo>还没写</ToDo> 写一句话进去。

能用的 Markdown 扩展

除了标准 Markdown，还可以用：

写法	效果
`==高亮==`	高亮，用于标注搜索关键词和关键区分
`:::tip` / `:::warning` / `:::danger` / `:::info`	提示框
`:::details 标题`	可折叠块，适合放长表格、长流程
```mermaid	流程图、时序图，见第 3 周的电源树
`::: timeline 日期`	时间线，见培训计划
`[^1]`	脚注，用来标注来源
$E = mc^2$	KaTeX 公式
`<Note>需要验证</Note>`	行内存疑标记
`<ToDo>...</ToDo>`	整段待补充标记
`[[其他页面]]`	双向链接，按文件名跳转

写作约定

简单几条

短句，一句一个信息点。不要写"总的来说""值得注意的是"这类铺垫
涉及规则、参数、安全的内容要标来源，用脚注 [^1]
加粗留给"必须"和"禁止"，数字和日期不要加粗
不确定的写"通常""一般"，或者直接用 <Note>需要验证</Note> 标出来
删除线内容通常应该直接删掉，而不是留着

完整的风格约定见仓库里的 .agents/skills/rm-hw-doc-style/SKILL.md，用 AI 辅助写作时可以让它先读这个文件。

提交前跑一下格式检查

pnpm format

仓库配了 husky pre-commit 钩子，提交时会自动跑一遍。CI 上也会检查，格式不对会挂。

贡献者

asidjwiaijd

页面历史

最后编辑于大约 1 小时前

查看完整历史

参与编写 ​

最快的方式：在网页上改 ​

本地跑起来 ​

目录约定 ​

frontmatter 字段 ​

能用的 Markdown 扩展 ​

写作约定 ​

提交前跑一下格式检查 ​

贡献者