如何维护自己的中文笔记
目录约定
| 目录 | 放什么 |
|---|---|
docs/start/ | 学习路线与环境 |
docs/esp32/ | 板卡实践与排错 |
docs/concepts/ | Zephyr 基础概念 |
docs/lab/ | 自己的实验记录 |
docs/reference/ | 官方资料入口、英文阅读页 |
docs/site/ | 写作与部署说明 |
static/img/ | LOGO、截图、接线图 |
static/reference/ | 固定版本英文原文与许可证 |
templates/ | 可复制的笔记模板 |
design/ | 视觉设计说明 |
scripts/ | 资料同步工具 |
本地写作
cd ~/Projects/zephyr-docs
npm start -- --host 127.0.0.1
浏览器打开 http://localhost:3000。修改 docs/ 下的 Markdown 后，开发服务器通常会自动刷新。
页面以如下 front matter 开头：
---
title: "我的实验标题"
---
正文使用 Markdown，新增文件后在 sidebars.js 添加对应文档 ID。不要把代码中的尖括号裸写在正文中，使用反引号或代码块，避免被 MDX 解析成标签。
提交前检查
npm run build
npm run serve -- --host 127.0.0.1
构建开启内部链接错误检查。需要更新官方资料时执行 npm run sources:fetch，检查 static/reference/zephyr-v4.2.0/manifest.json 的来源与 SHA-256。
升级 Zephyr 应新增版本目录，并同时核对中文步骤、board target 和原文，不要静默把 v4.2.0 的内容替换成 latest。