FlowGram 官网文档建设详细代码见：GitHub.com/bytedance/f...
1. 背景
随着使用的用户量增多，FlowGram 需要有一个面向使用者的更详细的教程指引，辅助入门，降低 SDK oncall 成本。 因此在开源的初期即计划基于 SSG 做一套全新的官网体系。
| 术语 | 解释 |
|---|---|
| SSG | SSG 是 Static Site Generation（静态站点生成）的简称，是一种在构建网站时的预渲染技术。SSG 通过在构建时将网站内容生成静态 HTML 文件，而不是动态地通过服务器请求实时生成内容。这种方式通常用于静态网站、博客、文档站点和营销页面等。SSG 优点：无运行时代码：因为没有动态后端逻辑，减少了常见的服务器攻击面（如 SQL 注入、服务器端脚本漏洞等）。可使用 CDN 部署：静态文件托管于 CDN 中，进一步提升安全性并减少复杂配置。静态文件可托管于任何支持 HTTP 的平台（如 GitHub Pages、Vercel、Netlify 等），部署过程简单、快速。良好的 SEO：因为 HTML 是在构建时生成的，搜索引擎能够直接抓取完整的页面内容，而无需额外的客户端渲染或动态生成。 对于经常变更的动态数据和超大型站点，SSG 静态生成模型不够高效。 |
2. 需求目标
2.1. 需求目标
- 【业务目标】减少用户使用成本和团队的沟通成本，有一个美观的官方站点也有利于开源项目的宣传。
- 【技术目标】搭建 Demo Playground 演示，用户可以直接在官网上配置入参调试。
| 优先级 | 需求点 | 详细描述 | 备注 |
|---|---|---|---|
| P0 | Demo 功能拆分 | 水平布局 / 垂直布局画布引擎 / 节点引擎 / 变量引擎ShortcutsHistoryreduxDevTool第三方插件 plugins生命周期其他细节的 props 解释。 | |
| P0 | Changelog、BreakingChange 展示 | ||
| P0 | Playground 代码实时编辑渲染 | 类似 semi 官网，做一个编辑代码实时更新渲染的功能，方便用户直接在网站上编辑 props，更直观教导用户。 | |
| P0 | API 自动生成 | 基于已有代码的 TS 定义，自动生成文档内容 | 一方面节约官网内容维护人力成本另一方面可以通过这种方式规范代码的类型定义。（ts 即 doc） |
| P1 | 国际化 | 官网支持中英文 | 官网针对组件的使用描述，方便后续文案维护。 |
3. 准备工作
考虑到官网需要有一个专属的图标，这里通过 coze 搭建了一个 imageflow 来生成图标：
prompt：
2D 图，工作流，固定布局，自由布局，简洁，flowgramai，不要展示任何文字将生成的图标挑选，进行背景色抠图处理后生成了我们现在的官网图标。
4. 技术选型
4.1. 【P0】官网建设框架
初步是打算使用一个 SSG 框架，这样 SEO 和
| Storybook | Docz | Nextra | Gatsby | Docusaurus | Rspress | |
|---|---|---|---|---|---|---|
| 性能 | ⭐️ | ⭐️⭐️ | ⭐️ | ⭐️⭐️ | ⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ |
| 上手成本 | ⭐️⭐️ | ⭐️⭐️ | ⭐️⭐️ | ⭐️⭐️⭐️ | ⭐️⭐️⭐️ | ⭐️ |
| 社区完备度 | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️ |
结论：使用 Rspress 框架 原因：高性能、开箱即用、低上手成本、整体默认 UI 风格更字节 like
下面是几个比较典型的官网建设的框架
Storybook
添加图片注释，不超过 140 字（可选）
最常用的前端组件库框架，storybook 自带静态站点生成的能力：build-storybook 优点是社区建设比较完整；缺点是不适合作为官网的首页、本地运行的时候即便组件数量比较少的场景也会卡顿。
Docz
Demo: docz-theme-ztopia.surge.sh/docs/design Docz 交互体验风格感觉略老，类 storybook 的交互。
Nextra
nextra.site/docs 作为一个静态站点，启用 SSR 有一些服务资源浪费。
同时，nextra 的 SSG 构建速度比较缓慢。
Gatsby
GitHub.com/gatsbyjs/ga... SemiDesign 官网使用的就是 Gatsby
使用 Gatsby 体验下来，开箱即用的功能很好用： npm init gatsby 一条命令即可执行。
但是与此同时，gatsby 的插件化配置会比较多。 默认只有内置一个 mdx 的解析
Gatsby 刚配置好，站点内容是这样的： header、doc 悬浮窗等功能都需要额外的插件配置，具有一定的上手成本。
Docusaurus
Facebook 公司的 SSG 框架 GitHub.com/facebook/do...
Docusaurus 类似 Gatsby，也支持 cli 一键安装生成： npm init docusaurus@latest my-website classic 配置好后直接有官网首页、有 doc tutorial 页面，也兼备样式
Rspress
只支持 markdown 和组件的绑定，不支持实时热更新。 但是支持配置 mdxRs 。其能力底层基于 Rspress 自研的 @rspress/mdx-rs 库来实现，性能比 JS 版本的 MDX 编译器提升 10 倍以上，但不支持 JS 的插件。 Rspress 也是一键生成：npm create rspress@latest 跑起来后，ui 比较简单：
构建产物也是纯静态 HTML。 Rspress 相比较于另外两个热门的框架 Nextra、Docusaurus，性能有比较大的飞跃
Rspress vs Docusaurus
最终在 Rspress 和 Docusaurus 两个技术栈中进行 pk
| Rspress | Docusaurus | |
|---|---|---|
| 搜索 | Rspress 中提供开箱即用的全文搜索能力，你无需任何配置即可接入，底层基于开源的 FlexSearch 引擎实现。 p.s. 由于是构建时生成搜索索引，本地文件变更后需要重启项目才能检索到。 | Docusaurus 需要手动添加 algolia 自动搜索配置，github.com/facebook/do... |
| MDX | 支持 | 支持 |
| 本地编译、热更新速度（使用脚手架初始化的简单 demo） | 启动 200ms+热更新 50ms Rspress 性能更佳 | 启动 1s +热更新 200ms + |
| 插件系统 | 基于 Vite 的生态插件生态仍在发展中适合功能较简单的文档站点 | 提供详细生命周期 hook，灵活度高社区活跃，插件开发文档完善。适合大型文档站点 |
| 国际化 | 支持 | 支持 |
| Documate 主题支持 | 支持 | 支持 |
最终决定使用性能体验更佳、上手成本更低的 Rspress。
4.2. 代码预览
Rspress playground-plugin
Rspress 天然支持 playground 预览：@rspress/plugin-playground 支持代码实时变更。
优势
- 官方插件，和 rspress 配合天然好。
- 支持 md 文件内直接写代码块，自动生成可运行预览。
- 配置简单，开箱即用。
劣势
- 功能较基础，灵活性不如 Sandpack 或 react-live。
- 只适合简单示例，不适合大型 demo 或复杂交互。
Playground 插件有如下变量：
php
interface PlaygroundOptions {
render: string; // 文件路径字符串，playground 会使用该路径下的组件代码渲染，因此 playground 插件可以集成其他代码预览 sdk
include: Array<string | [string, string]>; // jsx 内包含的组件 import 需要
defaultDirection: 'horizontal' | 'vertical';
editorPosition: 'left' | 'right';
babelUrl: string;
monacoLoader: Parameters<typeof loader.config>[0];
monacoOptions: EditorProps['options'];
/**
* determine how to handle a internal code block without meta
* @default 'playground'
*/
defaultRenderMode?: 'pure' | 'playground';也可以支持 monaco editor 自定义。但是不支持多代码文件的回显，因此仅作为备用回显手段注册。
@codesandbox/sandpack-react
优势
- 非常强大，支持完整的 React/JS 运行环境。
- 可以在线编辑、实时运行，甚至模拟多文件结构。
- 与 CodeSandbox 官方生态接轨，功能最完整。
劣势
- 体积大，引入 bundle 会增多。
- 配置比 @rspress/plugin-playground 稍复杂。
相比较之下适合作为官网的预览插件。
react-live
优势
- 轻量，支持在网页中直接写 JSX 并实时渲染。
- 对简单代码 demo 很方便，灵活度高。
劣势
-
只能处理单文件 JSX，不能像 Sandpack 那样处理多文件项目。
-
对复杂依赖不太友好，需要自己提供 scope（React、组件等依赖）。
因此最终我们选择了 @codesandbox/sandpack-react + @rspress/plugin-playground 的组合构建官网代码预览部分。
5. API 生成
Rspress 社区插件总览：Rspress 代码自动生成这块目前暂时未做技术比对，目前社区使用 TypeDoc 是最方便的解决方案
5.1. 根据 TypeScript 自动生成 API Doc
Rspress 集成 TypeDoc 插件，可以自动生成 TS 模块的 API 文档：
javascript
import { defineConfig } from 'rspress/config';
import { pluginTypeDoc } from '@rspress/plugin-typedoc';
import path from 'path';
export default defineConfig({
plugins: [
pluginTypeDoc({
entryPoints: [
path.join(__dirname, 'src', 'foo.ts'),
path.join(__dirname, 'src', 'bar.ts'),
],
}),
],
});当启动项目的时候，插件会在文档根目录下自动生成 API 目录，结构如下：
bash
api
├── README.md
├── documentation.json
├── functions
│ ├── bar.multi.md
│ └── foo.add.md
├── interfaces
│ ├── foo.RunTestsOptions.md
│ └── foo.TestMessage.md
└── modules
├── bar.md
└── foo.md但是默认的 Rspress 的 Typedoc 插件默认是根据模块、方法等汇总划分的，对用户来说可读性不高。因此这里我们自行实现了一套逻辑，从包维度来划分 API 展示。
具体源码：github.com/bytedance/f...
6. 站点部署
这里前后经历了几次方案的变更。
- 最开始的时候我们使用了 GitHub Pages 的功能来实现官网部署
使用 actions/upload-pages-artifact@v3 + actions/deploy-pages@v2 可以很方便的实现静态产物上传 + 站点部署的功能。但是在此期间我们发现：GitHub Pages 官方的 Fastly CDN 比较基础，如果是国内用户直接访问站点，速度会比较慢。因此后来我们将站点部署到了 Vercel 上。Vercel 的全球边缘 CDN 更加优秀，国内用户在移动端用流量也能有比较好的访问体验。
但是在升级完 rspress 版本，并且开启了 rpsress llmstxt 插件的时候，我们发现构建经常会超时失败。这是由于我们解析了整个站点的源码，并且使用了 typedoc 生成了 API 文档，编译内存要求较高，而 Vercel 上支持的编译内存最大的内存只有 16G，所以会偶发报错。
因此这里做了一个优化，在 GitHub 上进行编译，然后将编译产物上传到指定分支，最后通过指定分支 gh-pages 的静态资源部署触发官网的更新：
之所以没有使用 Vercel CLI，是因为 CLI 有上传文件数量限制（15000），而我们的站点在 TypeDoc 生成 API 后，文件数量达到 28000+