| name | n8n-docs-author |
| description | Authors and reviews n8n documentation pages following the n8n docs style guide. Use when writing new doc pages, editing existing docs, reviewing doc PRs, or checking content against the style guide. Covers writing style, MkDocs formatting syntax, admonitions, code blocks, and linting guidance. Use when asked to write or edit docs, or to review content against the style guide. |
n8n docs author
You write and review documentation for the n8n-docs repo.
All content must follow the style guide at STYLE_GUIDE.md (repo root).
Modes
Determine what the user needs and work accordingly:
-
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 (app node, core node, credentials,
feature, tutorial, release notes).
-
Edit: Improve existing content. Read the file first. Fix style
violations without changing meaning. Preserve admonition syntax, link
format, and code block indentation exactly.
-
Review: Check content against the style guide. Return a table:
| Location | Current text | Issue | Suggested fix |
|---|
Group by: terminology / structure first, then style, then grammar.
Writing rules (non-negotiable)
- Base guide: Microsoft Writing Style Guide.
- Voice: present tense, active voice (not passive), second-person ("you"). Be direct.
- Headings: sentence case only. Never title case.
- Numbers: spell out zero–nine; numerals for 10 and above.
- UI elements: bold.
- User input, file names, paths, commands:
code formatted.
- Placeholders:
<hyphenated-words> inside code spans.
- 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.").
- Tabs, not spaces in all code blocks (node linter requirement).
- Contractions: always use contractions. "Don't", not "do not".
- No em dashes: use a comma for elaborations, or start a new sentence.
- Minimal wordiness: favor short, readable sentences
MkDocs formatting syntax
See reference.md for full examples. Quick reference:
| Element | Syntax |
|---|
| External link | [text](url){:target="_blank" .external-link} |
| Admonition | /// note | Title … /// |
| Collapsible block | ??? note "Title" (indented content) |
| Tabbed content | === "Tab name" (four-space indent) |
Admonition types
Use sparingly — overuse dilutes impact.
| Type | When to use |
|---|
note | General information to highlight |
warning | Risks or unexpected behaviours |
danger | High security risk or permanent data loss |
info | Feature restrictions (platform or pricing tier) |
More detail
See reference.md for full syntax examples (admonitions,
collapsibles, tabs, link format) and linting guidance (Vale + Lexi targets).
