Clarify

快速开始

这篇文档用一条最短路径说明 Clarify 如何工作：安装 CLI、创建内容、启动本地站点、构建静态产物。

Clarify = MDX 内容 + clarify.ts 配置 + OpenAPI 规范 + 静态站点生成。你主要维护 source/ 和配置文件，Clarify 负责开发服务器、路由、渲染和构建。

1. 准备环境

需要：

  • Node.js ≥ 20
  • pnpm ≥ 9

创建项目并安装 CLI：

mkdir my-docs
cd my-docs
pnpm init
pnpm add -D @clarify-labs/cli

在 package.json 中添加脚本：

{
  "scripts": {
    "dev": "clarify dev",
    "build": "clarify build --output output"
  }
}

2. 添加站点配置

推荐使用 clarify.ts，可以获得类型提示，也方便后续接入插件。

import { defineConfig } from '@clarify-labs/cli'

export default defineConfig({
  title: '我的文档',
  description: '基于 Clarify 构建的文档站点',
  navbar: {
    links: [
      { label: '文档', href: '/getting-started' },
      { label: 'GitHub', href: 'https://github.com/example/project', external: true },
    ],
  },
})

简单项目也可以使用 clarify.json：

{
  "title": "我的文档",
  "description": "基于 Clarify 构建的文档站点"
}

完整字段见 配置参考。

3. 编写第一批页面

Clarify 默认读取 source/ 目录。新增 .mdx 文件就是新增页面。

my-docs/
├── clarify.ts
├── package.json
└── source/
    ├── index.mdx
    └── getting-started.mdx

source/index.mdx：

---
title: 首页
description: 我的产品文档首页
---

# 欢迎使用

这里是文档首页。

source/getting-started.mdx：

---
title: 快速开始
---

# 快速开始

这里是第一篇指南。

路由会自动生成：

文件路由
source/index.mdx/
source/getting-started.mdx/getting-started
source/guides/index.mdx/guides
source/guides/auth.mdx/guides/auth

4. 启动开发服务器

pnpm dev

打开终端输出的本地地址。你修改 MDX、配置或 OpenAPI 文件后，开发服务器会重新生成页面。

5. 构建生产版本

pnpm build

默认输出到 output/：

output/
├── index.html
├── getting-started/
│   └── index.html
├── assets/
└── llms.txt

这些都是静态文件，可以部署到 Vercel、Netlify、GitHub Pages、S3、Nginx 或任意静态托管服务。

下一步

目标阅读
写出结构清晰的文档写作文档
配置导航、主题和多语言配置站点
生成 API Reference 或嵌入接口API 文档
发布到线上并让 AI 读取原始内容发布上线
从 Mintlify 迁移从 Mintlify 迁移