ToolJet 文档站点架构解析：基于 Docusaurus 的目录组织、版本化文档与本地开发全流程

本文以 docs/README.md 为主线，系统讲解 ToolJet 开源文档站点（部署于 docs.tooljet.ai）的目录组织、Docusaurus 版本化文档机制、写作约定与本地开发/构建/部署流程。读完本文，你将能够理解 ToolJet 文档仓库的结构约定（front matter、sidebars、版本号管理），并能在本地跑起文档开发服务器、构建静态站点，同时掌握从源码配置层面解读 includeCurrentVersion、lastVersion 等关键参数的影响。

1. docs 目录的定位

ToolJet 主仓库中的 docs/ 目录是独立于产品代码的文档站点工程，其内容即官方文档站的源码：Markdown 正文、侧边栏配置、主题定制代码与静态资源。docs/README.md 开宗明义地说明：该目录持有文档网站的代码与 Markdown 源文件。

文档站点的组织方式与最终站点（docs.tooljet.ai）保持一致，这意味着本地改动与线上页面结构一一对应，便于定位与维护。要理解这个工程，需要抓住三层结构：

• 内容层：docs/docs/ 目录，存放"下一个版本"（next/upcoming）的文档正文；
• 版本层：docs/versioned_docs/ 与 docs/versioned_sidebars/，存放各已发布版本的快照；
• 框架层：docusaurus.config.js、sidebars.js、docs/src/（主题与插件代码），由 Docusaurus 驱动渲染。

需要指出一个文档与仓库现状的差异：README 中提到"文档网站使用 Docusaurus 2 构建"，而当前 docs/package.json 实际依赖 @docusaurus/core: ^3.6.3、@docusaurus/preset-classic: ^3.6.3，即文档站已升级到 Docusaurus 3。以下讲解以当前仓库实际配置为准。

2. 仓库组织结构（Repository Organization）

README 给出的目录树如下（原样继承，并对照当前仓库实际文件补充说明）：

/tooljet/docs
├── sidebars.json        # sidebar for the next(upcoming) docs version
├── docs                 # docs directory for the next(upcoming) docs version
│   ├── Enterprise
│   │   └── multi-environment.md
│   └── tooljet-database.md
├── versions.json        # file to indicate what versions are available
├── versioned_docs
│   ├── version-x.x.x    # Current/latest version (set it on docusauras.config.js)
│   │   ├── Enterprise
│   │   │   └── multi-environment.md   # https://docs.tooljet.ai/docs/Enterprise/multi-environment
│   │   └── tooljet-database.md.       # https://docs.tooljet.ai/docs/tooljet-database
│   └── version-2.0.0
│       ├── Enterprise
│       │   └── multi-environment.md
│       └── tooljet-database.md
├── versioned_sidebars                 # includes sidebar for the specific versions
│   ├── version-x.x.x-sidebars.json
│   └── version-1.0.0-sidebars.json
└── src
│   └── img                           # contains folders that references the images (such as screenshots) used in the docs
├── docusaurus.config.js
└── package.json

对照当前仓库，几个要点：

• 侧边栏文件当前实际是 sidebars.js（README 树中写作 sidebars.json），它是一个 CommonJS 导出的 SidebarsConfig，按主题组织为 Getting Started、App Builder、Data Sources、ToolJet Database、Workflows、Setup ToolJet、User Management、Development Lifecycle、Security and Monitoring 等一级 category，每个 category 的 items 通过文档 id 引用正文文件。
• versions.json 当前内容为 ["3.0.0-LTS", "2.50.0-LTS"]，即站点对外提供两个已发布的 LTS 版本；对应的正文快照位于 docs/versioned_docs/version-3.0.0-LTS/ 和 docs/versioned_docs/version-2.50.0-LTS/，侧边栏快照为 version-3.0.0-LTS-sidebars.json、version-2.50.0-LTS-sidebars.json。
• src/ 目录除 img 外还包含站点代码：docs/src/components/（如 DocsCard 组件）、docs/src/pages/（首页与 markdown-page.md）、docs/src/css/custom.css（由 docusaurus.config.js 的 theme.customCss 引入）、以及 docs/src/plugins/devServer/index.js 本地开发插件。README 中"src/img 存放截图"的说法，在当前仓库中体现为 docs/static/img/（静态资源目录，文档正文中的截图即存放于此）。
• 另有一份 versionsArchived.json，记录了更久远的 2.x 版本（如 2.62.0、2.43.0 等 25 个条目），供归档链接使用（见第 4 节）。

3. 内容文件写作约定（Conventions）

README 的 Conventions 一节规定了三个必须遵守的硬性约定，这也是文档能进入版本化流水线的"准入条件"。

3.1 Front matter 必须包含 id 与 title

每个 Markdown 文档的 front matter 都应包含 id 和 title，其中 id 是文件在 sidebars.js 或 version-x.x.x-sidebars.json 中被引用的键。README 给出的示例：

---
id: building-internal-tool
title: Building internal tool with ToolJet
---

仓库中的真实文档完全遵循这一格式，例如 introduction.md 的开头即为 id: introduction / title: Introduction。侧边栏中所有形如 'how-to/bulk-update-multiple-rows' 的条目，都是"目录路径 + 文件名"拼出的 id，必须与正文文件的实际位置一一对应，否则 Docusaurus 构建时会报"sidebar 中引用了不存在的文档 id"。

3.2 文件与目录命名：小写 + 连字符

README 要求文件和文件夹使用小写字母并以 - 作为分隔符，例如：

• /docs/data-sources/sap-hana.md
• /docs/how-to/bulk-update-multiple-rows.md

这与 sidebars.js 中现有的条目风格（widgets/toggle-switch-v2、development-lifecycle/gitsync/overview 等）一致，也保证了 URL 的稳定性。

3.3 图片规范：命名、路径与引用写法

• 图片存放在 static 下的 img 子目录中；每个主题应有自己的子文件夹，例如 static/img/how-to/bulk-update/query1.png（即仓库路径 docs/static/img/how-to/bulk-update/query1.png）。
• 链接路径与文件名大小写敏感；约定图片文件名全部小写、用连字符分隔。
• README 给出的引用示例（原样保留，注意这是 JSX 写法，需要放在 .mdx/支持 JSX 的 Markdown 中渲染）：

<div style={{textAlign: 'center'}}>

<img className="screenshot-full" src="/img/button-group.png" alt="Button group" />

</div>

src="/img/..." 是站点根相对路径，对应 docs/static/img/... 下的文件——static 目录中的文件会被 Docusaurus 原样拷贝到站点根路径，这是 Docusaurus 静态资源的标准机制。

补充说明：仓库在 docs/docs/contributing-guide/documentation-guidelines/style-guide.md 中还给出了更细的图片与排版规范（图片 < 300kb、使用 WEBP/PNG、alt 文本描述图意而非"图片是…"、左对齐等），撰写文档时建议一并遵循。

4. 版本化文档机制（Versions）

ToolJet 文档采用 Docusaurus 的 versioned docs 机制，核心由四个文件协同：

文件	作用
docs/versions.json	声明"可用版本"清单，当前为 ["3.0.0-LTS", "2.50.0-LTS"]
docs/versioned_docs/<version>/	每个已发布版本的正文快照
docs/versioned_sidebars/<version>-sidebars.json	对应版本的侧边栏快照
docs/docusaurus.config.js	通过 docs preset 的 includeCurrentVersion、lastVersion、versions 控制"当前版本"与历史版本的映射关系

从 docusaurus.config.js 可以看到当前的关键配置：

docs: {
  sidebarPath: require.resolve('./sidebars.js'),
  editUrl: 'https://github.com/ToolJet/Tooljet/blob/develop/docs/',
  includeCurrentVersion: true,
  lastVersion: '3.0.0-LTS',
  versions: {
    current: {
      label: '3.1.0-Beta 🚧',
      path: 'beta',
      banner: 'none',
      badge: false
    },
    "2.50.0-LTS": { banner: 'none', badge: false },
    "3.0.0-LTS": { banner: 'none', badge: false }
  }
}

逐条解读：

• includeCurrentVersion: true：将 docs/docs/ 基础目录作为"当前版本"（next 版本）加载进站点。README 的 Local setup 部分特别提醒：如果你要预览将进入下一版本文档的改动，需要把该值设为 true，改完后记得改回 false 再提交。当前仓库中该值恒为 true，且 current 版本被标记为 3.1.0-Beta、路径为 beta——从配置结构看，可以推断当前分支处于 3.1.0 的 Beta 阶段，next 文档即通过 /docs/beta/... 路径访问。
• lastVersion: '3.0.0-LTS'：声明"最新已发布稳定版"，决定版本下拉框中哪个已发布版本排在最前，并作为站点默认展示的已发布版本。
• versions 对象：为每个版本定制标签与 URL 路径（如 current 版本走 beta 子路径），并统一关闭 banner/badge，避免版本切换提示干扰阅读。
• 归档版本：配置文件顶部还从 versionsArchived.json 读取列表并取前 5 项，映射到 archived-docs.tooljet.com 基础 URL，用于把远古 2.x 版本指向独立托管的归档站点，而不是全部打进本站点构建。

侧边栏的每个版本快照（versioned_sidebars/version-3.0.0-LTS-sidebars.json 等）与 versions.json 一一对应：发布新版本时，把当时的 docs/docs/ 与 sidebars.js 复制为版本快照、并把版本号写入 versions.json，是这类 Docusaurus 项目的标准发布动作（从文件命名规律可以推断）。

5. 本地开发全流程（Local Setup）

5.1 环境要求

README 写明要求 Node 16.14；但当前仓库的 docs/package.json 中 engines 字段声明为 node: 18.18.2、npm: 9.8.1，且 docs/netlify.toml 的生产构建也锁定 NODE_VERSION = "18.18.2"、NPM_VERSION = "9.8.1"。因此以 18.18.2 为准是更稳妥的选择，README 中的 16.14 属于未同步更新的历史要求。

5.2 安装

yarn install

README 以 yarn install 为例。需要注意当前仓库 docs 工程同时存在 package-lock.json，且 netlify.toml 的生产构建命令走的是 npm（npm run build）。从 docs/package.json 的 scripts 定义看，yarn 或 npm 安装均可完成依赖装配，关键依赖包括 @docusaurus/preset-classic（提供 docs/blog/blogless 预设）、@docusaurus/plugin-client-redirects（URL 重定向）、@docusaurus/plugin-sitemap（站点地图）、@docusaurus/plugin-google-gtag（统计）、以及 React 18 + Tailwind CSS。

5.3 本地开发服务器

yarn start

启动本地开发服务器并自动打开浏览器窗口，大部分修改无需重启即可热更新。开发过程中若需要预览"下一版本文档"（即 docs/docs/ 中的改动），前提是 includeCurrentVersion: true（当前仓库默认满足）。

5.4 构建静态站点

yarn build

在 build 目录生成纯静态内容，可交给任意静态托管服务。注意 docs/package.json 中 build 脚本实际定义为 npm install && docusaurus build，即构建前会自动安装依赖——这与 CI（Netlify）直接执行 npm run build 的方式相衔接。

5.5 部署

GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy

若使用 GitHub Pages 托管，该命令会自动构建站点并推送到 gh-pages 分支。官方生产环境的实际发布渠道从 netlify.toml 看是 Netlify：

[build]
  base = "docs/"
  publish = "build"
  command = "GTM=$GTM ALGOLIA_API_KEY=$ALGOLIA_API_KEY npm run build"

  [template.environment]
  NODE_ENV = "production"
  NODE_VERSION = "18.18.2"
  NPM_VERSION = "9.8.1"

两个环境变量在 docusaurus.config.js 与 Algolia 配置中被消费：GTM 仅在 NODE_ENV === 'production' 时注入 Google Tag Manager 容器，ALGOLIA_API_KEY 用于文档全文搜索（缺省回退为 development，配置中注明该 key 为可公开提交的 public key）。

6. 站点配置中的几个值得注意的细节

在 docusaurus.config.js 中还有几处与文档可用性直接相关的配置：

• 历史 URL 重定向：通过 @docusaurus/plugin-client-redirects 维护了 7 条旧链接到新路径的映射，例如 /docs/gitsync → /docs/development-lifecycle/gitsync/overview、/docs/enterprise/superadmin → /docs/user-management/authentication/self-hosted/instance-login/。文档目录结构每次大重构（如 Enterprise 章节拆分为 User Management、GitSync 移入 Development Lifecycle）都靠它保持旧链接不 404。
• 搜索与元信息：url: 'https://docs.tooljet.ai'、baseUrl: '/'、onBrokenLinks: 'ignore'、onBrokenMarkdownLinks: 'warn'——Markdown 内链断链只告警不失败，这降低了 CI 的脆弱性，但要求作者在 PR 前自查（见第 7 节 PR checklist）。
• 站点地图：sitemap 插件按周更新频率生成，并显式忽略 /docs/1.x.x/** 的远古路径。
• 顶部导航：内置 docsVersionDropdown（右上角版本切换器）、search（Algolia 上下文搜索），以及指向产品、社区的外部链接。

7. 贡献工作流（Workflow）与质量关卡

README 给出两条贡献路径：

1. 小改动：直接用每个页面底部的 "Edit this page" 按钮在源码托管平台编辑 Markdown 并提交 PR。editUrl 配置保证该按钮指向 docs/ 下对应文件。
2. 大改动或需本地预览：克隆仓库，按第 5 节的安装与本地开发步骤操作。

文档问题的反馈渠道：README 建议文档类问题使用带 documentation 标签的 issue 模板提交，产品问题则选择对应的 issue 模板；社区交流通过 Slack 进行。

提交前的质量关卡由仓库内的贡献指南固化：

• introduction.md 定义了 ToolJet 文档的三类体裁——Concepts（概念解释）、How-to（任务指南）、Reference（属性/用法速查），并提出"一个功能没有完整文档就不算完成"的黄金准则；
• style-guide.md 规定了排版细节：查询/表名/组件实例名用斜体、可点击按钮与数据源用粗体、行内代码用单引号、HTTP 头大写、表格左对齐、警示块（:::warning/:::info）克制使用、图片 < 300kb 等；
• pr-checklist.md 是逐条可勾选的 PR 检查清单：拼写语法检查、标题 Title Case、无断链/缺图/错误代码、内部链接使用根相对路径、确认改动已同步到所有需要的版本（即 next 文档与相关 versioned_docs 快照）。

其中"改动需同步到所有必需版本"这一点，正对应第 4 节的版本化机制：只改 docs/docs/ 只会影响下一版本，已发布的 LTS 文档快照不会自动更新。

8. 小结

ToolJet 的 docs/ 目录是一个标准的 Docusaurus 3 版本化文档工程：docs/docs/ 承载下一版本文稿，versions.json + versioned_docs/ + versioned_sidebars/ 管理已发布的 LTS 快照，docusaurus.config.js 通过 includeCurrentVersion 与 lastVersion 控制版本呈现，Netlify 在 Node 18.18.2 环境下执行 npm run build 完成生产发布。对文档贡献者而言，牢记三条约定（front matter 的 id/title、小写连字符命名、static/img 图片规范）并通过 PR checklist 的逐项自检，即可保证改动顺利进入版本化流水线而不破坏侧边栏引用与历史链接。