# 实物照片与视频的接入

主页和站内 Wiki 的「样机照片与演示」共用一份清单；拍好后登记一次，再重新构建，就能同步显示。原生 GitHub Wiki 导出时会生成照片和视频链接。素材未登记时页面会显示「正在整理」，不会出现空白图片或假照片。

## 1. 整理素材

- 原始照片、高清视频等放 `docs/media/originals/`。此目录已加入 `.gitignore`，站点构建也会跳过；请自行保留原片备份。
- 选好公开的照片和压缩后的视频，放入 `docs/media/assets/`（目录不存在时自行新建）。建议照片为 JPG、PNG 或 WebP，视频为 MP4（H.264 视频、AAC 音频，兼容性较好）或 WebM。建议使用英文、数字和连字符命名。
- 网页直接托管视频会增加站点和下载包体积。只选短片并压缩，先检查本地播放效果和部署平台的文件大小限制。视频只会在读者点击后播放。
- 拍摄时记录板卡版本、固件版本、上位机版本以及场景。当前仓库固件是 2026-10-27 的快照；原始工程此后有修改，演示时确认实际版本和上位机配套。

## 2. 登记要展示的文件

打开 [manifest.json](manifest.json)，把需要在主页和样机记录中展示的文件加入数组，例如：

```json
[
  {
    "type": "photo",
    "file": "docs/media/assets/linear-board.jpg",
    "title": "直线位移样机",
    "description": "HallPos 板与测试结构，固件版本：请填写。",
    "alt": "直线样机及安装在测试结构上的电路板"
  },
  {
    "type": "video",
    "file": "docs/media/assets/linear-demo.mp4",
    "title": "直线运动演示",
    "description": "磁铁移动时观察位置读数；板卡和软件版本请填写。",
    "alt": "磁铁沿滑台移动，电脑显示对应位置"
  }
]
```

`type` 只能是 `photo` 或 `video`；`file` 必须指向仓库内 `docs/media/assets/` 中已存在的文件。顺序就是页面展示顺序。标题和说明面向读者；`alt` 是无法看到画面时的文字描述。示例文件名只是格式示意，替换为实际文件名，不要保留不存在的文件条目，否则构建会报错。

构建只复制清单中登记的展示素材；未登记素材不会进入 Pages 或网站内的源码下载包。已登记的视频会随站点发布，也会进入源码下载包；如不希望公开视频文件，不要登记它。原生 GitHub Wiki 显示图片，并提供指向仓库视频文件的链接。

仅用于教程的特写放在 `docs/assets/hardware/`，由对应的 Wiki 文章直接引用。当前图片由项目作者提供原照，经转正、裁剪和压缩后保存为 WebP。

| 照片 | 原图 |
| --- | --- |
| 两块打样板 | `boards-together.jpg` |
| HallPos 直线样机 | `hallpos-assembled.jpg` |
| Encoder 旋转样机 | `encoder-assembled.jpg` |
| HallPos 元件面 | `hallpos-top.jpg` |
| HallPos 接口近照 | `hallpos-connectors.jpg` |
| Encoder 元件面 | `encoder-top.jpg` |
| USB 转 RS485 接线 | `rs485-wiring.jpg` |

## 3. 构建并检查

在仓库根目录运行：

```sh
python -m pip install -r requirements-site.txt
python scripts/build_site.py
python scripts/check_site.py
```

构建会重新生成 `website/public/`，其中手工改动会被覆盖；请先确认没有需要保留的修改。在浏览器打开 `website/public/index.html` 和 `website/public/wiki/Prototype-Showcase.html`，检查图片、视频、文字和手机屏幕布局；要导出 GitHub Wiki 时，按 `scripts/export_wiki.py --help` 指定仓库地址，重新运行导出。确认公开内容后再提交清单、登记的发布素材和生成的网站。