n8n 文档贡献指南
n8n 文档欢迎大家的贡献。本指南涵盖了贡献流程以及要遵循的准则。
简介
n8n Docs 是 n8n 的官方文档,涵盖从入门到高级工作流程自动化的所有内容。它由 n8n 团队维护,但社区贡献可以通过改进解释、更新内容、修复错误等来提供帮助。
所有贡献都必须遵守我们的 行为准则,并遵循本贡献指南以及风格指南中规定的标准。这确保了 n8n 文档的质量和一致性。
n8n 文档内容在我们的 GitHub 存储库上进行管理。该站点是用 吉特书 生成的。页面是用 降价 编写的,具有 GitBook 特定的组件,例如标注、选项卡和结构化页面元素。
本节内容
- n8n 文档的风格指南:编写文档时应遵循的写作风格、格式和结构规则。
- 术语和命名:文档中应使用的 n8n 官方术语,以及应避免的非官方术语。
- 面向代理的文档:介绍 n8n 文档对「面向代理的文档」的定义,以及该标准与风格指南的关系。
贡献类型
以下是参与的主要方式:
修复拼写错误和小错误 纠正拼写错误、损坏的链接或轻微的错误。
改进现有页面 如果解释不清楚、内容过时或页面缺少重要信息,您可以建议修改和添加。
建议新页面 如果您认为文档中完全缺少某些内容,请告诉我们。在编写任何内容之前,打开一个问题来描述所需的内容。这可以让团队确认内容在范围内,并避免重复已经在进行的工作。如果您想在获得批准后自己撰写内容,请务必在问题中提及。
在代码更改的同时更新文档 如果您要在 主 n8n 存储库 上打开 PR — 例如,要添加节点、更改配置选项或修复影响记录行为的错误 — 打开文档 PR 以反映更改。
报告问题 也许您已经在文档中发现了问题,但您无法自行修复。打开一个问题来描述问题所在,n8n 文档团队将处理它。
不应该提交什么
我们不接受以下类型的贡献:
- 对完全生成的页面的修改。这些页面是通过 n8n 工作流程自动生成并保持最新的。如果发现问题,请打开问题,而不是直接编辑页面。您可以通过其 frontmatter 中的
generated: true字段来识别完全生成的页面。 - 任何类型的促销或商业内容,包括将提供商或工具添加到兼容选项的精选列表中。文档中的此类列表通常仅涵盖最广泛使用的选项,而不是详尽的目录 - 我们的目标是保持供应商中立,并且仅在有明确理由时才扩展它们。
- 个人偏好更改 — 进行编辑,用您喜欢的措辞或风格替换已遵循我们风格指南的内容。
- 忽略这些准则的贡献。 如果提交的内容显然没有尝试遵循我们的风格指南或贡献准则,我们可能会在不进行审核的情况下将其关闭。
写作指导
n8n 文档使用简单、直接的第二人称(“您”)语言、现在时和主动语态,遵循 Microsoft 写作风格指南。保持句子简短、没有行话,并使用缩写。
有关完整详细信息,请参阅 n8n 风格指南。
内容类型
n8n 文档使用几种不同的页面类型。了解您正在使用的类型有助于您遵循正确的结构并使用正确的模板。每种类型在 document-templates/ 文件夹中都有一个模板:
- 集成节点:节点的参考文档。使用与节点类型匹配的模板 - 应用程序、核心、触发器 或 集群 节点。
- 凭据:如何验证集成 (模板)。
- 常见问题:节点的已知问题和修复(模板)。
- 功能:n8n 功能 (模板) 的操作方法和参考文档。
- 教程:构建内容的分步指南 (模板)。
使用人工智能起草稿件
使用人工智能工具来帮助起草或改进贡献是很好且受欢迎的。
我们建议将 skills/n8n-docs-author/SKILL.md 上的 n8n 文档技能文件与您选择的 AI 工具一起使用。它是我们风格指南的精炼,为代理提供有关 n8n 风格和文档约定的背景信息。这从一开始就可以产生更好的输出,并减少事后的编辑。
它是如何运作的
如果您在 n8n 文档 GitHub 存储库的本地分支中使用 AI 编码代理,则该技能可以自动加载。例如,存储库根目录下的 CLAUDE.md 文件指向技能处的 Claude 代码,因此您无需执行任何额外操作。
如果您尚未分叉该存储库,或者您使用的工具不会自动加载技能,您仍然可以使用它。将 SKILL.md、reference.md 和风格指南的内容复制到代理的上下文中,然后要求它在编写或审阅您的文档贡献时遵循该指南。
如何使用
要求您的代理人像平常一样撰写或审阅文件。明确模式:
- 写入:“为X编写一个触发节点页面。”
- 编辑:“编辑此页面以修复样式指南违规行为。”
- 评论:“根据样式指南查看此页面。”
为了进行审查,代理会返回按严重性分组的问题表以及建议的修复方案。
投稿方式
您可以通过多种不同的方式做出贡献:
在浏览器中编辑页面
此方法最适合快速编辑单个页面。 GitHub 将指导您进行更改并打开拉取请求(也称为 PR - 将更改添加到文档的正式提案)。
先决条件: GitHub 帐户。
- 打开任何 n8n 文档页面顶部的 复制 下拉列表,然后选择 在 GitHub 上编辑。这将带您进入 n8n 文档 GitHub 存储库 中的页面。
- 单击铅笔图标可编辑页面。
如果您是外部贡献者,GitHub 将提示您在进行更改之前分叉存储库。单击分叉此存储库,GitHub 会自动为您创建一个分叉。
- 在文本编辑器中进行编辑,然后单击 提交更改 > 建议更改。
GitHub为您准备了拉取请求。
- 检查拉取请求的标题和描述,并根据需要进行编辑。如果您满意,请单击 创建拉取请求。
确保您已遵循一般清单,如果您遗漏了任何内容,请根据需要编辑您的 PR。 n8n 文档团队将审核您的拉取请求,如果被接受,则将其合并(发布您建议的修改)。
在本地分叉存储库
此方法适用于较大的更改、新页面或跨多个文件的工作。
先决条件: GitHub账户、git 和本地安装的文本编辑器或 IDE。
- 分叉 n8n 文档存储库 上的 GitHub 和 克隆到本地。
- 为您的更改创建一个新分支。
- 在相关页面中进行更改。如果您添加新页面,请将其添加到空间的
SUMMARY.md文件中,以便它显示在导航中。请参阅样式指南的页面导航部分。 -
使用 淡水河谷 检查您的散文。安装它(macOS 上的
brew install vale— 其他系统请参阅 淡水河谷安装指南),然后从存储库的根目录运行它:bash vale docs/ # lint a directory vale docs/path/to/file.md # lint a single fileVale 风格规则随存储库一起提供,因此不需要额外的设置。在继续之前修复所有错误和警告。 5. 提交并将您的分支推送到 GitHub。 6. 从您的叉子向
main打开 拉取请求。
确保您已遵循一般清单,如果您遗漏了任何内容,请根据需要编辑您的 PR。 n8n 文档团队将审核您的拉取请求,如果接受则将其合并。
预览您的更改
当您打开拉取请求时,GitBook 会自动构建更改的预览并将其与 PR 链接起来。在 PR 的 对话 选项卡上,找到底部的检查部分,然后针对您编辑的空间单击 检查文档网站上的实时预览:

然后,您可以检查您的更改在文档网站上的呈现方式。
预览构建完成后,机器人还会在您的 PR 上发布 GitBook 页面预览 评论,其中包含指向您更改的每个页面的直接链接,因此您不必在导航中找到它们。每次推送都会更新评论。

无法在本地构建该网站。
打开一个问题
如果您发现问题但不想自己编辑内容,或者想在编写新内容之前提出新内容,则可以打开 GitHub 问题。
- 转到 n8n 文档问题页面。
- 在创建新问题之前,通过搜索未解决的问题来检查问题是否已存在。
- 单击 新问题 并选择最相关的问题类型。
- 填写标题和描述。包含尽可能多的详细信息 - 页面 URL、错误或缺失的内容以及您的任何建议。
- 单击提交新问题。
n8n 文档团队将对您的问题进行分类,并在需要更多信息时进行跟进。
一般清单
在提交修改 n8n 文档的拉取请求之前,请确保您的贡献勾选了所有这些框:
- 包含所有必要的文件和图像。
- 所有新页面都会添加到空间的
SUMMARY.md中,以便它们显示在导航中。 - 所有格式均遵循样式指南。
- 您的更改通过了 淡水河谷 散文 linting,没有任何错误(如果您在本地贡献 — 请参阅在本地分叉存储库)。
- 所有链接均有效并指向正确的位置。
- PR 解释了您所做的更改以及这些更改的必要性。
- 您还没有提交不被接受的提交类型
- 您已阅读并接受 行为准则 和 贡献者许可协议。
审核流程
一旦您打开拉取请求,n8n 文档团队将对其进行审核并合并、请求更改或关闭它。以下是我们所期待的:
时间表 团队的目标是尽快审查拉取请求。复杂或大型的贡献可能需要更长时间。在合并主 PR 之前,不会审核与主代码库中的 PR 相关的贡献。
标签 团队使用标签来传达 PR 的状态:
| 标签 | 含义 |
|---|---|
action:awaiting-author |
团队已留下反馈,正在等待您回复或进行编辑 |
action:needs-review |
您的 PR 正在队列中,正在等待技术作者审核 |
action:needs-sme |
您的 PR 需要经过主题专家的审核才能合并 |
status:pending-dev |
您的 PR 链接到未合并的代码更改,一旦合并,将接受审核 |
status:awaiting-release |
链接代码更改已合并,但尚未发布。您的 PR 很快就会被审核 |
status:dev-cancelled |
您的 PR 链接到的代码更改已被取消 — 文档 PR 将关闭 |
status:duplicate |
您的 PR 涵盖与现有 PR 或问题相同的内容 - PR 将被关闭 |
status:outdated |
您的 PR 已被文档的后续更改所取代 - PR 将被关闭 |
quality:low-effort-usable |
您的 PR 可以接受,但只是 - 在审核之前考虑改进它 |
quality:unusable |
您的 PR 不符合贡献准则,将被关闭。如果您做出的多项贡献都被赋予此标签,您将被阻止。 |
quality:disruptive |
您的 PR 引入了会主动损坏文档的更改。您将立即被禁止做出进一步的贡献。 |
查看我们完整的标签集 在我们的 GitHub 存储库上
为什么 PR 可能会被关闭 如果内容超出范围、重复现有文档、不符合风格或贡献指南,或者在请求更改后尚未更新,则拉取请求可能会在不合并的情况下关闭。如果您认为 PR 被错误关闭,欢迎发表评论并要求澄清。
打开拉取请求即表示您同意许可证中描述的条款。
许可证
n8n 已获得公平代码许可。通过向 n8n 文档做出贡献,您的贡献是在同一许可证下进行的。有关更多信息,请参阅许可证文档。
获得帮助
如果您对贡献有疑问,可以通过以下几个地方获得帮助:
为了特别引起文档团队的注意,请在拉取请求或问题中标记 @n8n-io/docs。