部署到 GitHub Pages

GitHub Pages 项目网站通常位于 https://owner.github.io/repository/。只要构建收到最终公开 URL， Doctrine 就能处理这段子路径。

1. 在本地验证生产构建

添加 CI 前，先使用相同的公开地址结构：

doctrine build docs --site-url https://owner.github.io/repository/

如果要检查导航与搜索，请通过静态服务器打开生成的 dist/index.html。不要使用 file: URL； module script 和 Pagefind 都需要 HTTP 服务。

2. 启用 Actions 部署

打开仓库的 Settings → Pages，把 Source 设置为 GitHub Actions。

3. 添加工作流

创建 .github/workflows/deploy-docs.yml：

name: Deploy documentationon:  push:    branches: [main]  workflow_dispatch:permissions:  contents: read  id-token: write  pages: writeconcurrency:  group: pages  cancel-in-progress: truejobs:  deploy:    environment:      name: github-pages      url: ${{ steps.deployment.outputs.page_url }}    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v5      - uses: pnpm/action-setup@v4      - uses: actions/setup-node@v4        with:          node-version: 24          cache: pnpm      - run: pnpm install --frozen-lockfile      - id: pages        uses: actions/configure-pages@v6      - run: doctrine build docs --site-url "${{ steps.pages.outputs.base_url }}"      - uses: actions/upload-pages-artifact@v5        with:          path: dist      - id: deployment        uses: actions/deploy-pages@v5

这些版本与本仓库验证过的 Pages 工具链一致。请按使用方项目修改分支、包管理器、内容目录或 输出目录，并让上传 path 与 --out-dir 或 outDir 保持一致。

为什么 base_url 很重要

actions/configure-pages 返回配置后的 Pages URL：项目网站会包含 /repository/，自定义域名也会 反映在这里。Doctrine 归一化该 URL，再把 pathname 用于：

• CSS 与 JavaScript 资源
• 默认 MDX 链接与导航
• 语言路由与切换
• Pagefind 请求和结果链接
• canonical 与 alternate 元数据
• 404.html 引用的脚本和样式

Artifact 仍包含 dist/index.html，而不是 dist/repository/index.html。GitHub Pages 在服务 artifact 时添加仓库前缀。

自定义域名与其他静态托管

Pages 配置自定义域名后，同一工作流仍然适用，因为 base_url 会反映该设置。使用其他静态托管 时，传入其最终 HTTP(S) URL 执行同一个构建，再上传输出目录内容即可。生产环境不需要 Node.js 进程。

常见问题

• 工作流无法部署： 确认 Pages 使用 GitHub Actions，并且 job 拥有 pages: write 和 id-token: write。
• 资源、导航或搜索返回 404： 确认 --site-url 包含完整仓库 pathname，并结束于公开网站 root。
• Artifact 上传找不到文件： 让 path 与 --out-dir 或配置的 outDir 一致。
• 构建拒绝 outDir： 它必须位于项目 root 内、内容目录外，并且不能就是 root。
• 原生绑定无法加载： 在 @amamo/mdx 支持的平台安装依赖，不要从其他机器复制 node_modules。