# GitHub Pages

> 将站点部署到 GitHub Pages，包括位于子路径下的项目站点。

GitHub Pages 以两种 URL 形式之一提供静态文件目录：

- **用户/组织站点**：`https://<user>.github.io/`，从名为 `<user>.github.io` 的仓库提供。没有子路径。
- **项目站点**： `https://<user>.github.io/<repo>/`，从其他任意仓库提供。 `/<repo>/` 前缀很重要；页面和资源的 URL 都必须包含它。

## 构建站点

```sh
htmlpress build
```

输出位于 `.htmlpress/build/`。

## 为项目站点配置 `base`

如果你发布在 `https://<user>.github.io/<repo>/` 下，请设置 `base`，让构建中每个根相对 URL 都带上该前缀。编写链接时照常不带前缀（`/guides/build/`）；htmlpress 会自动加上。`htmlpress start` 和 `preview` 也在同一 base 下提供服务，因此开发环境与生产环境一致：

```yaml
site: https://acme.github.io
base: /my-docs/
```

对于位于根路径的用户/组织站点，完全省略 `base`。

> **提示**
>
> 即使是项目站点，使用自定义域名时也不再有 `/<repo>/` 子路径。如果你要绑定 `docs.example.com` 这样的域名，请不要设置 `base`，并把 `site` 设为最终域名。

## 手动部署

最简单的一次性部署方式是使用 [`gh-pages`](https://www.npmjs.com/package/gh-pages) 包：

```sh
htmlpress build
npx gh-pages -d .htmlpress/build --nojekyll --dotfiles
```

这会把构建推送到 `gh-pages` 分支。在仓库设置中，把 **Pages → Source** 设为“Deploy from a branch”，并选择 `gh-pages` / `/ (root)`。

> **Warning**
>
> 务必保留 `--nojekyll`：分支部署会运行 Jekyll，它会丢弃以 `_` 开头的文件夹，`_htmlpress/` 中的主题也会随之丢失。`--dotfiles` 则会保留存放智能体技能的 `.well-known/`。

## 使用 GitHub Actions 部署

官方 Pages actions 是最简洁的方式：无需额外分支，也无需服务令牌。

```yaml
name: deploy

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npx gethtmlpress build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: .htmlpress/build

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment
```

在仓库设置中把 **Pages → Source** 设为“GitHub Actions”。

## 自定义域名

在项目中、页面旁边添加一个写有你域名的 `CNAME` 文件：

```
docs.example.com
```

项目中所有非页面文件都会按原样、以相同路径复制到构建输出中，因此放在根 `index.html` 旁的 `CNAME` 会出现在部署的根目录。在域名注册商处配置 DNS（一条指向 `<user>.github.io` 的 `CNAME` 记录），并在 **Pages → Custom domain** 中设置该域名。

## 另请参阅

- [站点元数据](/zh/customization/site-metadata/)：sitemap 和 Open Graph 标签中的绝对 URL 需要 `site`。
- [部署](/zh/deployment/)：返回托管平台索引。