updated script

Author: Chenran Jin

GITHUB_PAGES_SETUP.md

@@ -0,0 +1,91 @@
+# 发布到 GitHub Pages 指南
+
+## 快速开始
+
+### 方法 1：使用 Windows 脚本（推荐）
+
+直接运行：
+```
+bin\publish-to-github-pages.bat
+```
+
+### 方法 2：使用 Bash 脚本（Git Bash / WSL）
+
+```bash
+chmod +x bin/publish-to-github-pages
+./bin/publish-to-github-pages
+```
+
+## 首次设置
+
+### 1. 确保 GitHub Pages 已启用
+
+1. 打开你的 GitHub 仓库设置
+2. 进入 **Settings** → **Pages**
+3. 在 **Source** 下选择：
+   - Branch: `gh-pages`
+   - Folder: `/docs` 或 `/ (root)`
+4. 点击 **Save**
+
+### 2. 调整 hosting-base-path
+
+在脚本中找到这一行：
+```bash
+--hosting-base-path the-swift-programming-language-in-chinese-1
+```
+
+改为你的**仓库名称**（如果仓库名不同的话）。
+
+### 3. 第一次运行
+
+脚本会自动：
+1. 创建 `gh-pages` 分支（如果不存在）
+2. 使用 `--experimental-enable-custom-templates` 构建文档
+3. 将构建结果复制到 `gh-pages` 分支的 `docs` 目录
+4. 提交并推送到 GitHub
+
+## 访问你的文档
+
+发布成功后，访问：
+```
+https://你的用户名.github.io/the-swift-programming-language-in-chinese-1/docs/documentation/the-swift-programming-language
+```
+
+## 关键差异说明
+
+相比原版脚本的修改：
+- ✅ `TSPL.docc` → `swift-6.docc`（中文版目录）
+- ✅ 添加 `--experimental-enable-custom-templates`（启用 header/footer）
+- ✅ 移除了 redirects 复制（如果你不需要）
+- ✅ 调整了 `--hosting-base-path` 为你的仓库名
+
+## 本地预览（推荐先测试）
+
+发布前建议先本地预览：
+```bash
+# 使用之前创建的预览脚本
+preview-with-header-footer.bat
+```
+
+或手动：
+```bash
+docc preview swift-6.docc --experimental-enable-custom-templates
+```
+
+## 故障排除
+
+### 问题：没有看到 header 和 footer
+**解决**：确保构建命令包含 `--experimental-enable-custom-templates`
+
+### 问题：页面 404
+**解决**：
+1. 检查 GitHub Pages 设置中的分支和文件夹
+2. 确认 `--hosting-base-path` 与仓库名匹配
+3. 等待几分钟让 GitHub Pages 部署
+
+### 问题：样式不正确
+**解决**：检查 `swift-6.docc/header.html` 和 `footer.html` 中的资源路径
+
+## 自动化部署（可选）
+
+可以设置 GitHub Actions 自动发布。需要时可以参考官方仓库的 workflow 配置。

bin/publish-to-github-pages

@@ -0,0 +1,54 @@
+#! /bin/bash
+
+# Swift 中文版文档发布脚本 - 发布到 GitHub Pages
+# 基于 swiftlang/swift-book 的 update-book-preview 脚本修改
+
+set -eux
+
+REMOTE=${1:-origin}
+CURRENT_COMMIT_HASH="$(git rev-parse --short HEAD)"
+
+# 进入仓库根目录
+cd "$(git rev-parse --show-toplevel)"
+
+# 检出 gh-pages 分支到子目录
+git worktree add --checkout gh-pages "$REMOTE"/gh-pages
+
+# 美化 DocC JSON 输出，便于对比和版本控制
+export DOCC_JSON_PRETTYPRINT="YES"
+
+# 使用 header.html（如果需要不同版本可以先复制）
+# cp -n swift-6.docc/header-publish.html swift-6.docc/header.html
+
+# 构建文档，输出到 gh-pages/docs 子目录
+xcrun docc convert \
+    --experimental-enable-custom-templates \
+    --hosting-base-path the-swift-programming-language-in-chinese-1 \
+    --output-path "./gh-pages/docs" \
+    swift-6.docc
+
+# 如果复制了临时 header，清理掉
+# rm swift-6.docc/header.html
+
+# 提交并推送更改到 gh-pages 分支
+pushd gh-pages
+git add docs
+
+if [[ -n "$(git status --porcelain)" ]]
+then
+    echo "发现文档更新。"
+    echo "正在提交更改到 'gh-pages' 分支并推送到 $REMOTE。"
+    git commit -m "更新 GitHub Pages 文档站点到提交 '$CURRENT_COMMIT_HASH'"
+    echo
+    git push "$REMOTE" HEAD:gh-pages
+else
+    echo "没有发现文档更改。"
+fi
+
+popd
+
+git worktree remove gh-pages
+
+echo "发布完成！"
+echo "GitHub Pages 地址应该是："
+echo "https://你的用户名.github.io/the-swift-programming-language-in-chinese-1/"

bin/publish-to-github-pages.bat

@@ -0,0 +1,75 @@
+@echo off
+REM Swift 中文版文档发布脚本 - Windows 版本
+REM 发布到 GitHub Pages
+
+echo 正在发布中文版 Swift 文档到 GitHub Pages...
+echo.
+
+REM 获取当前提交哈希
+for /f "delims=" %%i in ('git rev-parse --short HEAD') do set COMMIT_HASH=%%i
+
+REM 检查 gh-pages 分支是否存在
+git show-ref --verify --quiet refs/heads/gh-pages
+if %errorlevel% neq 0 (
+    echo gh-pages 分支不存在，正在创建...
+    git checkout --orphan gh-pages
+    git rm -rf .
+    echo # GitHub Pages for Swift Chinese Documentation > README.md
+    git add README.md
+    git commit -m "Initialize gh-pages branch"
+    git push -u origin gh-pages
+    git checkout main
+    echo gh-pages 分支已创建！
+)
+
+REM 创建临时输出目录
+set TEMP_OUTPUT=gh-pages-temp
+if exist %TEMP_OUTPUT% rmdir /s /q %TEMP_OUTPUT%
+mkdir %TEMP_OUTPUT%
+
+REM 构建文档
+echo 正在构建文档...
+xcrun docc convert ^
+    --experimental-enable-custom-templates ^
+    --hosting-base-path the-swift-programming-language-in-chinese-1 ^
+    --output-path "%TEMP_OUTPUT%" ^
+    swift-6.docc
+
+if %errorlevel% neq 0 (
+    echo 构建失败！
+    pause
+    exit /b 1
+)
+
+REM 切换到 gh-pages 分支
+echo 正在切换到 gh-pages 分支...
+git checkout gh-pages
+
+REM 清空 docs 目录并复制新文件
+if exist docs rmdir /s /q docs
+mkdir docs
+xcopy /E /I /Y "%TEMP_OUTPUT%" docs
+
+REM 提交更改
+git add docs
+git diff-index --quiet HEAD --
+if %errorlevel% neq 0 (
+    echo 发现文档更新，正在提交...
+    git commit -m "更新 GitHub Pages 文档站点到提交 %COMMIT_HASH%"
+    git push origin gh-pages
+    echo 发布成功！
+) else (
+    echo 没有发现文档更改。
+)
+
+REM 切回主分支
+git checkout main
+
+REM 清理临时文件
+rmdir /s /q %TEMP_OUTPUT%
+
+echo.
+echo 完成！GitHub Pages 地址：
+echo https://你的用户名.github.io/the-swift-programming-language-in-chinese-1/docs/documentation/the-swift-programming-language
+echo.
+pause

build-with-header-footer.bat

@@ -0,0 +1,23 @@
+@echo off
+REM 构建带 header 和 footer 的中文版 Swift 文档
+
+REM 设置输出目录
+set OUTPUT_DIR=swift-book-cn
+
+REM 进入项目根目录
+cd /d "%~dp0"
+
+REM 确保使用正确的 header 文件（如果需要不同的版本可以修改）
+REM copy /Y swift-6.docc\header-publish.html swift-6.docc\header.html
+
+REM 使用 DocC 构建文档，启用自定义模板支持
+xcrun docc convert ^
+    --experimental-enable-custom-templates ^
+    --hosting-base-path swift-book ^
+    --output-path "%OUTPUT_DIR%" ^
+    swift-6.docc
+
+echo.
+echo 构建完成！输出目录：%OUTPUT_DIR%
+echo 可以使用 docc preview 预览或直接在浏览器中打开
+pause

preview-with-header-footer.bat

@@ -0,0 +1,16 @@
+@echo off
+REM 预览带 header 和 footer 的中文版 Swift 文档
+
+REM 进入项目根目录
+cd /d "%~dp0"
+
+echo 正在启动 DocC 预览服务器（带 header 和 footer）...
+echo 注意：必须使用 --experimental-enable-custom-templates 参数
+echo.
+
+REM 使用 DocC 预览，启用自定义模板支持
+xcrun docc preview swift-6.docc ^
+    --experimental-enable-custom-templates
+
+REM 如果 xcrun 不可用，尝试直接使用 docc
+REM docc preview swift-6.docc --experimental-enable-custom-templates