n8n 中文文档

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 帐户。

  1. 打开任何 n8n 文档页面顶部的 复制 下拉列表,然后选择 在 GitHub 上编辑。这将带您进入 n8n 文档 GitHub 存储库 中的页面。
  2. 单击铅笔图标可编辑页面。

如果您是外部贡献者,GitHub 将提示您在进行更改之前分叉存储库。单击分叉此存储库,GitHub 会自动为您创建一个分叉。

  1. 在文本编辑器中进行编辑,然后单击 提交更改 > 建议更改。

GitHub为您准备了拉取请求。

  1. 检查拉取请求的标题和描述,并根据需要进行编辑。如果您满意,请单击 创建拉取请求。

确保您已遵循一般清单,如果您遗漏了任何内容,请根据需要编辑您的 PR。 n8n 文档团队将审核您的拉取请求,如果被接受,则将其合并(发布您建议的修改)。

在本地分叉存储库

此方法适用于较大的更改、新页面或跨多个文件的工作。

先决条件: GitHub账户、git 和本地安装的文本编辑器或 IDE。

  1. 分叉 n8n 文档存储库 上的 GitHub 和 克隆到本地。
  2. 为您的更改创建一个新分支。
  3. 在相关页面中进行更改。如果您添加新页面,请将其添加到空间的 SUMMARY.md 文件中,以便它显示在导航中。请参阅样式指南的页面导航部分。
  4. 使用 淡水河谷 检查您的散文。安装它(macOS 上的 brew install vale — 其他系统请参阅 淡水河谷安装指南),然后从存储库的根目录运行它:

    bash vale docs/ # lint a directory vale docs/path/to/file.md # lint a single file

    Vale 风格规则随存储库一起提供,因此不需要额外的设置。在继续之前修复所有错误和警告。 5. 提交并将您的分支推送到 GitHub。 6. 从您的叉子向 main 打开 拉取请求。

确保您已遵循一般清单,如果您遗漏了任何内容,请根据需要编辑您的 PR。 n8n 文档团队将审核您的拉取请求,如果接受则将其合并。

预览您的更改

当您打开拉取请求时,GitBook 会自动构建更改的预览并将其与 PR 链接起来。在 PR 的 对话 选项卡上,找到底部的检查部分,然后针对您编辑的空间单击 检查文档网站上的实时预览:

拉取请求上的 GitBook 预览链接

然后,您可以检查您的更改在文档网站上的呈现方式。

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

拉取请求上的 GitBook 页面预览评论

无法在本地构建该网站。

打开一个问题

如果您发现问题但不想自己编辑内容,或者想在编写新内容之前提出新内容,则可以打开 GitHub 问题。

  1. 转到 n8n 文档问题页面。
  2. 在创建新问题之前,通过搜索未解决的问题来检查问题是否已存在。
  3. 单击 新问题 并选择最相关的问题类型。
  4. 填写标题和描述。包含尽可能多的详细信息 - 页面 URL、错误或缺失的内容以及您的任何建议。
  5. 单击提交新问题。

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 文档做出贡献,您的贡献是在同一许可证下进行的。有关更多信息,请参阅许可证文档。

获得帮助

如果您对贡献有疑问,可以通过以下几个地方获得帮助:

  • 社区论坛: 在文档类别中发布有关内容、风格或贡献过程的问题。
  • Discord: 加入 #docs 频道以获取更多非正式问题或快速反馈。

为了特别引起文档团队的注意,请在拉取请求或问题中标记 @n8n-io/docs。

相关资源

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