元驭机器人元驭机器人Hall Lab / 教学 Wiki
维护与发布约 4 分钟阅读Markdown 原文
本页目录 6 个小节

发布网站和 Wiki

页面改好以后，我们先在本地生成一次网站，检查页面和链接，然后再推送到自己的 GitHub 仓库。当前还没有绑定远程仓库，命令里的账号和仓库名需要替换。

本地预览

在仓库根目录，用 Python 3.10+：

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\python.exe -m pip install -r requirements-site.txt
.\.venv\Scripts\python.exe scripts/build_site.py
.\.venv\Scripts\python.exe scripts/check_site.py
.\.venv\Scripts\python.exe scripts/serve_site.py --host 127.0.0.1 --port 8765

macOS/Linux 将 Python 路径改为 .venv/bin/python。打开 http://127.0.0.1:8765/，Wiki 入口为 /wiki/Home.html。服务支持视频进度拖动，主页、教程、图纸、模型、搜索和源码 ZIP 都来自同一个 website/public/。网页使用相对链接，可放在站点根目录或子目录下。

Windows 也可以用 scripts/Start-Site.ps1 在后台启动，查看完成后运行 scripts/Stop-Site.ps1。默认仅在本机监听，不会修改防火墙或云服务器。

wiki/*.md 是唯一教学内容源；网页由Markdown构建，搜索索引同时生成。无需维护第二份网页文章。互动示意在浏览器本地运行，没有后端，也不控制硬件串口。

不启动服务也可以直接打开 website/public/index.html。Logo、图纸、动画与搜索索引均为本地文件，直接打开的 Wiki 也可以搜索。图纸点开后可放大查看，动画默认暂停，可播放或单步操作。

部署到自己的云服务器

本地看完后，执行 python scripts/prepare_server_bundle.py，生成 release/cloud-server.zip。其中 site/ 是完整网页，另附 Nginx 示例配置和部署说明。把 site/ 内的内容上传到网站根目录，确认目录下直接有 index.html、wiki/、experiments/ 和资源文件。

云端只需要静态网站服务，不需要安装 Node、CAD 软件或连接传感器。按服务器已有的站点配置域名、端口和 HTTPS；使用 Nginx 时先检查配置再重载。操作步骤见 云服务器部署说明。

建立仓库

先确认 授权状态 与 发布准备。在GitHub建立空仓库后，从此项目根目录提交与推送：

git remote add origin https://github.com/YOUR-ACCOUNT/YOUR-REPO.git
git push -u origin main

把示例中的账号与仓库名换成真实值；仓库已有远程时应使用已有配置。虚拟环境、固件 build、截图和上传压缩包已忽略。website/public/ 已作为网页成品纳入跟踪，应随主仓库上传。

仓库的 .gitattributes 对原工程镜像关闭文本换行转换，以保留SHA-256；请与源码一起提交，否则Windows/Linux之间的自动换行转换可能使来源核验失败。

启用 Pages

仓库 Settings → Pages → Build and deployment → Source 选择 GitHub Actions。默认分支为 main 时，推送会运行 .github/workflows/pages.yml；其他分支需要修改工作流分支过滤。

工作流安装固定版本Markdown、运行离线测试和来源核验、生成/检查站点，然后上传Pages构件。部署作业仅对main推送或手动运行执行，PR只运行验证。首次启用后如果上一次部署失败，在Actions手动运行一次；成功URL以GitHub返回值为准。

当前工作流遵循GitHub的官方自定义Pages工作流说明，使用configure-pages、upload-pages-artifact和deploy-pages。部署需要pages写入和OIDC权限，仓库/组织还可能有环境保护规则。

发布 GitHub Wiki

Pages中的Wiki已随主页生成。如果还希望仓库顶部的 Wiki 标签出现相同内容，需要另行发布到独立的 .wiki.git 仓库。先在GitHub界面启用Wiki并创建第一篇页面，然后克隆它。

python scripts/export_wiki.py --repository https://github.com/YOUR-ACCOUNT/YOUR-REPO --branch main
git clone https://github.com/YOUR-ACCOUNT/YOUR-REPO.wiki.git ../hall-sensor-wiki

把 output/github-wiki/ 的文件复制到克隆的Wiki目录，检查差异后提交和推送。Windows可使用：

Copy-Item -Path .\output\github-wiki\* -Destination ..\hall-sensor-wiki\ -Force
git -C ..\hall-sensor-wiki add .
git -C ..\hall-sensor-wiki commit -m "Update progressive Hall sensor lessons"
git -C ..\hall-sensor-wiki push

导出脚本会把文章内 .md 互链改成Wiki页面名，把源码链接改到主仓库，把图纸缩图改到主仓库raw地址，并附侧栏和页脚。必须传真实的仓库URL和分支；直接复制 wiki/*.md 会导致独立Wiki中的源码相对链接失效。脚本不会自动推送，也不会删除已有页面。

GitHub 原生 Wiki 不运行 JavaScript。导出时，动画位置会换成对应 Pages 教程的链接，文字和图纸保留；侧栏带项目 Logo。脚本按默认 github.io 地址生成演示链接，使用自定义域名时再按实际网址调整。

GitHub Wiki是独立Git仓库，其可用范围及编辑权限见官方Wiki说明和本地编辑方法。

日常更新

改 wiki/*.md 更新教程；改 website/source/ 更新主页和交互；原图更改时同时更新预览与硬件描述。website/public/ 是已提交的生成结果，重建后需一并提交。完整说明见 UPLOAD。每次运行构建、链接检查与相关测试。固件改动单独提交，附测试记录，并更新源码清单的处理方式。贡献方法见 CONTRIBUTING。