1# 实物照片与视频的接入23主页和站内 Wiki 的「样机照片与演示」共用一份清单；拍好后登记一次，再重新构建，就能同步显示。原生 GitHub Wiki 导出时会生成照片和视频链接。素材未登记时页面会显示「正在整理」，不会出现空白图片或假照片。45## 1. 整理素材67- 原始照片、高清视频等放 `docs/media/originals/`。此目录已加入 `.gitignore`，站点构建也会跳过；请自行保留原片备份。8- 选好公开的照片和压缩后的视频，放入 `docs/media/assets/`（目录不存在时自行新建）。建议照片为 JPG、PNG 或 WebP，视频为 MP4（H.264 视频、AAC 音频，兼容性较好）或 WebM。建议使用英文、数字和连字符命名。9- 网页直接托管视频会增加站点和下载包体积。只选短片并压缩，先检查本地播放效果和部署平台的文件大小限制。视频只会在读者点击后播放。10- 拍摄时记录板卡版本、固件版本、上位机版本以及场景。当前仓库固件是 2026-10-27 的快照；原始工程此后有修改，演示时确认实际版本和上位机配套。1112## 2. 登记要展示的文件1314打开 [manifest.json](manifest.json)，把需要在主页和样机记录中展示的文件加入数组，例如：1516```json17[18 {19 "type": "photo",20 "file": "docs/media/assets/linear-board.jpg",21 "title": "直线位移样机",22 "description": "HallPos 板与测试结构，固件版本：请填写。",23 "alt": "直线样机及安装在测试结构上的电路板"24 },25 {26 "type": "video",27 "file": "docs/media/assets/linear-demo.mp4",28 "title": "直线运动演示",29 "description": "磁铁移动时观察位置读数；板卡和软件版本请填写。",30 "alt": "磁铁沿滑台移动，电脑显示对应位置"31 }32]33```3435`type` 只能是 `photo` 或 `video`；`file` 必须指向仓库内 `docs/media/assets/` 中已存在的文件。顺序就是页面展示顺序。标题和说明面向读者；`alt` 是无法看到画面时的文字描述。示例文件名只是格式示意，替换为实际文件名，不要保留不存在的文件条目，否则构建会报错。3637构建只复制清单中登记的展示素材；未登记素材不会进入 Pages 或网站内的源码下载包。已登记的视频会随站点发布，也会进入源码下载包；如不希望公开视频文件，不要登记它。原生 GitHub Wiki 显示图片，并提供指向仓库视频文件的链接。3839仅用于教程的特写放在 `docs/assets/hardware/`，由对应的 Wiki 文章直接引用。当前图片由项目作者提供原照，经转正、裁剪和压缩后保存为 WebP。4041| 照片 | 原图 |42| --- | --- |43| 两块打样板 | `boards-together.jpg` |44| HallPos 直线样机 | `hallpos-assembled.jpg` |45| Encoder 旋转样机 | `encoder-assembled.jpg` |46| HallPos 元件面 | `hallpos-top.jpg` |47| HallPos 接口近照 | `hallpos-connectors.jpg` |48| Encoder 元件面 | `encoder-top.jpg` |49| USB 转 RS485 接线 | `rs485-wiring.jpg` |5051## 3. 构建并检查5253在仓库根目录运行：5455```sh56python -m pip install -r requirements-site.txt57python scripts/build_site.py58python scripts/check_site.py59```6061构建会重新生成 `website/public/`，其中手工改动会被覆盖；请先确认没有需要保留的修改。在浏览器打开 `website/public/index.html` 和 `website/public/wiki/Prototype-Showcase.html`，检查图片、视频、文字和手机屏幕布局；要导出 GitHub Wiki 时，按 `scripts/export_wiki.py --help` 指定仓库地址，重新运行导出。确认公开内容后再提交清单、登记的发布素材和生成的网站。
元驭机器人Hall 传感器教学下载原文件