n8n 中文文档

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 功能可用性 的 info hint。请参阅功能可用性 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,如下所示:

  1. 按照 Vale 文档查看 安装淡水河谷 CLI。
  2. 选择是从命令行进行 lint,还是安装文本编辑器插件:
  3. 运行 vale docs/ 会检查 docs 目录中的所有 Markdown 文件
  4. 或者安装插件并在文本编辑器中自动查看问题。如果使用 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):

​ ![替代文本](../.gitbook/assets/workflow-overview.png) ​

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

​ ![替代文本](../../.gitbook/assets/workflow-overview.png) ​

替代文本

始终编写描述性替代文本。它支持辅助功能,并在图像加载失败时显示。

  • 描述图像显示的内容,而不是它是什么。 “带有连接到 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

  1. 第二个选项卡的内容。
  2. 不需要缩进。

嵌入式工作流程

您可以将 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。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。