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 表格。所有表格保持左对齐便于阅读与扫描。示例图表组件属性表div style{{ width:100px}} Variablediv style{{ width:200px}} Descriptiondiv style{{width: 200px}} How To AccesschartTitleHolds the title of the chart component.Accessible dynamically with JS (for e.g.,{{components.chart1.chartTitle}}).xAxisTitleContains the title for the X-axis of the chart.Accessible dynamically with JS (for e.g.,{{components.chart1.xAxisTitle}}).yAxisTitleContains the title for the Y-axis of the chart.Accessible dynamically with JS (for e.g.,{{components.chart1.yAxisTitle}}).clickedDataPointsStores details about the data points that were clicked.Accessible dynamically with JS (for e.g.,{{components.chart1.clickedDataPoints}}). Each data point includesxAxisLabel,yAxisLabel,dataLabel,dataValue, anddataPercent.以上表格中的属性并非虚构在 frontend/src/AppBuilder/Widgets/Chart.jsx 的源码中图表组件确实通过useMemo计算并暴露了chartTitle、xAxisTitle、yAxisTitle等属性供 JS 表达式动态访问。这提示文档贡献者写属性表前先核对组件源码保证文档与实现一致。表格规范要点所有列标题使用粗体与表格内容区分。避免留空单元格若某格无适用内容使用 N/A 或 — 占位表明该格是有意留空。4. 提示块AdmonitionsAdmonitions 是用于吸引读者注意特定要点的内容块。请克制使用避免淹没读者仅保留给关键或警示信息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 tokenHTTP 代码块应保证复制到 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 nodejsSQL 查询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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ToolJet 文档写作风格指南：从格式规范到源码级验证的完整实践
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 表格。所有表格保持左对齐便于阅读与扫描。示例图表组件属性表div style{{ width:100px}} Variablediv style{{ width:200px}} Descriptiondiv style{{width: 200px}} How To AccesschartTitleHolds the title of the chart component.Accessible dynamically with JS (for e.g.,{{components.chart1.chartTitle}}).xAxisTitleContains the title for the X-axis of the chart.Accessible dynamically with JS (for e.g.,{{components.chart1.xAxisTitle}}).yAxisTitleContains the title for the Y-axis of the chart.Accessible dynamically with JS (for e.g.,{{components.chart1.yAxisTitle}}).clickedDataPointsStores details about the data points that were clicked.Accessible dynamically with JS (for e.g.,{{components.chart1.clickedDataPoints}}). Each data point includesxAxisLabel,yAxisLabel,dataLabel,dataValue, anddataPercent.以上表格中的属性并非虚构在 frontend/src/AppBuilder/Widgets/Chart.jsx 的源码中图表组件确实通过useMemo计算并暴露了chartTitle、xAxisTitle、yAxisTitle等属性供 JS 表达式动态访问。这提示文档贡献者写属性表前先核对组件源码保证文档与实现一致。表格规范要点所有列标题使用粗体与表格内容区分。避免留空单元格若某格无适用内容使用 N/A 或 — 占位表明该格是有意留空。4. 提示块AdmonitionsAdmonitions 是用于吸引读者注意特定要点的内容块。请克制使用避免淹没读者仅保留给关键或警示信息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 tokenHTTP 代码块应保证复制到 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 nodejsSQL 查询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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考