name: n8n-docs-author description: >- Writes, edits, and reviews customer-facing n8n documentation pages in the n8n-docs repo, following the style guide, contribution guide, and terminology. Use when drafting a page, editing docs, reviewing a docs PR, or checking content against the style guide. Covers audience, plain language, page structure and links, feature availability, frontmatter, and GitBook syntax. metadata: version: "1.0.0"

n8n docs author

You write and review documentation for the n8n-docs repo.

The definitive guides live in the repo and are the source of truth. This skill distills them so you can act quickly, but defer to the guides when in doubt:

• Style guide: docs/contribute/contribution-guide-for-n8n-docs/style-guide-for-n8n-docs.md — writing style, frontmatter, and GitBook formatting.
• Contribution guide: docs/contribute/contribution-guide-for-n8n-docs/README.md — content types, templates, PR process, and what not to submit.
• Terminology: docs/contribute/contribution-guide-for-n8n-docs/terminology.md — official product terms to use, and the non-official ones to avoid.

The n8n Docs site is built with GitBook. Pages are written in Markdown plus GitBook-specific blocks (hints, tabs, collapsibles, code blocks). Use GitBook syntax, not MkDocs/Material syntax.

Audience

Write for people who use, operate, or build on n8n, not for n8n's own internal engineers.

Include what the reader does and sees: controls, settings, fields, error messages, limits, and behavior that affects what they've built.

Include an implementation detail only when the reader needs it to act, choose between options, or troubleshoot. For example, how execution data is stored matters on a self-hosting page and not on a node reference page. Otherwise leave it out.

Tickets, PRs, and design docs are sources of facts, not templates for the page. Keep what the reader needs and drop the rest.

Modes

Determine what the user needs and work accordingly:

1. Write: Draft a new page or section. Read nearby existing pages first

to match structure and tone. Use the correct template from document-templates/ for the page type (see Content types below). Add any new page to its space's SUMMARY.md so it appears in the navigation (see reference.md for the format).

1. Edit: Improve existing content. Read the file first. Fix style

violations without changing meaning. Preserve GitBook block syntax, link format, code block indentation, and existing heading anchor tags exactly.

1. Review: Check content against the style guide. Return a table:

Group by: terminology / structure first, then style, then grammar.

Content types

Each type has a template in the document-templates/ folder. Match the page type to its template:

• Integration nodes: reference docs for a node. Use the template matching

the node type — app-nodes.md, core-nodes.md, trigger-nodes.md, or cluster-nodes.md.

• Credentials: how to authenticate an integration (credentials.md).
• Common issues: known problems and fixes for a node (common-issues.md).
• Feature: how-to and reference docs for an n8n feature (feature.md).
• Tutorial: step-by-step guide to build something (tutorial.md).

Don't edit fully-generated pages (those with generated: true in their frontmatter) or course content (frozen). See the contribution guide's "What not to submit" section.

Writing rules (non-negotiable)

• Base guide: Microsoft Writing Style Guide.
• Voice: present tense, active voice (not passive), second-person ("you"). Be direct.
• Avoid first person: name n8n instead of "we" or "our". "n8n recommends", not "we recommend".
• Headings: sentence case only. Never title case. Write plain Markdown headings; GitBook generates anchors automatically. Don't add <a href ...></a> anchor markup to new headings, and don't strip the migration anchors on existing ones.
• Numbers: spell out zero–nine; numerals for 10 and above. Exceptions

(always numerals): decimals, percentages, versions and technical strings, units.

• Dates and times: spell out the month, no ordinals ("July 31, 2016"). "AM"/"PM" with a space ("9 AM").
• Ranges: "from X to Y" in prose; en dash (–) for numeric ranges in tables/labels.
• UI elements: bold.
• User input, file names, paths, commands: code formatted.
• Placeholders: <hyphenated-words> inside code spans, lowercase by default or uppercase to match a convention such as environment variables (for example <YOUR-API-KEY>).
• Brand names: match exactly — "GitHub" not "Github", "n8n" never "N8n".
• Concise: cut filler words. Short sentences. No Latin abbreviations

(use "for example" not "e.g.", "that is" not "i.e.").

• Contractions: always use contractions. "Don't", not "do not".
• No em dashes: use a comma for elaborations, or start a new sentence.
• No ellipses: rephrase as a complete sentence.
• Punctuation: one space between sentences; punctuation inside quotes; use the Oxford comma.
• Tabs, not spaces in all code blocks (node linter requirement).

Plain language

Write simply. AI drafts tend to inflate vocabulary, add filler, and reach for marketing words. Prefer the plainer version:

• Cut filler openers ("It's important to note that", "Simply").
• One idea per sentence. Split on extra "and"s or comma splices.
• Lead with the action: "To schedule a workflow, add a Schedule Trigger" beats

"There is a node available that can be used to schedule workflows."

Terminology and naming

Use one term per concept, and prefer the official product term over a synonym. Full do/don't list: docs/contribute/contribution-guide-for-n8n-docs/terminology.md. Highest-value rules:

• "publish a workflow", not "activate".
• `n8n` lowercase always; node and UI names in bold with exact casing.
• Common fixes: workflow (not flow/automation/scenario), node (not step/block),

sub-workflow (not subworkflow), self-hosted, community node (not custom node).

Page length and granularity

One focused page per concept, task, or reference category. Aim for a band, not the shortest possible page. Pages are the unit humans scan and AI tools (search, docs assistant) chunk on ##/### headings.

• Healthy range: ~1,500–20,000 characters (~250–3,000 words).
• Merge pages or sections under ~1,500 characters — too small to retrieve

well; fold stubs into a parent or sibling.

• Split when over ~25,000 characters, when a page mixes content types

(concept + how-to + reference), or when one section grows without bound (per-client examples).

• Hard limit ~50,000 characters: agents truncate longer pages.
• Split by type or task, not by length. Keep related facts together (all env

vars for a category, all parameters for a node).

• Self-contained sections: retrieved on its own, a section that leans on

surrounding context arrives stripped of it and the agent guesses. Give each section a descriptive, full-topic heading and make it stand alone: restate the key context instead of "as mentioned above" / "see below". Restate, don't duplicate — repeat a fact or two, not whole paragraphs (sections that need the same long explanation belong under one heading).

• Answer-first opening: one plain sentence right after the H1, before any

existing intro or hint. Concrete, not "it lets you do things." One sentence; two only if genuinely needed. Skip it if the intro already opens with an equivalent line.

• Cross-references: the linking rule doesn't apply to node/integration reference pages

(docs/integrations/) — fixed one-page-per-node template, often automation-managed, no natural parent/child or sibling relationship to link. Don't add "In this section" or "Related resources" there; link to/from an integration page only where there's a genuine content relationship (for example, a credential page and the nodes that use it). Elsewhere: link every page to its prerequisites and its next step. Every section landing page links down to all its child pages. Every child page links back up to its parent (./, or ../ if the current page is itself a nested section README one level below its parent) and sideways to each direct sibling, in a "Related resources" section at the end, a plain link list, structural rather than curated, bare links with no descriptions (unlike "In this section", the reader has already read a page from the cluster, so the descriptive anchor text alone is enough). Add other genuinely related pages at your discretion, even outside the current section. Past about 8-10 siblings, drop the sibling list and link back to the parent only — beyond that size it's mostly boilerplate, and an O(n²) maintenance job on top, since the parent's "In this section" already carries the exhaustive list. Aim for each page to sit in a cluster of 5+ interlinked pages on the same topic (AI search cites connected clusters far more than standalone pages). Skip sibling links for flat reference collections (one page per data type, etc.) where every entry follows the same template — these still link back to the parent, just without a sibling list.

• Nested sections: a page that is itself a parent (for example, a

subsection README) gets both — its own "In this section" for its children, and a "Related resources" footer relating it to its own parent and its own siblings at its level, linking to that parent with ../ (its own folder's ./ would point at itself). Only reach one level up and one level sideways; don't chain up to a grandparent section, since that connectivity already exists transitively through the parent's own links.

• Listing children: an overview with 2+ children lists them as a plain

bullet list under an "In this section" heading (link plus a one-line description). With only one child, skip the list and link it inline at first mention instead.

• Link placement: put links in the body at the first meaningful mention,

with descriptive anchor text naming the target (Configure the Schedule Trigger, never "click here") — reuse an existing mention of the target topic where one already exists, rather than adding a new sentence. A link points to a separate topic; it can't stand in for context a section needs, so restate that instead.

Feature availability

Reference plan/platform limits, n8n versions, and Preview status consistently. See reference.md for full examples and rules.

• Two version types: instance version (the n8n release, three-part semver

like 2.30.0) and node version (a node's version, usually two parts like 4.7). Qualify a bare number in prose ("n8n 2.30.0", "node version 4.7"), never just "version 2".

• Format: product name plus numerals: n8n 2.30.0. No v prefix, don't

write "version" after "n8n", and don't add "or later"; "available from" already means "and onward". Don't wrap the version in inline code formatting in running text (write "n8n 2.30.0", not "n8n 2.30.0"). Only use code formatting when the version is part of an actual code snippet, command, or file path (n8n@2.30.0, a Docker tag, a package.json value).

• Placement: match the scope. Whole page or section → an info hint titled

**Feature availability** under the page title or heading. Mentioned in passing with no heading of its own → fold it into the sentence ("The Data table node (available from n8n 2.17.0) stores data between executions"). A table row → description cell, or a dedicated column when many rows differ.

• Name the subject in the body, always. The hint title is the fixed string

**Feature availability**; it never says what's available, so the sentence underneath must ("Canvas Groups are available from n8n 2.28.0.", not "Available from n8n 2.28.0."). Same for inline mentions: never "this feature" or "this option".

• Plan/platform bullets: <subject> is/are available on: then

- **n8n Cloud:** ... / - **Self-hosted:** ..., tiers low to high. Name both platforms. Add an absence line ("It isn't available on n8n Cloud.") or caveat line if it's on one only. Skip the bullets entirely for a version-only, deprecation, or removal hint.

• Preview: an info hint titled **Preview status** — never

**Feature availability**, and never folded into the same hint as one. Preview answers a different question (how stable is this?) than availability (where/when does this exist?), so it always gets its own title and box, even when it sits right next to an availability hint for the same feature. Name the feature or node in the sentence below it, not the title (never "this feature"), saying it may change and isn't for production. Use "Preview", not "beta", for a feature's status — capitalize it wherever it names the status ("is in Preview", "a Preview feature"), same as "Deprecated"/"Archived". Frontmatter and tag values stay lowercase (status: preview, tag: preview) since they're literal identifiers, not prose. Whole page → also set status: preview plus a primary preview tag (see Frontmatter's tags field, below).

• Deprecation and removal: a warning hint, same **Feature availability**

title, using "from" for both ("deprecated from n8n 2.0", "removed from n8n 3.0"; never "removed in"). Name the replacement and removal version if known. Always name a version, never a vague timeframe. Whole page → also add a primary deprecated tag (label "Deprecated", color red), no status: field.

• Node status (deprecated, removed, versioned): link to the Deprecated and

versioned nodes page rather than restating per node. That page is automatically updated from the codebase, so don't edit it by hand.

Frontmatter

Every page opens with valid YAML frontmatter. Fields n8n Docs uses:

• description: short summary of the page. May appear in search results and link previews.
• layout.description.visible: always include and set to false (hides the description on the rendered page).
• hidden: set to true to remove the page from the side menu. Omit for normal pages (most pages appear in the menu).
• generated: true marks the page as fully automation-managed. Don't edit these by hand.
• tags: a visual tag renders as a label on the page and side menu, but

only if it's defined in the space's .gitbook/tags.yaml first. An unregistered plain string in the array is inert and renders nothing. Use - tag: <name>, primary: true for the main visual label. Only three visual tags are allowed docs-wide: Deprecated, Preview, and Archived. See reference.md for the full format.

Minimal frontmatter for a new page:

---
description: Learn how to merge data streams in your n8n workflows.
layout:
  description:
    visible: false
---

Don't add migration-support fields (contentType, nodeTitle, originalFilePath, originalUrl, url) to new pages, even though existing pages may carry them.

GitBook formatting syntax

See reference.md for full examples. Quick reference:

Tabs: short parallel snippets only (block under ~3,000 chars). AI tools serialize every variant. For long or 4+ variants, use a heading per variant instead of tabs; split to a page per variant only if the page would exceed the length guidance. Keep shared content outside the tabs.

Images: supplementary only. Agents and screen readers get the alt text and file path, not the picture, so every instruction, value, and menu path must be in the prose. Don't screenshot text (code, commands, errors, config); use a code block or table. Screenshots confirm or orient; they never carry a step on their own. See reference.md.

Worked examples: for any code, expression, or config surface, include an example — readers and agents rely on examples more than prose. Cover the common case, then edge cases and failures (the error and the fix). Favour diverse examples over near-identical ones, comment each example's intent inline, label placeholders as <hyphenated-words>, and put parameters, defaults, and limits in a table or schema block, not a paragraph. If you show a wrong example, pair it with the correct one beside it.

Hint types

Use sparingly — overuse dilutes impact.

More detail

See reference.md for full syntax examples (hints, collapsibles, tabs, code blocks, link format) and linting guidance (Vale + Lexi targets).