发布上线

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

Clarify 支持 SSR 渲染，但它采用的是构建期 SSR：clarify build 会在构建过程中把每个路由渲染成 HTML 文件。上线后的产物仍然是纯静态文件，不需要 Node.js 服务端运行时，可以部署到任何静态托管服务。

SSR 支持方式

Clarify 的生产渲染流程是 SSG（Static Site Generation）+ Hydration：

1. 构建环境运行 pnpm exec clarify build。
2. CLI 使用 Vite SSR bundle 在 Node.js 中渲染每个文档路由。
3. 每个路由写出独立的 index.html，并生成 JS/CSS 资源、原始 Markdown/OpenAPI 制品和 llms.txt。
4. 用户访问页面时先拿到已经渲染好的 HTML；浏览器加载 JavaScript 后再注水为 React 应用，后续站内跳转获得客户端导航体验。

这意味着：

• ✅ 支持首屏 HTML、SEO 友好和直接访问深层链接；
• ✅ 部署时只需要托管静态文件；
• ✅ Vercel、Netlify、GitHub Pages、对象存储、CDN、Nginx 都可以使用；
• ❌ 不需要也不提供生产环境的请求时 SSR 服务器。

构建产物

运行：

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 后会获得客户端导航体验。部署时只需要发布 output/ 目录，不要发布构建过程中的临时 SSR bundle。

部署平台

Vercel

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

Netlify

1. 连接 Git 仓库。
2. 构建命令：pnpm exec clarify build。
3. 发布目录：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，用于复制原始内容链接、下载页面源内容，或让 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 中的链接会自动带上相同前缀。

发布前检查

• 构建环境满足 Node.js >=20.0.0 和 pnpm >=9.0.0。
• pnpm exec clarify build 可以成功完成。
• output/ 中包含预期 HTML、资源、原始 Markdown/OpenAPI 和 llms.txt。
• 如果部署在子路径，已配置 routePrefix。
• OpenAPI 原始内容不包含不应公开的内部信息。
• 部署平台的输出目录指向 output 或你的自定义输出目录。
• 生产环境按静态站点部署即可，不需要启动 Node.js SSR 服务。