同步与发布

源码同步与静态发布是两项独立操作：同步处理 Markdown、站点配置、图片与主题源文件；发布处理公开构建生成的静态文件。同步成功不会自动让公网网站更新。

发布前检查

在包含 bookx.yml 的工作区执行：

bookx validate
bookx build

validate 执行内容、主题、链接、资源及产物校验，但不替换当前正式输出。build 成功后通过“发布预览”检查网站，特别是内部链接、图片、文档目录和手机布局。

正式发布和 --dry-run 都会先重新公开构建；构建失败时停止发布并保留旧产物。不要把 .bookx/preview/ 的全部内容预览当作发布源。

Git 源码同步

在工作台“发布”页配置同步，或编辑本地 .bookx/local.yml：

sync:
  type: git
  remote: origin
  url: git@github.com:owner/source.git
  branch: main

执行：

bookx sync --workspace ./my-site

BookX 会按同步流程提交本地改动、整合远程更新并推送。遇到未解决冲突时停止，先查看冲突文件并确认正确内容，再继续同步。使用 Git SSH 地址时，需要本机 Git 已能完成相应认证。

只有非空 sync.url 才启用桌面启动自动更新；清空地址可停止后续启动更新。私有内容和草稿仍可能随源码同步，“仅本地”文档目录另有排除规则。工作台会保留已有 .gitignore 并补充生成物和本地设置的忽略项。

配置发布目标

发布目标也保存在 .bookx/local.yml，以名称区分。下面的三个目标可以放在同一个 publish 下：

publish:
  local-copy:
    type: local
    path: ./published-site
  pages:
    type: git
    remote: git@github.com:owner/site.git
    branch: gh-pages
  production:
    type: ssh
    host: example.com
    port: 22
    user: deploy
    path: /var/www/blog
    key_file: /path/to/id_ed25519
    use_agent: false
    timeout: 30s

将示例地址替换为实际目标。先检查计划，再执行发布；命令行选项放在目标名称之前：

bookx publish --dry-run production
bookx publish production

Git 产物分支应与源码分支区分。发布目录应专门承载该站点，不要混入需要人工长期维护的其他文件。

SSH 认证与后置命令

SSH 支持私钥文件或 SSH Agent。使用 Agent 时设置 use_agent: true 并确保本机 Agent 中已有可用身份。不要把私钥内容、口令或其他秘密写入 bookx.yml、主题或文档。

当前实现没有读取 known_hosts，也没有验证服务器主机指纹；旧文档中“严格校验主机”的说明不适用，填写 known_hosts 不会启用校验。主机身份校验已单独列为待办。

如需上传成功后执行命令，可以在 SSH 目标中增加 after_publish 字符串列表。命令按顺序原样交给远端执行；BookX 记录输出、退出状态和超时。仅填写你已经确认需要的命令。后置命令失败不代表已经上传的文件会自动回滚。

私有源码与公开 Pages 仓库

建议使用两个仓库：私有源码仓库保存 Markdown、图片、配置与主题源文件，作为 sync.url；独立公开仓库保存公开构建的静态文件，作为 Git 发布目标。源码同步可能包含私有内容和草稿，公开发布会按内容状态过滤。

使用上面的 pages 发布目标时，先将 remote 改为自己的公开仓库地址，再在本机执行 bookx publish pages。BookX 会重新构建并将 dist/ 内的文件提交到目标仓库的 gh-pages 分支根目录，不会额外套一层 dist/。发布会替换目标分支中的文件，不要在该分支手工维护工作流或其他需要保留的文件。

首次发布创建分支后，在公开仓库的 Settings → Pages 中选择 Deploy from a branch，分支选择 gh-pages，目录选择 /(root)。以后发布更新该分支，由 GitHub Pages 部署静态网站，无需自定义 Pages 工作流。发布来源的设置见 GitHub 官方说明。

项目 Pages（例如 https://yourname.github.io/your-repo/）设置 site.base_url: https://yourname.github.io 和 site.base_path: /your-repo；用户主页或根域名部署使用空 base_path。具体配置见站点配置。

使用 giscus 时，在公开产物仓库开启 Discussions、安装 giscus 应用，并在站点评论配置中填写该仓库及讨论分类信息。评论保存在 GitHub Discussions 中，不是 dist/ 内的文件，静态产物更新不会删除讨论。配置要求见 giscus 官方说明。

发布后检查

• 打开首页、文章与一个深层文档，确认 URL 和导航正常。
• 打开搜索并滚动归档，检查按需请求的 JSON 是否可以访问。
• 检查图片、CSS 和 JS，子路径部署尤其要确认地址前缀。
• 查看部署日志，区分构建失败、认证失败和上传后的命令失败。

.bookx/local.yml 属于本地配置，默认不进入 Git；迁移到另一台机器时需要重新准备同步／发布目标和认证环境。