GitHub Pages

更新于 2026年11月12日

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

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

构建站点

livemark build

输出位于 .livemark/build/client/。

为项目站点配置 `base`

如果你发布在 https://<user>.github.io/<repo>/ 下，请设置 base 字段，让每个路由和资源 URL 都带上正确的前缀。函数形式能让开发保持简单：livemark start 仍然在 / 下提供服务，只有生产构建才挂载到 /<repo>/ 下：

livemark.config.ts

import { defineConfig } from "livemark"

export default defineConfig({
  site: "https://acme.github.io/my-docs",
  base: command => (command === "build" ? "/my-docs" : undefined),
})

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

手动部署

最简单的一次性部署方式是使用 gh-pages 包：

livemark build
gh-pages -d .livemark/build/client

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

使用 GitHub Actions 部署

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

.github/workflows/deploy.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: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          cache: pnpm
          node-version: 24
      - run: pnpm install
      - run: pnpm livemark build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: .livemark/build/client

  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”。

自定义域名

在 .livemark/public/ 中添加一个写有你域名的 CNAME 文件：

.livemark/public/CNAME

docs.example.com

.livemark/public/ 中的所有内容都会按原样复制到构建输出，因此该文件会位于部署的根目录。在域名注册商处配置 DNS（一条指向 <user>.github.io 的 CNAME 记录），并在 Pages → Custom domain 中设置该域名。

另请参阅

站点元数据：sitemap、RSS 和 Open Graph 标签中的绝对 URL 都需要 site。
部署：返回托管平台索引。