# 发布网站和 Wiki

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

## 本地预览

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

```sh
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 时先检查配置再重载。操作步骤见 [云服务器部署说明](../deploy/README.md)。

## 建立仓库

先确认 [授权状态](../LICENSE.md) 与 [发布准备](Release-Checklist.md)。在GitHub建立空仓库后，从此项目根目录提交与推送：

```sh
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工作流说明](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)，使用configure-pages、upload-pages-artifact和deploy-pages。部署需要pages写入和OIDC权限，仓库/组织还可能有环境保护规则。

## 发布 GitHub Wiki

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

```sh
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可使用：

```powershell
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说明](https://docs.github.com/en/communities/documenting-your-project-with-wikis)和[本地编辑方法](https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages)。

## 日常更新

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