企业官网建设流程全解析

ToolJet 文档写作风格指南：从格式规范到源码级验证的完整实践

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

本文是 ToolJet 开源项目面向文档贡献者的写作规范手册，系统讲解文本格式、标题层级、Markdown 表格、提示块（Admonitions）、图片、语言风格、代码块、链接与术语语义等全流程规范。你将掌握如何编写清晰、一致、无障碍且符合 ToolJet 文档体系（基于 Docusaurus 构建）的开发者文档，并学会结合 frontend/src/AppBuilder/Widgets/Chart.jsx 等源码验证文档示例的真实性，确保提交的 PR 一次通过评审。

1. 文本格式规范

ToolJet 文档对项目中不同元素的格式有统一约定，目的是让读者一眼就能区分对象名称、界面操作与代码引用。

a. 斜体：用于命名对象

查询（Queries）、数据库表（Database Tables）和组件（Components）的名称使用斜体：

• 创建一个新查询并将其重命名为getEmployees。
• 选择ToolJetDB作为数据源，选择Employees表作为数据源。
• 将返回的数据传递给allEmployees组件。

b. 粗体：用于界面元素与操作入口

工作区常量（Workspace Constants）、可点击按钮、fx 表达式入口、数据源（Data Sources）和组件类型使用粗体：

• 选择Button组件，并将其标签改为 "Save"。
• 拖入一个Table组件并将其重命名为todosTable。
• 展开底部的查询面板，点击Add按钮创建一个新的REST API查询。

值得说明的是，上述示例并非凭空虚构，而是与 ToolJet 实际的组件模型一一对应。在 frontend/src/AppBuilder/Widgets/Chart.jsx 中可以看到，图表组件通过chartTitle、xAxisTitle、yAxisTitle等变量暴露组件属性，这正是文档中"组件名称使用斜体、属性通过{{components.chart1.chartTitle}}动态访问"这一约定背后的真实实现。

c. 行内代码与多行代码

• 行内代码使用单反引号（`），适用于表达式、命令、变量等；
• 多行代码使用三反引号（```），适用于完整代码片段。

示例：fx选项位于组件的 Loading state 属性旁，可用来为组件添加加载状态。例如，输入{{queries.getData.isLoading === true}}即可在getData查询运行期间显示加载器。

使用下面的代码获取数据：

// 此代码包裹在三反引号中 const fetchData = async () => { const response = await api.get('/users'); console.log(response.data); };

其他补充约定：

• API 端点：使用代码反引号，例如GET /api/v1/resources。
• 标签或用户输入：使用双引号突出显示，例如 "Enter your username"。

2. 标题（Headings）

合理使用标题层级是组织内容、提升可读性的关键：

• Title Casing（标题大小写）：所有标题统一采用 Title Casing，保持风格一致。
• 主标题（#）：一篇文章只使用一次，用于文档或章节的主题。
• 二级标题（##）：用于主标题下的子主题或主要章节。
• 三级标题（###）：用于二级标题下的更细粒度要点或小节。
• 四级标题（####）：用于三级标题内更细化的细节，仅在复杂文档中按需使用。
• 间距：每个标题前后各保留一个空行，以保持清晰分隔。
• 层级频率：建议不超过三级标题；若仍需更细粒度，考虑拆分为独立章节或独立文档。

在 ToolJet 的文档仓库中，这一规范得到了严格执行：以 docs/versioned_docs/version-3.0.0-LTS/contributing-guide/documentation-guidelines/pr-checklist.md 为例，其评审清单明确包含"Verify that all h2 and h3 headings follow title case"，即所有 h2/h3 标题必须遵循 Title Case，并且"every section starting with h2 has a 24px padding-top"（每个以 h2 开头的章节需有 24px 顶部内边距），这两条都是 PR 评审的硬性检查项。

3. Markdown 表格

当需要高效呈现大量重复性信息（例如组件的属性清单）时，使用 Markdown 表格。所有表格保持左对齐，便于阅读与扫描。

示例（图表组件属性表）：

以上表格中的属性并非虚构：在 frontend/src/AppBuilder/Widgets/Chart.jsx 的源码中，图表组件确实通过useMemo计算并暴露了chartTitle、xAxisTitle、yAxisTitle等属性，供 JS 表达式动态访问。这提示文档贡献者：写属性表前先核对组件源码，保证文档与实现一致。

表格规范要点：

• 所有列标题使用粗体，与表格内容区分。
• 避免留空单元格；若某格无适用内容，使用 "N/A" 或 "—" 占位，表明该格是有意留空。

4. 提示块（Admonitions）

Admonitions 是用于吸引读者注意特定要点的内容块。请克制使用，避免淹没读者，仅保留给关键或警示信息：

• Warning 提示块：用于高风险操作或不可逆变更，提醒用户注意潜在危险或关键问题。

:::warning Ensure you back up your data before upgrading to the latest version. :::

• Info/Tip 提示块：用于提供有用提示或最佳实践，通常语气积极。

:::info Preview the changes before pushing them. :::

过度使用会稀释提示效果。能使用斜体强调重点时，优先用斜体替代 Admonitions——这是一种侵入性更小的强调方式。

Admonitions 语法是 Docusaurus 的原生能力。在 docs/docusaurus.config.js 中可以看到，ToolJet 文档站使用@docusaurus/preset-classic构建并托管多个版本（2.50.0-LTS、3.0.0-LTS与当前3.1.0-Beta）。因此贡献者在新增 Admonitions 时，应同步检查 docs/docs 与 docs/versioned_docs/version-3.0.0-LTS 等版本目录，确保同一内容在所有受支持的文档版本中保持一致（这也是 PR 评审清单中的强制项："Ensure that the changes are implemented in all the required versions"）。

5. 图片规范

文档配图应贴近真实使用场景，让文档更实用、更易产生共鸣：

• 命名：图片名称反映其用途，例如create-get-query.jpeg，便于文件组织与检索。
• 对齐：图片左对齐，这是与大多数内容布局兼容的标准对齐方式。
• 宽度：图片宽度设为 100%，确保在不同屏幕尺寸下按比例缩放。
• 体积：单张图片控制在 300KB 以内，平衡加载速度与质量。
• Alt 文本：用一句话准确描述图片内容，为依赖屏幕阅读器的用户提供与图片相同的信息。避免 "image of"、"graphic of" 这类前缀——屏幕阅读器会自动处理，只需聚焦描述图片中真正重要的内容。
• 格式：网页图片优先使用WEBP或PNG，在质量与体积之间取得平衡；Logo 或图标使用SVG，保证任意缩放下不失真。

ToolJet 文档仓库的图片统一存放于 docs/static/img 目录（包含两千余张 png、gif、svg、webp 等素材），并在 docs/versioned_docs/version-3.0.0-LTS 各版本文档中以根相对路径引用。新贡献的图片也应遵循同样的存放与引用方式。

6. 语气与清晰度

清晰一致的语气是有效沟通的基础，目标是简洁、信息丰富、对用户友好：

• 语言直白简洁；除非目标读者必需，否则避免术语堆砌，必要时补充解释。
• 提交 PR 前务必使用 Grammarly 或类似工具校对内容，捕捉初稿中可能遗漏的错误。
• 尽可能使用主动语态，使内容更直接、更具吸引力；被动语态会让句子变长且更难理解。

7. 项目符号（Bullet Points）

项目符号用于拆解步骤或列表，让内容更易扫描和理解：

• 避免为单个条目使用项目符号；若只有一个要点，直接融入正文。
• 子要点在 Markdown 中正确缩进，保持层级与逻辑关系。
• 完整句子的项目符号以句号结尾，保证语法正确、可读。
• 项目符号之间不要插入空行，保持列表紧凑、视觉连贯。
• 需要进一步说明或存在层级关系时，使用嵌套项目符号。

8. 具体语言规范

为保证一致性与清晰度，不同技术语言遵循以下格式约定。

HTTP 格式

• 所有 HTTP 头按First-Letter-Capitalized方式大写，遵循标准惯例且易于区分。

Content-Type: application/json Authorization: Bearer <token>

• HTTP 代码块应保证复制到 Postman 或cURL等工具后可直接运行，即包含请求头、请求体、方法等所有必要要素。

curl -X POST https://api.example.com/resource \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <token>' \ -d '{"key": "value"}'

JavaScript 规范

• 语句以分号（;）结尾。虽然 JavaScript 通常能自动推断分号，但显式书写可以避免复杂代码中的潜在问题。

const name = 'John'; console.log(name);

• 字符串默认使用单引号，除非必须使用双引号（例如需要避免转义字符串内部的单引号）。

const greeting = 'Hello, world!';

JSON 格式

• JSON 使用 2 空格缩进，这是改善可读性的标准实践。

{ "name": "John Doe", "age": 30, "city": "New York" }

• JSON 中不要写注释——JSON 原生不支持注释。如需解释，在文档中代码块之外说明。

Shell 脚本

• 将独立命令拆分为独立代码块，或用&&串联以提高可读性；多行命令使用\换行。

sudo apt-get update && \ sudo apt-get install -y curl

• 使用#前缀注释说明命令用途。

# This command installs Node.js sudo apt-get install -y nodejs

SQL 查询

• SQL 关键字使用大写，长查询拆分为多行以提升可读性。

SELECT name, age, city FROM users WHERE age > 30 ORDER BY name ASC;

9. 链接规范

• 使用根相对路径（root-relative paths），例如/schema/postgres/tables.mdx，而不是相对链接，以避免文件移动时链接失效。

示例：Postgres tables链接到 Postgres 表页面。

• 链接到页面内特定章节时，使用锚点链接（anchor links）精准定位。

示例：ToolJet supports [multiple environments](https://docs.tooljet.com/docs/#multiple-environments)直接引导用户到对应章节。

这一规范同样体现在 PR 评审清单中（"Ensure new internal links use root-relative file paths"），评审人会逐条验证新链接是否为根相对路径，同时测试是否存在失效链接、缺失图片与错误代码。

10. 语义与术语

• 使用第二人称（you、your）写作，让内容更富互动性、直接适用于读者。
• 全文保持一致的大小写敏感性，尤其是技术术语与命令——命令和变量对大小写敏感。

示例："MyVariableandmyvariableare not the same."

• 首次出现时定义缩写词，并避免过度使用，帮助不熟悉缩写的读者。

示例："The Content Delivery Network (CDN) is used to deliver content to users efficiently."

• 全文保持术语一致：如果开头使用 "user"，不要在后续同一语境中换成 "customer"。

11. 与文档体系配合：从入门到评审

这份 Style Guide 是 ToolJet 文档贡献流程的一环。在动笔前，建议先阅读 docs/versioned_docs/version-3.0.0-LTS/contributing-guide/documentation-guidelines/introduction.md（了解文档分类：ToolJet Concepts、How-to Guides 与 Reference 三类内容各自的目标），完成写作后对照 docs/versioned_docs/version-3.0.0-LTS/contributing-guide/documentation-guidelines/pr-checklist.md 逐条自检：拼写语法、标题 Title Case、h2 章节 24px 内边距、链接与图片完整性、根相对路径、跨版本同步。

同时，ToolJet 文档站本身托管在 docs 目录，由 docs/docusaurus.config.js 配置多版本构建。提交文档改动时，记得同步检查受支持的版本目录（2.50.0-LTS、3.0.0-LTS），确保用户无论浏览哪个版本的文档都能获得一致的体验。

遵循以上全部规范，你产出的文档将清晰、一致、易用，并能在评审中顺利通过——这正是 ToolJet 文档体系"让功能完整"（feature 没有完善文档就不算完成）这一黄金准则的落地保障。

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet