> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/contribute/contribution-guide-for-n8n-docs/style-guide-for-n8n-docs.md). # Style guide for n8n Docs ## Writing style n8n uses the [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/). This page highlights the elements that matter most for n8n Docs and adds our custom style choices. ### Plain language * Clearly explain each step of the process you are documenting. * Use present tense. * Keep your writing as concise as possible. Two free browser apps to help: * [Hemingway](https://hemingwayapp.com/) measures language complexity. There's no fixed rule about what grade to aim for, but the lower the reading grade, the better. * [Lexi](https://rebilly.github.io/lexi/) measures writing complexity in Markdown text, combining several measures into one readability score. Aim for 60 or higher. Most pages should score above that. Watch for these common patterns and prefer the plainer version: | Avoid | Use instead | | ------------------------------------------- | ---------------------- | | utilize, leverage | use | | in order to | to | | functionality, capabilities | features, what it does | | It's important to note that X | X | | n8n provides a powerful, seamless way to... | n8n lets you... | A few rules of thumb: * **Cut filler.** Drop openers like "It's important to note that" or "Simply". * **Avoid marketing language.** Skip "powerful", "robust", "seamless". State what the feature does. * **Cut vague qualifiers.** Drop "very", "quite", "several", or give a specific figure. * **Keep sentences short.** Under 30 words, one idea each. Split anything held together by a semicolon or a second "and". * **Lead with the action, not "There is".** "To schedule a workflow, add a Schedule Trigger", not "There is a node that can schedule workflows". ### Voice and person Write as if you're speaking directly to the reader. * **Use active voice.** "n8n sends the request", not "the request is sent by n8n". * **Address the reader as "you".** "You can add a node", not "Users can add a node". * **Avoid first person.** Name n8n instead of "I", "we", or "our". "n8n recommends", not "we recommend". * **Use contractions.** "Don't" and "you'll", not "do not" and "you will". ### Inclusive language Write for everyone. * **Use "they" for an unknown person.** "Every user can configure their settings", not "his settings". * **Choose gender-neutral terms.** "Chair", not "chairman". "Main", not "master". ### Terminology and naming Use the same term for the same concept everywhere, and prefer the official product term over a plausible synonym (for example, "publish a workflow", not "activate a workflow"). In prose, use sentence case; for a literal UI label or node name, use bold with the product's exact casing. Write the product name as "n8n", lowercase, even at the start of a sentence. See [Terminology and naming](/contribute/contribution-guide-for-n8n-docs/terminology.md) for the full set of terms to use and avoid. ### Text formatting * Headings: sentence case ([more info](https://docs.microsoft.com/en-us/style-guide/scannable-content/headings#formatting-headings)) * UI elements: bold ([more info](https://docs.microsoft.com/en-us/style-guide/procedures-instructions/formatting-text-in-instructions)) * User input: code formatted. Placeholders as hyphenated words in angle brackets, lowercase by default or uppercase to match a convention such as environment variables. For example `` or ``. * File names, directory names, and paths: code formatted. * Make sure you match brand names precisely. For example: "GitHub", not "Github". ### Numbers, dates, and times Write zero to nine in letters, 10 and above in numerals. Obvious exceptions: * **Decimals**: always use numerals, even under 10 (for example, 3.5, not three point five) * **Percentages**: use numerals (for example, 5%, not five percent) * **Versions and other technical strings**: use numerals (for example, n8n 2.1, step 3) * **Units of measurement**: use numerals (for example, 5px, 3MB) **Dates and times** * Spell out the month and don't use ordinals: "July 31, 2016", not "31/07/2016" or "July 31st". * Use "AM"/"PM" with a space: "9 AM", not "9am". **Ranges** * Use "from X to Y" or "X through Y" in prose: "from 5 to 10 nodes". * Use an en dash (–), not a hyphen, for numeric ranges in tables or labels: "5–10". * For times, use "to": "9 AM to 5 PM", not "9 AM–5 PM". [More info](https://docs.microsoft.com/en-us/style-guide/numbers) ### Punctuation and spacing * **One space between sentences**, not two. * **Punctuation goes inside quotes.** "Select Save," not "Select Save". * **Use the Oxford comma.** "triggers, nodes, and credentials". * **Avoid em dashes** (—). Use a comma or a new sentence. "Add a node, then save", not "Add a node — then save". * **Avoid ellipses** (…). "Configure the settings, then continue", not "Configure the settings...". ## Page length and granularity Split content into focused pages, each covering a single concept, task, or reference category, in a middle band between one monolithic page and scattered fragments. Self-contained, heading-structured pages work best for both readers and AI tools (see [Agent-friendly docs](/contribute/contribution-guide-for-n8n-docs/agent-friendly-docs.md) for why). ### Length * **Healthy range:** about 1,500 to 20,000 characters (250 to 3,000 words): scannable for people, retrievable for AI tools. * **Merge if under \~1,500 characters**, too small to retrieve well. Fold stubs into a parent or sibling page. * **Split if over \~25,000 characters**, if the page mixes content types (concept, how-to, and reference together), or if one section grows without bound (such as a list of per-client examples). * **Never exceed \~50,000 characters.** Agents truncate anything past this limit. ### How to split * Split along **type or task** boundaries (concept, how-to, reference, examples), not arbitrarily by length. This matches how readers navigate and keeps each chunk about one thing. * Keep related facts **on one page** (all environment variables for a category, all parameters for a node). AI search keeps adjacent content together, so proximity preserves context. ### Keep each section self-contained Write each section so a reader who lands on it alone, without its neighbours for context, can still understand it (see [Agent-friendly docs](/contribute/contribution-guide-for-n8n-docs/agent-friendly-docs.md) for why): * **Write descriptive, sentence-case headings.** The heading is the unit AI search retrieves, often without the rest of the page, so name the section's topic in full: "Configure the Schedule Trigger", not "Configuration". * **Make each section understandable on its own.** Restate the key context instead of pointing back to it: avoid "as mentioned above", "as described in the previous section", and "see below", which break for an agent retrieving this section out of order or a reader arriving from search. * **Restate, don't duplicate.** Repeat the one or two facts the section needs, not whole paragraphs. If two sections need the same long explanation, that's a sign they belong together under one heading. Keep restatements short so the page stays concise (see [Plain language](#plain-language)). ### Lead with a one-sentence answer Add one plain-language sentence directly after the H1, before any existing intro, hint, or include: a concrete answer to what the page is about (see [Agent-friendly docs](/contribute/contribution-guide-for-n8n-docs/agent-friendly-docs.md) for why). * State what the page or node lets the reader do, naming the actual product, node, or technology, not "it lets you do things." * One sentence; two only if a short qualifier is genuinely needed. * Skip it if the existing intro already opens with a similar sentence. For example: "The Code node lets you run your own JavaScript or Python inside a workflow, so you can transform data or add logic the built-in nodes don't cover." ### Link to related pages, prerequisites, and next steps Connect each page to the others on its topic (see [Agent-friendly docs](/contribute/contribution-guide-for-n8n-docs/agent-friendly-docs.md)). **These guidelines below don't apply to `docs/integrations/` ("Nodes") pages**, which use a different structure. * **Always link prerequisites and the next step**. * **Section landing pages link down to children.** Two or more children: list under an "In this section" heading as bullets (link + short description). One: skip the list, and link it inline at first mention instead. * **Child pages link back up and sideways, in a "Related resources" section at page-end.** A bare link to the parent, plus one to each direct sibling, no descriptions. Use `./` for the parent if the page shares a folder with the parent's `README.md`, or `../` if the page is itself a section landing page one level below the parent (see [Parent pages](#parent-pages)). Add other genuinely related pages at your discretion. * **Past 10 siblings, drop the sibling list.** Link only the parent (its "In this section" already has the full list). * **A page that is itself a parent does both.** It has its own "In this section" for children, plus a "Related resources" footer for its own parent and siblings: one level up and sideways only, never to a grandparent. * **Skip sibling links for flat reference collections** where every page follows the same one-fact template (for example, one page per expression data type). Link back to the parent only in "Related resources". * **Aim for a cluster of five or more interlinked pages** on the same topic. * **In prose, link at first meaningful mention only**, with descriptive anchor text naming the target (for example, [Configure the Schedule Trigger](https://github.com/n8n-io/n8n-docs/tree/main/docs/contribute/contribution-guide-for-n8n-docs/configure-schedule-trigger.md), not "click here"), reusing an existing mention of the topic rather than adding a sentence for it. A link can't substitute for context the section needs; restate the key fact instead if so (see [Keep each section self-contained](#keep-each-section-self-contained)). ## Feature availability A feature's availability can be limited in three ways: * **Plan or platform**: which n8n Cloud plan or self-hosted edition it's on. * **Version**: which n8n version introduced, deprecated, or removed it. * **Preview status**: whether it's still stabilizing, may change, or isn't rolled out to everyone yet. [Plan/platform and version limits](#plan-platform-and-version-limits) share one documentation system. [Preview status](#preview-status) works differently and is always documented separately. ### Plan, platform, and version limits Document at one of three scopes: * **Page or section:** an `info` hint titled **Feature availability**, under the page title or the relevant heading. See [Feature availability hints](#feature-availability-hints). * **Inline or passing mention:** a short note next to a small option, field, role, or behavior, or a whole feature or node named in prose with no heading of its own - fold the limit into the sentence. See [Inline and passing mentions](#inline-and-passing-mentions). * **Table row:** one row among many; put the limit in the description cell, or a dedicated column if several rows differ. See [Table rows](#table-rows). #### Feature availability hints Examples: **Both plan and version:** ``` {% hint style="info" %} **Feature availability** Environments are available on: - **n8n Cloud:** Pro, Enterprise - **Self-hosted:** Enterprise Available from n8n 2.30.0. {% endhint %} ``` **Version only**: the subject can be a feature or a node: ``` {% hint style="info" %} **Feature availability** Canvas Groups are available from n8n 2.28.0. {% endhint %} ``` **Deprecated or removed** uses `warning`, not `info`. Swap the wording for a removal (for example, "`N8N_RUNNERS_ENABLED` removed from n8n 3.0"). The subject here is a setting: ``` {% hint style="warning" %} **Feature availability** `N8N_RUNNERS_ENABLED` is deprecated from n8n 2.0. {% endhint %} ``` If the entire page is about a deprecated or removed feature, also add a primary `deprecated` tag (see [Tags](#tags), under Frontmatter). Don't add a `status:` field, since `deprecated` isn't a verified value for it: ``` --- tags: - tag: deprecated primary: true --- ``` The tag needs label "Deprecated" and color red defined in the space's `.gitbook/tags.yaml`. Rules: * **Hint style:** `warning` for deprecation or removal (reader must act); `info` otherwise. A combined hint uses `warning`. * **Name the subject in the body**, not just the title: the hint title doesn't say what's available, and don't rely on an outside heading either. Keep "available from n8n X.Y.Z" unbroken. A version-only subject can name what it replaces, for example, "The Chat Trigger node is available from n8n 1.24.0, replacing the Manual Chat Trigger node." * **Platform bullets:** lead with " \ available on:". Always name both platforms. Both: one bullet each. One only: that bullet plus an absence line below it ("It isn't available on n8n Cloud."/"...self-hosted."). Available elsewhere only conditionally (for example, on request): a caveat line replaces the absence line (for example, "On n8n Cloud Enterprise, contact n8n to enable it."). * **Tiers:** low to high, comma-separated, never "and". Cloud: Starter, Pro, Enterprise. Self-hosted: Community, Registered Community, Business, Enterprise. Use exact capitalized names; spell out "Registered Community". * **Write "n8n Cloud", never bare "Cloud".** * **Whole platform:** write `All plans`/`All editions`, not every tier. "All plans" includes the free trial (mirrors Pro); never list the trial itself, cover it only on the trial page. * **Order below the bullets:** (1) absence/caveat line, (2) version sentence, (3) other feature-specific caveats. * **No plan limit** (version-only, deprecation, removal): just the title and sentence, no bullets. * **Don't link to Compare plans and editions or release notes.** State the fact in the sentence and let readers search if needed. #### Inline and passing mentions Use inline wording for a small control, option, field, or role within a larger feature, or for a whole feature/node named in prose with no heading of its own. Not for a page- or section-wide limit (use a hint instead). * Name the specific thing, not "this feature" or "this option": it must stand alone out of context. * One sentence per item; two if both plan/platform and version apply (plan/platform first). * Mention both platforms if both matter; never imply absence by omission. * State version, deprecation, or removal plainly ("available from n8n X", "deprecated from n8n X"). Skip the hint's "Available from" lead-in. * More than two sentences, or both platform bullets needed: promote to a scoped hint instead. For a control, option, field, or role: ``` 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. ``` For a whole feature or node with no heading of its own, fold the limit into the sentence: ``` 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. ``` #### Table rows For one row among many, using the same vocabulary and ordering as inline text. Put the limit in the description cell: | Variable | Type | Default | Description | | ---------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------- | | `N8N_RUNNERS_ENABLED` (deprecated) | Boolean | `false` | Whether task runners are enabled. Deprecated from n8n 2.0; you no longer need to set it. | Or add a dedicated column if several rows differ: | Variable | Available on | Description | | ------------------ | -------------------------------- | ---------------------------------------- | | `N8N_LDAP_ENABLED` | Self-hosted Business, Enterprise | Whether LDAP sign-in is enabled. | | `N8N_SMTP_HOST` | All editions | SMTP server hostname for outgoing email. | ### Versioning wording #### Two version types n8n has two separate version numbers. Never leave the reader guessing which. * **Instance version**: the n8n release, three-part semver (for example, 2.30.0). Use for features, environment variables, APIs, CLI commands, hooks. * **Node version**: a node's version, usually two parts (for example, 4.7). Use only for node-specific facts. Qualify bare numbers in prose: "n8n 2.30.0" or "node version 4.7", not "version 2". #### Writing version numbers Follow the [numbers guidance](#numbers-dates-and-times), plus for n8n instance versions: * **Product name + numerals**: n8n 2.30.0. * **No `v` prefix**: not "n8n v2.30.0". * **No "version" after "n8n"**: not "n8n version 2.30.0". * **No inline code formatting in running text**: write n8n 2.30.0, not n8n `2.30.0`. Use code formatting only when the version appears in an actual snippet, command, or file path, for example, `n8n@2.30.0`, a Docker tag, or a `package.json` value. ### Preview status A Preview feature is available but not yet complete or stable, and may change. Capitalize "Preview" as the maturity label ("is in Preview", "a Preview feature", "In Preview from n8n 2.20.0"); use "Preview", not "beta". Leave unrelated senses of the word (a link preview, a UI preview action) lowercase. Frontmatter and tag values stay lowercase (`status: preview`, `tag: preview`) as literal identifiers, not prose. **Page or section:** title the hint `**Preview status**`, not `**Feature availability**`. Stability and availability are different questions, so each gets its own hint rather than a second one with the availability hint's label. Name the node or feature in the sentence below, not the title (hints are skimmed independently of surrounding headings): ``` {% hint style="info" %} **Preview status** The Data table node is in Preview and may change in future releases. Avoid relying on it in production workflows. {% endhint %} ``` If the whole page covers a Preview feature, also set `status: preview` and add a primary `preview` tag (see [Tags](#tags), under Frontmatter): ``` --- status: preview tags: - tag: preview primary: true --- ``` See [Build and manage agents](/build/build-and-manage-agents.md) for a working example. **Inline or passing mention:** for a small control, or a whole feature or node named in prose with no heading of its own: ``` 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. ``` * **Tie to a version when helpful**: "In Preview from n8n 2.20.0". * **Keep separate from Feature availability.** If both apply, stack them (hint + hint, or sentence + sentence) rather than folding one into the other. * **An inline note needing more than one sentence**: promote to a page- or section-level hint instead. ## Vale linting n8n uses [Vale](https://vale.sh/) to lint documentation against the rules in this guide. The setup comprises: * A `.vale.ini` file in the root of the repo, containing the configuration. * A `styles` directory, containing the style definitions. This includes off-the-shelf style libraries and n8n-specific styles. * A GitHub Action that runs Vale on every PR and reports violations directly on it. You can run Vale locally on your machine as follows: 1. Follow the Vale docs to [install Vale CLI](https://vale.sh/docs/install). 2. Choose whether to lint from the command line, or install a text editor plugin: 1. Running `vale docs/` lints all Markdown files in the `docs` directory 2. Or install a plugin and view problems automatically in your text editor. If using VS Code, install [vale-vscode](https://github.com/ChrisChinchilla/vale-vscode) by ChrisChinchilla. ## Frontmatter Frontmatter sits at the top of a page and must be valid YAML. n8n Docs uses the following frontmatter fields: * `description`: A short summary of the page content. n8n may display it in search results and link previews. * `hidden`: When set to `true`, removes the page from the site's side menu. Omit this field if the page should appear in the menu (most pages do). * `layout.description.visible`: When set to `false`, hides the frontmatter description on the rendered page. Always include this field and set it to `false`. * `generated`: When set to `true`, marks the page as fully managed by an automation. Don't update these pages manually. Frontmatter example: ``` --- description: Learn how to merge data streams in your n8n workflows. layout: description: visible: false --- ``` {% hint style="info" %} You may see other frontmatter fields on existing n8n Docs pages, such as `contentType`, `nodeTitle`, `originalFilePath`, `originalUrl`, and `url`. These support migration management on pre-existing pages. Don't add them to new pages. {% endhint %} ### Tags A **visual tag** renders as a label on the page and, if `primary: true`, in the side menu too. It only renders if it's defined in the space's `.gitbook/tags.yaml` (its label and color). Add it as an object in the `tags` array: ``` --- tags: - release - tag: preview primary: true --- ``` In this example, only `tag: preview` is a visual tag. `release` is a plain string with no matching `.gitbook/tags.yaml` entry, so it renders nothing. The `tags` array can carry inert strings like this alongside a real visual tag; they're a different thing, not a second visual tag. * A visual tag must already be defined in the space's `.gitbook/tags.yaml` before you can apply it: check it exists, and add it if it's missing. * A visual tag is a label only. It doesn't replace the explanatory hint on the page. The hint is where you explain what the status means; the tag just flags it in the UI. * The current set of visual tags allowed in docs is: **Deprecated** (a whole page about a deprecated feature), **Preview** (a whole page about a feature in [Preview](#preview-status)), and **Archived** (a page no longer updated). Don't create or use any visual tag other than these three. ## Page navigation Each space has a `SUMMARY.md` file at its root that defines the sidebar: which pages appear, in what order, and how they nest. GitBook builds the navigation from this file, so a new page won't appear in the sidebar until you add it to `SUMMARY.md`. Creating the `.md` file isn't enough on its own. A `SUMMARY.md` is a nested Markdown list. Each entry links to a page using a path relative to the space root (the folder where `SUMMARY.md` lives), including the `.md` extension. A `README.md` is the landing page for the space or a section, and indentation nests pages under it: ``` # 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) ``` When you add a page: * Add a line for it in the correct `SUMMARY.md`, in the position you want it to appear. * Use the page title as the link text. It doesn't have to match the page's heading exactly, but keep it close. * Indent it under its parent section to nest it. The order of entries sets the order in the sidebar. When you move, rename, or delete a page, update its `SUMMARY.md` entry to match. ## Markdown and GitBook blocks The site is generated with [GitBook](https://www.gitbook.com/). Pages are written in [Markdown](https://commonmark.org/), plus GitBook-specific components called **blocks** (callouts, tabs, and other structured page elements). The sections below cover common blocks. {% hint style="info" %} For the Markdown representation of every available block type, see the [GitBook documentation](https://gitbook.com/docs/creating-content/blocks). {% endhint %} ### Headings Write headings as plain Markdown (`## Heading text`), in sentence case. GitBook generates a clickable anchor from the heading text automatically, so don't add anchor markup yourself. You'll see explicit anchor tags on existing pages, like: ``` ## Heading text ``` These pin a stable anchor, so links to the heading keep working even if its text changes later. If you reword a heading, keep its anchor tag so existing links don't break. ### Links #### External links Use standard Markdown link syntax: ``` [commits](https://github.com/n8n-io/n8n/compare/n8n@0.176.0...n8n@0.177.0) ``` External links automatically open in a new tab. #### Internal links How you link depends on whether the target page is in the **same space** or a **different space**. Each top-level folder under `docs/` (such as `build/`, `deploy/`, and `administer/`) is a separate GitBook space. **Within the same space**, use standard Markdown link syntax and link to the relative path of the target file, including its `.md` extension. Link to the target file rather than typing a raw path, as these references are automatically kept up to date when pages move or are renamed. The relative path depends on where the target sits in relation to the page you're editing. The examples below all assume you're editing `current-page.md` in this file tree: ``` 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 ``` | Target location | Link syntax | | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Same subfolder, same space | `[link text](another-page.md)` | | Parent page, parent is a `README.md` | `[link to a parent page](./)` | | Parent page, parent is a named page (no `README.md` in this folder, for example `connect-to-n8n-mcp-server.md`) | `[link to a parent page](connect-to-n8n-mcp-server.md)`, linking to the file directly, not `./` | | Parent page, when the current page is itself a section landing page (a `README.md`) | `[link to a parent page](../)`, since `./` would point at itself, not the parent | | Different subfolder, same space | `[link to a page](../manage-workflows/export-import.md)` | | Different space | `[link to a page](https://app.gitbook.com/s//)` | #### Parent pages `./` and `../` are bare directory references, which GitBook resolves natively to that folder's own `README.md` at any relative depth. `./` points at the current folder's landing page, which is the parent only when the current page sits inside that folder as a child. If the current page is itself a section landing page (a `README.md`), `./` points at itself instead, so step up with `../` to reach the actual parent one level up. #### Link to a page in a different space Relative file paths only resolve within a space. GitBook resolves links between spaces as page references, not file paths, so a `../../` path into another space won't work. Instead, link to the target page's GitBook URL: ``` https://app.gitbook.com/s// ``` Build the URL from two parts: * ``: the ID of the space the target page lives in. Find it in [`SPACE_INDEX.md`](https://github.com/n8n-io/n8n-docs/blob/main/SPACE_INDEX.md). * ``: the target page's path within its space folder, with the `.md` extension dropped. A `README.md` becomes its folder path (for example, `host-n8n/configure-n8n/README.md` is just `host-n8n/configure-n8n`). For example, to link from a page in the `administer` space to `docs/deploy/host-n8n/configure-n8n/user-management.md` in the `deploy` space: ``` [link to a page](https://app.gitbook.com/s/jm0ZYRpZIPWge2ZSiDYO/host-n8n/configure-n8n/user-management) ``` Use this form only for a page in a *different* space. For a page in the space you're already editing, use a relative `.md` link instead. GitBook renders both forms, but a space URL drops out of GitBook's rename tracking, so the link breaks when someone moves the target page. It also escapes the revision on a GitBook preview, resolving against published content instead of your changes. The `internal-links` CI check reports these as `same-space-absolute`. Each top-level folder under `docs/` is a separate space. Find the space ID for your target space in [`SPACE_INDEX.md`](https://github.com/n8n-io/n8n-docs/blob/main/SPACE_INDEX.md) in the repository root, generated daily from each space's GitBook Git Sync settings. If you'd rather not build the URL by hand, open the target page in GitBook and copy its link. If you don't have GitBook access, use the page's published `https://docs.n8n.io/...` address instead. ### Images Images supplement the text; they never carry information on their own (see [Agent-friendly docs](/contribute/contribution-guide-for-n8n-docs/agent-friendly-docs.md) for why). Put anything the reader must do or know in the prose: * **Write every instruction in text.** A screenshot can show what a screen looks like, but the step ("Select **Add trigger**, then choose **On schedule**") must be written out. Never leave the only copy of a setting, value, menu path, or click target inside an image. * **Don't screenshot text.** Put code, commands, error messages, and configuration values in code blocks or tables, so readers can copy them and agents can read them. Don't paste a picture of a terminal or a code editor. * **Treat screenshots as confirmation, not instruction.** Use them to orient the reader or confirm they're in the right place, alongside the written steps, not instead of them. Each space has a single folder for all its images, at `.gitbook/assets/` in the root of that space: ``` 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 ``` Images must be stored in the `.gitbook/assets/` folder of the space where they're used. You can't reference an image from another space's assets folder. Reference images using a path relative to the page you're editing. From any page within the space, step up to the space root first, then into `.gitbook/assets/`: **From a page one level deep** (for example, `build-workflows/manage-workflows/export-import.md`): ​ `![Alt text](../.gitbook/assets/workflow-overview.png) ​` **From a page two levels deep** (for example, `build-workflows/understand-workflows/current-page.md`): ​ `![Alt text](../../.gitbook/assets/workflow-overview.png) ​` **Alt text** Always write descriptive alt text. It supports accessibility and is displayed if the image fails to load. * Describe what the image shows, not what it is. "Workflow canvas with a Schedule Trigger connected to an HTTP Request node", not "screenshot". * Keep it under 125 characters. * Don't start with "Image of" or "Screenshot of". **Image files** * Use PNG for screenshots and diagrams. * Use SVG for icons and simple illustrations where available. * Keep file sizes reasonable: compress PNGs before committing. [Squoosh](https://squoosh.app/) is a free browser tool. * Use lowercase, hyphenated file names: `workflow-overview.png`, not `WorkflowOverview.PNG`. **Inline icons** When a UI element is only shown as an icon (for example, a menu with no visible text label), embed it inline with an HTML `` tag and `data-size="line"`, so it renders at text height instead of as a block image: ``` select **Workflow menu** Workflow menu icon ``` * Bold the term; don't bold the `` tag. * Set alt text to `" icon"`, matching the bolded term. * See [Terminology and naming](/contribute/contribution-guide-for-n8n-docs/terminology.md) for which icon file maps to which named element. ### Videos Don't store video files in the n8n-docs repository. Host videos externally, for example on YouTube, Loom, or another [supported domain](https://iframely.com/domains), and embed them in the page. To embed a video, paste the URL inside embed tags as follows: ``` {% embed url="https://www.youtube.com/embed/your-video-id" %} ``` ### Code examples Use tabs not spaces. This is important because the n8n node linter enforces this convention. Any code samples in the 'Creating nodes' section could be copied into a user's node, then cause a linter fail if they use spaces. Use fenced code blocks with a language identifier for syntax highlighting: ```` ```typescript // Your code here ``` ```` ```typescript // Your code here ``` GitBook supports [optional code block settings](https://gitbook.com/docs/creating-content/blocks/code-block). Add a title, wrapping, or line numbers when they help the reader: ```` {% code title="MyNode.node.ts" overflow="wrap" lineNumbers="true" %} ```typescript // Your code here ``` {% endcode %} ```` {% code title="MyNode.node.ts" overflow="wrap" lineNumbers="true" %} ```typescript // Your code here ``` {% endcode %} ### Show worked examples for each feature For anything with a code, expression, or configuration surface, include a worked example. Readers and coding agents rely on examples more than prose. * **Cover the common case, then the ones that break.** Show the straightforward path, then edge cases (empty input, pagination, rate limits) and failures (the error the reader sees, and the fix). * **Favour diversity over volume.** Three examples that each show something different beat six near-identical ones. Don't pad; vary. * **Comment the intent inline.** Say what each example does and why, so it isn't mistaken for another instruction. * **Label every placeholder.** Use hyphenated words in angle brackets, matching [Text formatting](#text-formatting): `` or ``, not `YOUR_KEY` or a real value. * **Structure constraints, don't narrate them.** 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. A broken snippet left alone gets copied. ### Hints Hints (also known as admonitions or callouts) draw readers' attention to specific pieces of important information. There are four styles of hint: `info`, `warning`, `danger`, and `success`. Use them as follows: * `info` for general notes, information you want to stand out, and feature restriction boxes (features limited to certain platforms or pricing tiers). * `warning` if something has risks or unexpected behaviours. * `danger` if something is a high security risk (such as opening a tunnel to your local n8n instance), or destructive (the user can permanently lose data if they do this wrong). * `success` for positive confirmations or tips. Use sparingly. **Don't over-use hints. They lose their effectiveness if they're used a lot.** Use the following [hint syntax](https://gitbook.com/docs/creating-content/blocks/hint): ``` {% hint style="info" %} Some hint content. {% endhint %} ``` {% hint style="info" %} Some hint content. {% endhint %} If you want to add a header block, or title, to your hint, add a header block as the first line of the hint: ``` {% hint style="info" %} ## This is the hint title/heading Some hint content. {% endhint %} ``` {% hint style="info" %} ### This is the hint title/heading Some hint content. {% endhint %} ### Collapsible blocks Similar to hints, but collapsed. The user clicks to expand. Use them for supplementary detail that would otherwise clutter the page. Collapsible content is rendered from a standard HTML `
` block: ```
Summary text the user clicks Some collapsible content. Standard Markdown works inside the block.
```
Summary text the user clicks Some collapsible content. Standard Markdown works inside the block.
### Tabbed content When a block of content is different due to external considerations (platform, coding language etc) it **can** be useful to separate it using tabs, so the user sees only the content relevant to them. Use tabbed sections sparingly as they could impact discoverability. Use tabs only for **short** parallel variants (see [Agent-friendly docs](/contribute/contribution-guide-for-n8n-docs/agent-friendly-docs.md) for why). Keep the whole tab block under about one screen (\~3,000 characters combined). When variants outgrow that (a full procedure each, or four or more non-trivial variants), drop the tabs and give each variant its own heading on the page, so each becomes a clean, self-contained section. Split into a page per variant only if the combined page would exceed the [page length guidance](#page-length-and-granularity), or the set of variants is open-ended. Keep shared setup and explanation outside the tabbed block so it isn't repeated across variants. Denote tabbed content like this: ``` {% tabs %} {% tab title="First tab" %} The content is rendered following the normal Markdown syntax. To add a list: * Item one * Another item * Still more items {% endtab %} {% tab title="Second tab" %} 1. Content for the second tab. 2. No indentation is required. {% endtab %} {% endtabs %} ``` {% tabs %} {% tab title="First tab" %} The content is rendered following the normal Markdown syntax. To add a list: * Item one * Another item * Still more items {% endtab %} {% tab title="Second tab" %} 1. Content for the second tab. 2. No indentation is required. {% endtab %} {% endtabs %} ### Embedded workflows You can embed an n8n workflow in a page so readers can view and interact with it directly in the docs. Reference a published template by its template API URL: ``` {% @n8n-blocks/n8n-workflow-demo content="" url="https://api.n8n.io/workflows/templates/1747" %} ``` Find the template API URL by taking a published template's ID and adding it to `https://api.n8n.io/workflows/templates/`. ## Related resources * [Contribution guide for n8n Docs](/contribute/contribution-guide-for-n8n-docs.md) * [Terminology and naming](/contribute/contribution-guide-for-n8n-docs/terminology.md) * [Agent-friendly docs](/contribute/contribution-guide-for-n8n-docs/agent-friendly-docs.md)