# 宿主集成

将完整的 `website/` 目录复制到宿主仓库根目录。宿主内容保留在该目录之外，因此以后更换或更新发布实现时，无需移动原始笔记。

## 无需安装工具链即可部署

宿主中必须已有至少一篇公开笔记，例如 `docs/Start.md`：

```yaml
---
publish: true
title: Documentation
---
```

在 macOS、Linux 或 WSL 中，从宿主仓库根目录运行：

```sh
website/bin/integrate
```

在原生 Windows 的命令提示符中运行：

```bat
website\bin\integrate.cmd
```

也可以在 PowerShell 中运行：

```powershell
.\website\bin\integrate.cmd
```

CMD 启动器会优先使用 PowerShell 7；如果系统没有安装，则回退到 Windows PowerShell 5.1，并且不会修改计算机的执行策略。也可以直接调用适配器：

```powershell
.\website\bin\integrate.ps1
```

该命令不需要 Ruby 或 Node.js。默认内容目录为 `docs/`，默认主题为 `minimal`。它会创建 `.github/jekyll-obsidian.yml` 并生成 `.github/workflows/pages.yml`，但不会访问 GitHub 或修改仓库设置。

随后打开 **Settings → Pages → Build and deployment**，将 **Source** 设为 **GitHub Actions**，提交生成的文件并推送。GitHub Actions 会安装 Ruby、Node.js、依赖和 Chromium，再构建并部署站点。

**Verify and deploy Pages** 成功后，可以从其 `deploy` 作业或 **Settings → Pages** 打开站点。普通项目仓库使用 `https://<owner>.github.io/<repository>/`；名称为 `<owner>.github.io` 的仓库使用 `https://<owner>.github.io/`。配置自定义域名后，该域名会取代默认地址。工作流如何取得并应用最终 URL，详见 [[Deployment|部署]]。

## 选择内容目录与主题

两个平台适配器接受相同选项：

```text
--source PATH
--theme minimal|docs
--check
--force-workflow
--help
```

例如：

```sh
website/bin/integrate --source handbook --theme minimal
website/bin/integrate --check
```

Windows 路径分隔符会在写入可移植配置前完成规范化：

```powershell
.\website\bin\integrate.cmd --source "Documentation\User Guide" --theme docs
```

内容目录必须是仓库中已经存在的相对目录。路径遍历、与站点重叠、符号链接、Windows junction、reparse point 和路径大小写不一致都会被拒绝。内容根目录及其所有子目录都可以没有 `index.md`。物理 `index.md` 不存在时，同级且文件名精确为 `README.md` 的公开笔记会承担相同作用；已有的 `index.md` 即使未发布也保持优先。无依赖命令负责校验集成路径；Actions 中的编译器继续负责 YAML、路由、链接、附件和发布规则，并要求发布策略至少选中一篇笔记。

主题标识只支持 `minimal` 和 `docs`。

## 自定义宿主配置

生成的宿主配置包含一个托管块：

```yaml
title: My Project Documentation

website:
  # jekyll-obsidian:managed-start
  source: docs
  theme: minimal
  # jekyll-obsidian:managed-end
  repository: ""
  edit_branch: main
  content:
    publish_by_default: []
    default_type: doc
    directories:
      post: []
      doc: []
```

`integrate` 只更新标记之间的 `source` 和 `theme` 行，其他配置项和注释都归宿主管理，其中包括所有主题都能使用的 `website.comments`、`website.i18n` 和 `website.analytics` 映射。评论需要仓库所有者另行配置 GitHub Discussions 与 Giscus；流量统计默认关闭。新宿主的 `publish_by_default` 为空，因此笔记需要显式设置 `publish: true`。添加 `.` 可以默认发布整个内容树，也可以列出一个或多个相对目录。生成的内容默认值会把 `docs/` 直属的已发布文件分类为文档，所以 `docs/guide.md` 被发布后会出现在 Docs 导航中。

发布接口是根级 `website:` 映射。`integrate` 要求只存在一个受管的 `website:` 根；托管标记缺失或格式错误时，它会安全失败。

配置优先级依次为 `website/_config.yml`、`.github/jekyll-obsidian.yml`、显式的 `bin/build` 与 Pages 值。`bin/build` 会把 Jekyll 的 source、实现目录、缓存、目标目录和安全设置固定在 `website/` 中，宿主配置无法移动这些路径或绕过适配器。

生成的工作流完全由工具管理。更新 `website/` 或更改内容目录后，请重新运行 `integrate`。已有但不受管理的 `pages.yml` 会触发安全失败；检查其内容后，只有确定需要替换时才使用 `--force-workflow`。只读的 `--check` 模式会报告偏差但不写文件，CI 开始时也会运行它。

宿主已有配置但缺少托管标记时，命令会打印需要合并的配置块，并保持两个文件不变。添加标记后，再次运行同一命令。省略的参数会保留当前托管值。

## 更新带 tag 的安装

复制的 `website/` 工作区属于 `jekyll-obsidian`，但它位于具有独立 Git 历史的宿主仓库中。不要把本项目添加为 upstream remote，也不要对宿主运行指向本项目的 `git pull`。请使用已经安装的命令更新：

```sh
website/bin/update --check
website/bin/update
website/bin/update --to 0.1.0
```

原生 Windows 可以通过 CMD 启动器使用相同选项：

```bat
website\bin\update.cmd --check
website\bin\update.cmd
```

未提供 `--to` 时，命令会从不可变的附注标签（annotated tag）`vX.Y.Z` 中选择最新的官方稳定版本。`X.Y.Z` 是语义化版本（Semantic Versioning）的核心版本：每个数字标识符要么是 `0`，要么以 `1` 至 `9` 开头。公开接口仍处于初始开发阶段时，版本使用 `0.y.z`。发布日期写入发行说明，不写进版本号。目标可以是当前已安装版本，也可以向前更新，但不能降级。`--check` 不写文件。安装已经是目标版本时返回 `0`，存在更新或可首次记录来源时返回 `2`，参数无效、本地偏离、网络失败或发行版本无效时返回 `1`。

`--to` 接受不含前缀 `v` 的官方稳定核心版本；上面的 `0.1.0` 只用于展示格式。带预发布标识符或构建元数据的标签，例如 `v0.2.0-rc.1` 或 `v0.2.0+sha.abcdef`，不属于官方稳定更新通道。更新器会拒绝把它们作为目标，默认选择时也会忽略。没有稳定版本时，命令会报告该状态，并保持宿主不变。安装必须与某个官方标签匹配，严格更新才能建立或验证其来源。

更新器需要 Git，但不需要 Ruby 或 Node.js。它只会把官方仓库获取到隔离的事务目录中，不会修改宿主的 remote、ref、分支、索引、提交或 GitHub 设置。它会更新 `website/` 中由 release 管理的跟踪文件、托管配置块、生成的 Pages 工作流和 `.github/jekyll-obsidian.lock`。安装版本与目标版本都忽略的文件会保持不变；如果目标新增的跟踪路径会覆盖本地忽略状态，更新会安全失败。

更新前，请提交或撤销对托管工作区、工作流和锁文件的旧修改。无关的内容更改和托管块外的配置可以继续保持未提交。命令会拒绝 `website/` 中已提交的自定义、暂存或未暂存的托管文件修改，以及未忽略的额外文件；它不提供强制或合并模式。应把需要保留的自定义移动到宿主配置或内容目录。

没有来源锁的安装只有在已提交 `website/` 的路径与内容集合完全匹配其内置版本对应的官方标签时，才能被接管。未带标签的检出无法证明来源。没有匹配标签时，请先用完整的带标签快照替换一次 `website/`，重新运行 `integrate`，然后再次运行 `update`。发行标签不可变；已安装标签后续被删除或移动都会被视为错误。

目标 release 会先在影子宿主中生成并检查集成文件，之后才修改真实宿主。应用阶段会使用备份与事务日志支持回滚。后续命令只有在记录的旧文件或新文件摘要完全匹配时，才会恢复中断的事务；状态不明确时会保留现场供检查，不会直接覆盖。更新成功后，请检查 `git diff`，在本地预览前运行 `website/bin/setup`，并自行提交托管文件。

## 让编辑器状态留在本地

编译器和 watcher 会排除 `.obsidian/` 与 `.trash/`，但仓库读者仍能看到所有已提交文件。配置的内容目录尚未忽略这些文件时，请添加对应规则：

```gitignore
docs/.obsidian/workspace*.json
docs/.trash/
```

只有被 `publish: true` 或 `website.content.publish_by_default` 选中的笔记才会进入生成站点，选中范围内的笔记仍可通过 `publish: false` 排除。这些开关不是仓库隐私机制。不要把密钥或私密记录提交到他人可读的仓库。

## 可选的本地开发

部署不需要本地工具链。只有需要本地预览或测试时，才安装 Ruby 4.0.x 和 Node.js 26.x：

```sh
website/bin/setup
website/bin/dev
```

本指南中的原生 Windows 支持覆盖集成与部署。本地 Jekyll 开发命令请在 WSL 中运行。接下来可以阅读 [[Customization|自定义]]或 [[Deployment|部署]]。

## 排查问题

- 编译器报告内容目录没有公开笔记时，请为一篇笔记添加未加引号的顶层 `publish: true`，或在 `website.content.publish_by_default` 下配置一个目录。
- 命令报告站点重叠时，请把宿主内容放在 `website/` 之外。只有项目自带的 `website/docs/` 示例允许位于其中。
- 出现 `pages.yml is not managed` 时，请检查已有工作流。只有确定要替换它时才使用 `--force-workflow`。
- 更新 `website/` 后，`--check` 报告偏差时，请先运行一次不带 `--check` 的 `integrate`，再提交刷新后的文件。
- GitHub 完成构建但没有部署时，请确认 **Settings → Pages → Build and deployment → Source** 已设置为 **GitHub Actions**。