n8n 文档的风格指南
写作风格
n8n 使用 Microsoft 写作风格指南。此页面突出显示了对 n8n 文档最重要的元素,并添加了我们的自定义样式选择。
你的目标读者
面向使用、运维 n8n 或基于 n8n 进行构建的人员编写文档,而不是面向 n8n 内部工程师。
应包含读者会执行和看到的内容:控件、设置、字段、错误消息、限制,以及会影响其构建成果的行为。
仅在读者需要据此采取行动、选择选项或排查问题时,才包含实现细节。例如,执行数据的存储方式与自托管页面相关,但与节点参考页面无关。否则请省略。
工单、PR 和设计文档是事实来源,而不是页面模板。保留读者需要的信息,删除其余内容。
语言通俗易懂
- 清楚地解释您所记录的流程的每个步骤。
- 使用现在时。
- 让你的写作尽可能简洁。两个免费的浏览器应用程序可以提供帮助:
- 海明威 衡量语言复杂性。对于目标成绩没有固定的规则,但阅读成绩越低越好。
- 莱克西 衡量 Markdown 文本的写作复杂度,并将多项指标合并为一个可读性分数。目标分数应为 60 或更高,大多数页面应高于这个分数。
注意这些常见模式并更喜欢更简单的版本:
| 避免 | 使用 |
|---|---|
| 利用,杠杆 | 利用 |
| 依次为 | 至 |
| 功能、功能 | 功能、用途 |
| 需要注意的是 X | X |
| n8n 提供了一种强大、无缝的方式... | n8n 让您... |
一些经验法则:
- 削减填充物。 删除诸如“重要的是要注意这一点”或“简单”之类的开场白。
- 避免营销语言。跳过“强大”、“稳健”、“无缝”。说明该功能的作用。
- 删除模糊的限定词。删除“非常”、“相当”、“几个”,或给出具体数字。
- 保持句子简短。 30 个单词以下,每个单词一个想法。将任何由分号或第二个“和”连接在一起的内容分开。
- 以操作开头,而不是“有”。“要调度工作流,添加调度触发器”,而不是“有一个可以调度工作流的节点”。
声音和人
写作就好像你直接对读者说话一样。
- 使用主动语态。 “n8n 发送请求”,而不是“该请求由 n8n 发送”。
- 称呼读者为“您”。“您可以添加节点”,而不是“用户可以添加节点”。
- 避免使用第一人称。 命名为 n8n,而不是“我”、“我们”或“我们的”。 “n8n 推荐”,而不是“我们推荐”。
- 使用缩写。 “Don't”和“you'll”,而不是“do not”和“you will”。
包容性语言
写给大家。
- 对未知人员使用“他们”。“每个用户都可以配置他们的设置”,而不是“他的设置”。
- 选择不分性别的术语。“主席”,而不是“主席”。是“主”,不是“主”。
术语和命名
在任何地方使用相同的术语来表示相同的概念,并且更喜欢使用官方产品术语而不是合理的同义词(例如,“发布工作流程”,而不是“激活工作流程”)。在散文中,使用句子大小写;对于文字 UI 标签或节点名称,请使用粗体和产品的确切大小写。将产品名称写为“n8n”,小写,即使在句子的开头也是如此。
请参阅术语和命名,了解要使用和避免的完整术语列表。
文本格式
- 标题:句子大小写 (更多信息)
- UI元素:粗体(更多信息)
- 用户输入:代码格式化。占位符作为尖括号中的连字符单词,默认为小写或大写以匹配环境变量等约定。例如
<your-root-directory>或<YOUR-API-KEY>。 - 文件名、目录名和路径:代码格式。
- 确保品牌名称准确匹配。例如:“GitHub”,而不是“Github”。
数字、日期和时间
用字母写 0 到 9,用数字写 10 及以上。
明显的例外:
- 小数:始终使用数字,即使小于 10(例如 3.5,而不是三点五)
- 百分比:使用数字(例如 5%,而不是百分之五)
- 版本和其他技术字符串:使用数字(例如 n8n 2.1,步骤 3)
- 测量单位:使用数字(例如 5px、3MB)
日期和时间
- 拼写出月份,不要使用序数词:“July 31, 2016”,而不是“31/07/2016”或“July 31st”。
- 使用带有空格的“AM”/“PM”:“9 AM”,而不是“9am”。
范围
- 在散文中使用“从 X 到 Y”或“X 到 Y”:“从 5 到 10 个节点”。
- 对于表或标签中的数字范围,请使用短划线 (–),而不是连字符:“5–10”。
- 对于时间,请使用“to”:“上午 9 点到下午 5 点”,而不是“上午 9 点到下午 5 点”。
标点符号和间距
- 句子之间有一个空格,而不是两个。
- 标点符号位于引号内。“选择保存”,而不是“选择保存”。
- 使用牛津逗号。“触发器、节点和凭据”。
- 避免使用破折号 (—)。使用逗号或新句子。 “添加节点,然后保存”,而不是“添加节点 - 然后保存”。
- 避免省略号 (...)。 “配置设置,然后继续”,而不是“配置设置...”。
页面长度和粒度
将内容拆分为主题明确的页面,每个页面涵盖一个概念、任务或参考类别,篇幅应介于庞大的单一页面和零散片段之间。独立完整、按标题组织的页面最适合读者和 AI 工具(原因请参阅面向 agent 的文档)。
长度
- 健康范围: 大约 1,500 到 20,000 个字符(250 到 3,000 个单词),便于读者浏览,也便于 AI 工具检索。
- 少于约 1,500 个字符时合并,因为内容太短,不利于检索。将内容不完整的页面合并到父页面或同级页面中。
- 如果超过约 25,000 个字符,如果页面混合了内容类型(概念、操作方法和参考),或者如果一个部分无限制地增长(例如每个客户端示例的列表),则进行拆分。
- 绝不要超过约 50,000 个字符。 Agents 会截断超出此限制的内容。
如何分割
- 沿着类型或任务边界(概念、操作方法、参考、示例)进行拆分,而不是任意按长度进行拆分。这与读者导航的方式相匹配,并使每个块都围绕一件事。
- 将相关事实放在一页上(类别的所有环境变量,节点的所有参数)。人工智能搜索将相邻内容放在一起,因此邻近性可以保留上下文。
保持每个部分独立
编写每个章节时,应确保读者即使单独打开它、没有相邻章节的上下文,也能理解内容(原因请参阅面向 agent 的文档):
- 编写描述性句式标题。 标题是 AI 搜索检索的单元,通常没有页面的其余部分,因此请完整命名该部分的主题:“配置计划触发器”,而不是“配置”。
- 使每个章节都可以单独理解。 重述关键上下文,不要仅指向其他位置。避免「如上所述」「如上一节所述」和「见下文」,因为当 agent 不按顺序检索章节或读者从搜索进入时,这些引用无法理解。
- 重述,而不是重复。 重复该章节需要的一两个事实,而不是整个段落。如果两个章节需要相同的长篇解释,说明它们应合并到同一标题下。保持重述简短,让页面保持简洁(参阅语言通俗易懂)。
用一句话直接给出答案
紧接 H1 之后、在现有简介、hint 或 include 之前,添加一句通俗易懂的话,直接回答该页面介绍什么(原因请参阅面向 agent 的文档)。
- 说明页面或节点能让读者做什么,并明确指出实际产品、节点或技术,不要只写「它可以让你完成一些操作」。
- 只写一句;只有确实需要简短的限定条件时才写两句。
- 如果现有简介已经以类似句子开头,则无需添加。
例如:「Code 节点让你在工作流中运行自己的 JavaScript 或 Python,从而转换数据,或添加内置节点不支持的逻辑。」
链接到相关页面、先决条件和后续步骤
将每个页面与同一主题的其他页面连接起来(请参阅面向 agent 的文档)。
以下指南不适用于 docs/integrations/(「Nodes」)中的页面,这些页面采用不同的结构。
- 始终链接先决条件和后续步骤。
- 章节入口页面应向下链接到子页面。 有两个或更多子页面时,在「本节内容」标题下以项目符号列出(链接加简短说明)。只有一个子页面时,无需列表,在正文首次提及时添加行内链接即可。
- 子页面应在页面末尾的「相关资源」章节中向上和横向链接。 只列出父页面和每个直接同级页面的链接,不加说明。若页面与父页面的
README.md位于同一文件夹,请用./;若当前页面本身是比父页面低一级的章节入口页面,请用../(参阅父页面)。你也可以自行添加其他真正相关的页面。 - 同级页面超过 10 个时,不要列出同级页面。 只链接父页面即可,父页面的「本节内容」已包含完整列表。
- 本身也是父页面的页面应同时采用两种方式。 它应为子页面提供「本节内容」,并在「相关资源」页脚中链接自己的父页面和同级页面:只向上和横向链接一级,不要链接祖父页面。
- 对于扁平的参考资料集合,不要添加同级链接。 如果每个页面都采用相同的单一事实模板(例如每种表达式数据类型一个页面),只需在「相关资源」中链接父页面。
- 同一主题应争取形成至少五个相互链接的页面集群。
- 在正文首次有意义地提及时添加链接,并使用能指明目标的描述性锚文本,例如配置 Schedule Trigger,而不是「单击此处」。如果正文已提到该主题,应链接现有短语,不要另加一句话。链接不能代替章节所需的上下文;必要时请重述关键事实(参阅确保每个章节独立完整)。
功能可用性
功能的可用性和成熟度可以通过四种方式受到限制:
- 计划或平台:它所在的 n8n 云计划或自托管版本。
- 版本:哪个 n8n 版本引入、弃用或删除了它。
- 预览状态:该功能是否处于 Preview 阶段。
- Enterprise 就绪:该功能是否已达到 Enterprise ready。
计划/平台和版本限制共用同一套文档规范。Preview 状态和 Enterprise 就绪的处理方式不同,始终单独记录。有关各自的含义,请参阅了解功能可用性。
计划、平台和版本限制
在以下三个范围之一记录:
- 页面或章节: 在页面标题或相关章节标题下添加标题为 Feature availability 功能可用性 的
infohint。请参阅功能可用性 hints。 - 行内或顺带提及: 对较大功能中的小选项、字段、角色或行为添加简短说明;或在正文中提到没有独立标题的完整功能或节点时,将限制写入句子。请参阅行内和顺带提及。
- 表格行: 对表格中的某一行,将限制写在描述单元格中;如果多行的限制不同,则添加专用列。请参阅表格行。
功能可用性提示
示例:
计划和版本:
> **提示**
>
**Feature availability**
Environments are available on:
- **n8n Cloud:** Pro, Enterprise
- **Self-hosted:** Enterprise
Available from n8n 2.30.0.
仅版本: 主题可以是功能或节点:
> **提示**
>
**Feature availability**
Canvas Groups are available from n8n 2.28.0.
已弃用或删除使用 warning,而不是 info。将措辞替换为删除(例如,“N8N_RUNNERS_ENABLED 从 n8n 3.0 中删除”)。这里的主题是一个设置:
> **警告**
>
**Feature availability**
`N8N_RUNNERS_ENABLED` is deprecated from n8n 2.0.
如果整个页面都介绍已弃用或删除的功能,还应添加主要 deprecated tag(请参阅 Frontmatter 下的 Tags)。不要添加 status: 字段,因为 deprecated 不是该字段的有效值:
---
tags:
- tag: deprecated
primary: true
---
该标签需要在空间的 .gitbook/tags.yaml 中定义标签“已弃用”和红色。
规则:
- Hint 样式: 弃用或删除时使用
warning(读者必须采取行动),其他情况使用info。同时包含两者时使用warning。 - 在正文中指出主题,而不只依赖标题:hint 标题没有说明什么功能可用,也不要依赖 hint 外部的标题。保持「available from n8n X.Y.Z」为连续短语。仅版本限制的主题可以说明它取代的对象,例如「The Chat Trigger node is available from n8n 1.24.0, replacing the Manual Chat Trigger node.」。
- 平台项目符号: 以「
available on:」开头。始终明确两个平台。两个平台都可用时各列一个项目符号;只在一个平台可用时,列出该平台并在下方说明另一个平台不可用(「It isn't available on n8n Cloud.」/「...self-hosted.」)。如果另一平台仅在特定条件下可用(例如按请求启用),请用限制说明替代不可用说明(例如「On n8n Cloud Enterprise, contact n8n to enable it.」)。 - 层级: 从低到高列出,用逗号分隔,不使用「and」。Cloud 顺序为 Starter、Pro、Enterprise;self-hosted 顺序为 Community、Registered Community、Business、Enterprise。使用准确的大小写名称,并完整写出「Registered Community」。
- 写「n8n Cloud」,不要只写「Cloud」。
- 整个平台: 使用
All plans/All editions,不要列出每一层级。「All plans」包括免费试用(与 Pro 相同);不要单独列出试用,只在试用页面中说明。 - 项目符号下方的顺序: (1) 不可用/限制说明;(2) 版本说明;(3) 其他功能特定限制。
- 没有计划限制时(仅版本、弃用或删除):只保留标题和句子,不使用项目符号。
- 不要链接到 Compare plans and editions 或 release notes。 直接在句子中陈述事实,需要来源时让读者自行搜索。
内联和传递提及
对较大功能中的小控件、选项、字段或角色使用行内措辞;对于正文中提到、没有独立标题的完整功能或节点,也使用行内措辞。页面或章节级限制不适用,应改用 hint。
- 指出具体对象,不要写「此功能」或「此选项」:内容必须能脱离上下文独立理解。
- 每项使用一句;如果计划/平台和版本都适用,可以用两句,并先写计划/平台。
- 如果两个平台都相关,应同时提及;绝不要通过省略来暗示不可用。
- 直接说明版本、弃用或删除(「available from n8n X」「deprecated from n8n X」),无需使用 hint 风格的「Available from」开头。
- 如果需要超过两句或需要两个平台项目符号,请提升为指定范围的 hint。
对于控件、选项、字段或角色:
The **Scopes** option is available on n8n Cloud Pro, Enterprise, and self-hosted Enterprise.
The **Legacy format** field is deprecated from n8n 2.30.0.
对于没有自己标题的整个特征或节点,将限制折叠到句子中:
The Data table node (available from n8n 2.17.0) stores data between executions.
The environments feature (n8n Cloud Enterprise, self-hosted Enterprise) lets you promote workflows between instances.
表格行
对于表格中的某一行,使用与行内文本相同的词汇和顺序,并将限制写入描述单元格:
| 变量 | 类型 | 默认值 | 描述 |
|---|---|---|---|
N8N_RUNNERS_ENABLED(已弃用) |
布尔值 | false |
是否启用任务运行程序。从 n8n 2.0 开始弃用;您不再需要设置它。 |
或者,如果多行不同,则添加专用列:
| 变量 | 适用于 | 描述 |
|---|---|---|
N8N_LDAP_ENABLED |
自托管业务、企业 | 是否启用 LDAP 登录。 |
N8N_SMTP_HOST |
所有版本 | SMTP 传出电子邮件的服务器主机名。 |
版本措辞
两种版本类型
n8n 有两种独立的版本号。不要让读者猜测你指的是哪一种。
- 实例版本: n8n release,使用三段式 semver(例如 2.30.0)。用于功能、环境变量、API、CLI 命令和 hooks。
- 节点版本: 节点的版本,通常由两部分组成(例如 4.7)。仅用于节点特定的事实。
在正文中应限定单独出现的版本号:写「n8n 2.30.0」或「node version 4.7」,而不是「version 2」。
写入版本号
遵循数字规范,并对 n8n 实例版本遵循以下规则:
- 产品名称 + 数字: n8n 2.30.0。
- 不使用
v前缀: 不要写「n8n v2.30.0」。 - 不要在「n8n」后写「version」: 不要写「n8n version 2.30.0」。
- 不要在正文中使用行内代码格式: 写 n8n 2.30.0,而不是 n8n
2.30.0。只有版本出现在实际代码片段、命令或文件路径中时才使用代码格式,例如[email protected]、Docker tag 或package.json值。
预览状态
Preview 功能可能会发生破坏性变化,包括 API 结构、导出内容、节点参数或执行结果,n8n 也可能移除它。不要在生产工作流中依赖 Preview 功能。有关完整生命周期,请参阅了解功能可用性。
将「Preview」作为成熟度标签时首字母大写(「is in Preview」「a Preview feature」「In Preview from n8n 2.20.0」),并使用「Preview」而不是「beta」。其他含义(例如 link preview 或 UI preview 操作)仍使用小写。Frontmatter 和 tag 值作为字面标识符,也保持小写(status: preview、tag: preview)。
页面或章节: 将 hint 标题设为 **Preview status**,而不是 **Feature availability**。稳定性和可用性是不同问题,因此应分别使用 hint,而不是让第二个 hint 与可用性 hint 使用同一标签。在正文句子中而不是标题中指出节点或功能,因为读者可能独立浏览 hint:
> **提示**
>
**Preview status**
The Data table node is in Preview and may change in future releases. Avoid relying on it in production workflows.
如果整页都介绍 Preview 功能,还应设置 status: preview 并添加主要 preview tag(请参阅 Frontmatter 下的 Tags):
---
status: preview
tags:
- tag: preview
primary: true
---
有关工作示例,请参阅 建立和管理代理。
内联或传递提及: 对于一个小控件,或以散文命名的整个功能或节点,没有自己的标题:
The **Streaming response** option is in Preview and may change in future releases.
The Data table node is in Preview and may change in future releases.
- 在有帮助时关联版本:「In Preview from n8n 2.20.0」。
- 与 Feature availability 分开。 如果两者都适用,请并列使用(hint + hint,或句子 + 句子),不要合并。
- 行内说明需要超过一句时: 将其提升为页面或章节级 hint。
Enterprise 就绪
有关 Enterprise ready 和 Limited enterprise readiness 的含义,以及它们与 Preview 的区别,请参阅了解功能可用性。
对于满足所有适用 Enterprise 要求的功能,写作「Enterprise ready」;对于未满足的功能,写作「Limited enterprise readiness」(「enterprise」小写,这是 n8n 界面中的原文标签)。Enterprise ready 的功能在文档中不加任何标注,因此不要为它添加 hint。完全不在 Enterprise 上提供的功能不使用此标签,那属于计划或平台限制,应改用 Feature availability hint。
页面或章节: 将 hint 标题设为 **Limited enterprise readiness**,而不是 **Feature availability** 或 **Preview status**。
- 在第一句中写出功能名称。
- 用项目符号列表列出该功能支持的 Enterprise 能力。使用 Enterprise 能力列表中的名称。
- 如果列出的每项能力的就绪程度都相同,请在句子中说明(「partially supports the following Enterprise capabilities」),并只列出名称,就像 n8n Assistant 页面那样。如果程度不同,请在每个名称后加上 Full 或 Partial,如下例所示。
- 最后用一句话说明其他 Enterprise 能力要么不适用于该功能,要么它尚不支持,并接上「See Understand feature availability for the full list of Enterprise capabilities.」。不要列出不支持或不适用的能力,也不要说明 n8n 是否计划弥补差距。
> **提示**
>
**Limited enterprise readiness**
The Example feature has Limited enterprise readiness. It supports the following Enterprise capabilities:
- **SSO:** Full
- **External secrets:** Partial
Other Enterprise capabilities either don't apply to the Example feature or it doesn't support them yet. Refer to [Understand feature availability](https://app.gitbook.com/s/wMJrGrimpx3PxCJpUswm/understand-feature-availability#enterprise-capabilities) for the full list of Enterprise capabilities.
- 与 Preview status 和 Feature availability 分开。 如果适用多项,请将 hint 并列放置,而不要把一个合并到另一个中。
- 不使用视觉标签或 frontmatter。 Limited enterprise readiness 不属于三个允许的视觉标签之一(请参阅 Frontmatter 下的 Tags),也没有对应的
status:值,即使整个页面都在介绍该功能也是如此。
Vale linting
n8n 使用 Vale 按照本指南中的规则检查文档。
该设置包括:
- 存储库根目录中的
.vale.ini文件包含配置。 styles目录,包含样式定义。这包括现成的样式库和 n8n 特定的样式。- GitHub Action,会在每个 PR 上运行 Vale,并直接报告违规项。
您可以在您的计算机上本地运行 Vale,如下所示:
- 按照 Vale 文档查看 安装淡水河谷 CLI。
- 选择是从命令行进行 lint,还是安装文本编辑器插件:
- 运行
vale docs/会检查docs目录中的所有 Markdown 文件 - 或者安装插件并在文本编辑器中自动查看问题。如果使用 VS Code,请安装 ChrisChinchilla 的 vale-vscode。
前题
Frontmatter 位于页面顶部,并且必须是有效的 YAML。 n8n 文档使用以下 frontmatter 字段:
description:页面内容的简短摘要。 n8n 可能会在搜索结果和链接预览中显示它。hidden:设置为true时,从站点的侧面菜单中删除页面。如果页面应出现在菜单中(大多数页面都会出现),请忽略此字段。layout.description.visible:当设置为false时,隐藏渲染页面上的 frontmatter 描述。始终包含此字段并将其设置为false。generated:设置为true时,将页面标记为完全由自动化管理。不要手动更新这些页面。
前面的例子:
---
description: Learn how to merge data streams in your n8n workflows.
layout:
description:
visible: false
---
提示
您可能会在现有 n8n 文档页面上看到其他 frontmatter 字段,例如 contentType、nodeTitle、originalFilePath、originalUrl 和 url。这些支持对预先存在的页面进行迁移管理。不要将它们添加到新页面。
标签
视觉标签 在页面上呈现为标签,如果是 primary: true,也会在侧面菜单中呈现。它仅在空间的 .gitbook/tags.yaml(其标签和颜色)中定义时才会渲染。将其作为对象添加到 tags 数组中:
---
tags:
- release
- tag: preview
primary: true
---
在此示例中,只有 tag: preview 是视觉标签。 release 是一个纯字符串,没有匹配的 .gitbook/tags.yaml 条目,因此它不会呈现任何内容。 tags 数组可以携带像这样的惰性字符串以及真正的视觉标签;它们是不同的东西,而不是第二个视觉标签。
- 必须先在空间的
.gitbook/tags.yaml中定义视觉标签,然后才能应用它:检查它是否存在,如果缺少则添加它。 - 视觉标签只是一个标签。它不会取代页面上的解释性提示。提示是您解释状态含义的地方;标签只是在 UI 中标记它。
- 文档中当前允许的视觉标签集是:已弃用(有关已弃用功能的整个页面)、预览(有关 预览 中的功能的整个页面)和 已存档(不再更新的页面)。不要创建或使用除这三个标签之外的任何视觉标签。
页面导航
每个空间的根目录下都有一个 SUMMARY.md 文件,用于定义侧边栏:出现哪些页面、以什么顺序以及它们如何嵌套。 GitBook 从此文件构建导航,因此在将其添加到 SUMMARY.md 之前,新页面不会出现在侧边栏中。仅创建 .md 文件是不够的。
SUMMARY.md 是一个嵌套的 Markdown 列表。每个条目都使用相对于空间根目录(SUMMARY.md 所在的文件夹)的路径链接到一个页面,包括 .md 扩展名。 README.md 是空间或部分的登陆页面,缩进在其下嵌套页面:
# Summary
* [Administer](README.md)
* [Manage credentials](manage-credentials/README.md)
* [Share credentials securely](manage-credentials/share-credentials-securely.md)
* [Credential overwrites](manage-credentials/credential-overwrites.md)
添加页面时:
- 在正确的
SUMMARY.md中您希望其出现的位置为其添加一行。 - 使用页面标题作为链接文本。它不必与页面标题完全匹配,但要保持紧密。
- 将其缩进其父部分下方以将其嵌套。条目的顺序设置侧栏中的顺序。
当您移动、重命名或删除页面时,请更新其 SUMMARY.md 条目以进行匹配。
Markdown 和 GitBook 块
该站点使用 GitBook 生成。页面使用 Markdown 以及 GitBook 特有的 blocks(callouts、tabs 和其他结构化页面元素)编写。以下章节介绍常用 blocks。
提示
有关每个可用块类型的 Markdown 表示,请参阅 GitBook 文档。
标题
将标题写为纯 Markdown (## Heading text),并采用句子大小写。 GitBook 会自动从标题文本生成可点击的锚点,因此不要自己添加锚点标记。
您将在现有页面上看到明确的锚标记,例如:
## Heading text <a href="#heading-text" id="heading-text"></a>
这些标签会固定稳定的 anchor,因此即使以后修改标题文字,指向标题的链接也能继续工作。修改标题文字时,请保留其 anchor tag,以免现有链接失效。
友情链接
外部链接
使用标准 Markdown 链接语法:
[commits](https://github.com/n8n-io/n8n/compare/[email protected]@0.177.0)
外部链接会自动在新选项卡中打开。
内部链接
链接方式取决于目标页面是在同一空间还是不同空间。 docs/ 下的每个顶级文件夹(例如 build/、deploy/ 和 administer/)都是一个单独的 GitBook 空间。
在同一空间内,使用标准 Markdown 链接语法,链接到目标文件的相对路径,包括其 .md 扩展名。链接到目标文件而不是键入原始路径,因为当页面移动或重命名时,这些引用会自动保持最新。
相对路径取决于目标相对于您正在编辑的页面的位置。以下示例均假设您在此文件树中编辑 current-page.md:
docs/ # docs root
├── build/ # current space
│ ├── README.md # space landing page
│ ├── understand-workflows/ # subfolder (section) in the space
│ │ ├── README.md # section landing page (parent of current-page.md)
│ │ ├── current-page.md # <- you're editing this page
│ │ └── another-page.md # sibling page, same level
│ └── manage-workflows/ # another subfolder in the same space
│ ├── README.md # section landing page
│ └── export-import.md # page in a different subfolder
├── deploy/ # another space
│ ├── README.md # space landing page
│ └── hosting/ # subfolder in another space
│ ├── environment-variables.md # page in a different space
│ └── configure.md # another page in that subfolder
└── administer/ # another space
| 目标位置 | 链接语法 |
|---|---|
| 同一 space 的同一子文件夹 | [link text](another-page.md) |
父页面,且父页面是 README.md |
[link to a parent page](./) |
父页面是命名页面(此文件夹内没有 README.md,例如 connect-to-n8n-mcp-server.md) |
[link to a parent page](connect-to-n8n-mcp-server.md),直接链接该文件,不使用 ./ |
当前页面本身是章节入口页面(README.md)时的父页面 |
[link to a parent page](../),因为 ./ 会指向当前页面,而不是父页面 |
| 同一 space 的不同子文件夹 | [link to a page](../manage-workflows/export-import.md) |
| 不同 space | [link to a page](https://app.gitbook.com/s/<spaceId>/<page-path>) |
父页面
./ 和 ../ 都是不带文件名的目录引用,GitBook 会在任意相对深度将其原生解析为对应文件夹中的 README.md。./ 指向当前文件夹的入口页面,因此只有当当前页面是该文件夹内的子页面时,它才是父页面。如果当前页面本身就是章节入口页面(README.md),./ 会指向自身,此时应使用 ../ 返回上一级的实际父页面。
链接到不同 space 的页面
相对文件路径仅在空格内解析。 GitBook 将空间之间的链接解析为页面引用,而不是文件路径,因此指向另一个空间的 ../../ 路径将不起作用。相反,链接到目标页面的 GitBook URL:
https://app.gitbook.com/s/<spaceId>/<page-path>
由两部分构建 URL:
<spaceId>:目标页面所在 space 的 ID,可在SPACE_INDEX.md中查找。<page-path>:目标页面在其空间文件夹中的路径,并删除.md扩展名。README.md成为其文件夹路径(例如,host-n8n/configure-n8n/README.md就是host-n8n/configure-n8n)。
例如,要从 administer 空间中的页面链接到 deploy 空间中的 docs/deploy/host-n8n/configure-n8n/user-management.md:
[link to a page](https://app.gitbook.com/s/jm0ZYRpZIPWge2ZSiDYO/host-n8n/configure-n8n/user-management)
仅当目标页面位于其他空间时才使用此形式。在当前编辑的空间中,请改用相对 .md 链接。GitBook 虽然能渲染两种形式,但空间 URL 不会参与 GitBook 的重命名跟踪,移动目标页面后链接会失效;在 GitBook 预览中它还可能跳出当前修订版,解析到已发布内容。internal-links CI 检查会将这类链接报告为 same-space-absolute。
docs/ 下的每个顶级文件夹都是一个独立 space。请在代码仓库根目录的 SPACE_INDEX.md 中查找目标 space 的 ID;该文件每天根据各 space 的 GitBook Git Sync 设置生成。
如果您不想手动构建 URL,请在 GitBook 中打开目标页面并复制其链接。如果您没有 GitBook 访问权限,请改用该页面的已发布 https://docs.n8n.io/... 地址。
图片
图片用于补充文字,绝不能单独承载信息(原因请参阅面向 agent 的文档)。读者必须执行或了解的任何内容都应写在正文中:
- 用文本写下每条指令。 屏幕截图可以显示屏幕的样子,但必须写出步骤(“选择 添加触发器,然后选择 按计划”)。切勿在图像内留下设置、值、菜单路径或单击目标的唯一副本。
- 不要截屏文本。 将代码、命令、错误消息和配置值放入代码块或表格中,以便读者可以复制它们,代理也可以阅读它们。不要粘贴终端或代码编辑器的图片。
- 将屏幕截图视为确认,而不是说明。 使用它们来引导读者或确认它们位于正确的位置,与书面步骤一起,而不是代替它们。
每个空间都有一个单独的文件夹来存放其所有图像,位于该空间根目录中的 .gitbook/assets/ 中:
docs/ # docs root
├── build/ # space root
│ ├── .gitbook/
│ │ └── assets/ # all images for this space live here
│ │ └── workflow-overview.png
│ ├── understand-workflows/
│ │ └── current-page.md
│ └── manage-workflows/
│ └── export-import.md
└── deploy/ # another space
├── .gitbook/
│ └── assets/ # all images for this space live here
│ └── hosting-diagram.png
图像必须存储在其使用空间的 .gitbook/assets/ 文件夹中。您无法引用其他空间的资源文件夹中的图像。
使用相对于您正在编辑的页面的路径引用图像。从空间内的任何页面,首先进入空间根目录,然后进入 .gitbook/assets/:
从页面一层开始(例如 build-workflows/manage-workflows/export-import.md):

从两层深度的页面(例如 build-workflows/understand-workflows/current-page.md):

替代文本
始终编写描述性替代文本。它支持辅助功能,并在图像加载失败时显示。
- 描述图像显示的内容,而不是它是什么。 “带有连接到 HTTP 请求节点的计划触发器的工作流画布”,而不是“屏幕截图”。
- 保持在 125 个字符以下。
- 不要以“图像”或“屏幕截图”开头。
图像文件
- 使用 PNG 获取屏幕截图和图表。
- 如果有图标和简单插图,请使用 SVG。
- 保持文件大小合理:提交前压缩 PNG。Squoosh 是免费的浏览器工具。
- 使用小写连字符的文件名:
workflow-overview.png,而不是WorkflowOverview.PNG。
内联图标
如果 UI 元素只以图标显示(例如没有可见文本标签的菜单),请使用带有 data-size="line" 的 HTML <img> 标签将其嵌入行内,使其以文字高度渲染,而不是作为块级图片:
select **Workflow menu** <img src="../.gitbook/assets/three-dots-horizontal.png" alt="Workflow menu icon" data-size="line">
- 将术语加粗,不要将
<img>标签加粗。 - alt 文本使用与加粗术语匹配的
"<名称> icon"格式。 - 图标文件与菜单名称的对应关系请参阅术语和命名。
视频
不要将视频文件存储在 n8n-docs 代码仓库中。请在外部托管视频,例如 YouTube、Loom 或其他受支持的域名,然后嵌入页面。
要嵌入视频,请将 URL 粘贴到嵌入标签内,如下所示:
[https://www.youtube.com/embed/your-video-id](https://www.youtube.com/embed/your-video-id)
代码示例
使用制表符而不是空格。这很重要,因为 n8n 节点 linter 强制执行此约定。 “创建节点”部分中的任何代码示例都可以复制到用户的节点中,如果它们使用空格,则会导致 linter 失败。
使用带有语言标识符的隔离代码块进行语法突出显示:
```typescript
// Your code here
```
// Your code here
GitBook 支持 可选代码块设置。添加标题、换行或行号,以帮助读者:
```typescript
// Your code here
```
// Your code here
显示每个功能的工作示例
对于任何带有代码、表达式或配置表面的内容,请包含一个工作示例。读者和编码人员更依赖示例而不是散文。
- 涵盖常见情况,然后是破坏的情况。 显示直接路径,然后显示边缘情况(空输入、分页、速率限制)和故障(读者看到的错误和修复)。
- 重视多样性胜过数量。三个各自展示不同内容的例子胜过六个几乎相同的例子。不垫;各不相同。
- 内联注释意图。 说明每个示例的作用和原因,这样就不会被误认为是另一条指令。
- 标记每个占位符。 在尖括号中使用连字符,匹配 文本格式:
<your-api-key>或<YOUR-API-KEY>,而不是YOUR_KEY或实际值。 - 结构约束,不要叙述它们。 将参数、默认值和限制放在表或模式块中,而不是段落中。
如果您展示了错误的示例,请将其与旁边的正确示例配对。单独留下的损坏的片段会被复制。
提示
提示(也称为警告或标注)吸引读者注意特定的重要信息。提示样式有四种:info、warning、danger 和 success。按如下方式使用它们:
info用于一般注释、您想要突出的信息以及功能限制框(仅限于某些平台或定价层的功能)。warning如果某物存在风险或意外行为。danger如果某件事具有高安全风险(例如打开到本地 n8n 实例的隧道)或破坏性(如果用户做错了,可能会永久丢失数据)。success用于积极确认或提示。谨慎使用。
不要过度使用提示。如果频繁使用,它们就会失去效力。
使用以下 提示语法:
> **提示**
>
Some hint content.
提示
一些提示内容。
如果您想向提示添加标题块或标题,请添加标题块作为提示的第一行:
> **提示**
>
## This is the hint title/heading
Some hint content.
提示
这是提示标题/标题
一些提示内容。
可折叠块
与提示类似,但折叠了。用户单击以展开。使用它们来补充细节,否则会使页面变得混乱。
可折叠内容是从标准 HTML <details> 块呈现的:
<details>
<summary>Summary text the user clicks</summary>
Some collapsible content. Standard Markdown works inside the block.
</details>
用户点击的摘要文本
一些可折叠的内容。标准 Markdown 在块内工作。选项卡内容
当内容块由于外部考虑因素(平台、编码语言等)而不同时,使用选项卡将其分开可能有用,因此用户只能看到与其相关的内容。谨慎使用选项卡式部分,因为它们可能会影响可发现性。
仅对简短的并行变体使用 tabs(原因请参阅面向 agent 的文档)。整个 tab block 应控制在大约一屏以内(合计约 3,000 个字符)。如果变体内容进一步增长(每个变体都包含完整流程,或有四个及以上内容较多的变体),请取消 tabs,在页面中为每个变体设置独立标题,使其成为完整、独立的章节。只有当合并后的页面会超过页面长度规范,或变体集合会不断增长时,才为每个变体拆分单独页面。将共用设置和说明放在 tab block 外,避免在变体间重复。
像这样表示选项卡式内容:
### First tab
The content is rendered following the normal Markdown syntax. To add a list:
* Item one
* Another item
* Still more items
### Second tab
1. Content for the second tab.
2. No indentation is required.
First tab
内容按照正常的 Markdown 语法呈现。要添加列表:
- 项目一
- 另一项
- 还有更多项目
Second tab
- 第二个选项卡的内容。
- 不需要缩进。
嵌入式工作流程
您可以将 n8n 工作流程嵌入页面中,以便读者可以直接在文档中查看并与之交互。通过模板 API URL 引用已发布的模板:
> **工作流示例** [https://api.n8n.io/workflows/templates/1747](https://api.n8n.io/workflows/templates/1747)
通过获取已发布模板的 ID 并将其添加到 https://api.n8n.io/workflows/templates/ 来查找模板 API URL。