发布上线

这篇文档合并说明 Clarify 的发布能力：静态生成、部署到常见平台、配置子路径、输出原始内容和 llms.txt。

Clarify 构建产物是纯静态文件，可以部署到任何静态托管服务。

构建产物

运行：

pnpm exec clarify build

默认输出到 output/，也可以指定目录：

pnpm exec clarify build --output dist

构建结果类似：

output/
├── index.html
├── getting-started/
│   └── index.html
├── assets/
├── llms.txt
├── index.md
└── api.openapi.json

每个路由都有独立 HTML，适合 SEO 和直接访问；浏览器加载 JavaScript 后会获得客户端导航体验。

部署平台

Vercel

将代码推送到 GitHub/GitLab/Bitbucket。
在 Vercel 中导入项目。
构建命令：pnpm exec clarify build。
输出目录：output。

Netlify

连接 Git 仓库。
构建命令：pnpm exec clarify build。
发布目录：output。

GitHub Pages

如果仓库名为 my-repo，站点地址是 https://username.github.io/my-repo/，配置：

export default defineConfig({
  routePrefix: '/my-repo/',
})

示例 GitHub Actions：

name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 9
      - run: pnpm install
      - run: pnpm exec clarify build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./output

CDN / Nginx

将 output/ 上传到 Web 根目录即可：

rsync -avz output/ user@server:/var/www/html/

Nginx 示例：

server {
    listen 80;
    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

原始内容输出

Clarify 会在开发和构建阶段暴露原始内容，方便搜索、知识库和 AI 工具读取。

页面路由	原始内容 URL
`/`	`/index.md`
`/getting-started`	`/getting-started.md`
`/features/openapi`	`/features/openapi.md`
`/api`	`/api.openapi.json`

页面右上角的内容操作会使用这些 URL，用于复制原始内容链接、下载页面源内容，或让 AI 工具引用稳定的 Markdown/OpenAPI 地址。

`llms.txt`

构建产物会包含 llms.txt，列出站点标题、描述、MDX 页面和 OpenAPI 文档入口：

# Clarify

> 开源文档发布工具，为 MDX 和 OpenAPI 而生。

## Docs
- [快速开始](/getting-started.md)
- [API 文档](/features/openapi.md)

## OpenAPI
- [API Reference](/api.openapi.json)

适合被：

AI 编程助手读取；
内部知识库索引；
文档质量检查工具消费；
搜索或问答系统作为入口清单。

如果配置了 routePrefix，llms.txt 中的链接会自动带上相同前缀。

发布前检查

pnpm exec clarify build 可以成功完成。
output/ 中包含预期 HTML、资源、原始 Markdown/OpenAPI 和 llms.txt。
如果部署在子路径，已配置 routePrefix。
OpenAPI 原始内容不包含不应公开的内部信息。
部署平台的输出目录指向 output 或你的自定义输出目录。