-
Notifications
You must be signed in to change notification settings - Fork 367
Styles
n8n uses the Microsoft Writing Style Guide.
- Headings: sentence case (more info)
- UI elements: bold (more info)
- User input: code formatted. Placeholders as hyphenated words in angle brackets. For example
<your-root-directory>. - File names, directory names, and paths: code formatted.
- Make sure you match brand names precisely. For example: "GitHub", not "Github".
Write zero to nine in letters, 10 and above in numerals.
All external links open in new tab. Use the following syntax:
[commits](https://github.com/n8n-io/n8n/compare/[email protected]@0.177.0){:target="_blank" .external-link}
Note that the .external-link class currently doesn't do anything. However, it effectively tags all external links, making them easy to find - and to re-style in future if we want to.
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.
- To accommodate the node linter, we've configured MkDocs to use the preserved_tabs option in the SuperFences extension (more details here), along with some custom CSS to make the tabs a sensible width. Spaces should still display ok, but tabs are safer.
We have access to all the admonitions styles provided by the Material theme. Use them as follows:
-
notefor general notes, information you want to stand out. -
warningif something has risks or unexpected behaviours. -
dangerif 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) -
infofor feature restriction boxes (features limited to certain platforms or pricing tiers)
Don't over-use admonitions. They lose their effectiveness if they're used a lot.
We use an experimental syntax:
/// note | Admonition title
Some admonition content.
///
Similar to admonitions, but are collapsed. The user clicks to expand.
For details we use the main Material theme syntax:
??? note "Admonition title"
Some admonition content.
Note the indentation.
We have a custom collapsible admonition, "Details". You can see an example in the Google Credentials docs.
- Clearly explain each step of the process you are documenting.
- Use present tense, active voice, and "you"-form to address the readers.
- Keep your writing as concise as possible. Hemingway is a free browser app to measure language complexity. There is no fixed rule about what grade to aim for, but the lower the reading grade, the better.
n8n uses Vale and Lexi to lint documentation. Linting supports writing quality, and helps writers use the style guide.
The setup comprises:
- A
.vale.inifile in the root of the repo, containing the configuration - A
stylesdirectory, containing the style definitions. This includes off-the-shelf style libraries for Microsoft, write-good, and alex. - Two GitHub Actions: one to run Vale and one to run Lexi.
Vale is a text linter that checks for spelling, grammar, and style guide adherence. Vale can be run locally (on your machine) or remotely (as part of a CI process) We use the GitHub Action, but we don't currently allow it to fail pull requests, because Vale is detecting some false positives.
- Follow the Vale docs to install Vale CLI.
- Choose whether to lint from the command line, or install a text editor plugin:
- Running
vale --glob='*.md' docswill lint all Markdown files in thedocsdirectory - Or install a plugin and view problems automatically in your text editor. If using VS Code, install vale-vscode by ChrisChinchilla.
- Running
check-vale-results-on-pr.mp4
Vale supports complex rule setups.The Vale docs are a good starting point. There is a playground to help you create rules. The #testthedocs channel in the Write the Docs Slack is a source of support.
In the n8n docs:
-
/stylescontains the dictionaries, style libraries, and most custom rules (some ignore patterns are defined in.vale.ini, which is in the root of the project) -
/styles/config/vocabularies/defaultcontains the two files to add vocabulary to if you want Vale to accept or reject it. For example, you will often need to add brand names toaccept.txt. -
/styles/n8n-stylesis the directory for custom rules.
Lexi measures the complexity of writing in Markdown files. It's the product of extensive research and testing (more info here: https://youtu.be/BRZqQ6AjPc0?si=UZOBUpotnDs-bL0n) It applies several different ways of measuring complexity, to come up with a combined readability score.
The team behind Lexi recommend an ideal combined readability score of 60 or higher. I would suggest this is an absolute minimum: many pages should be far better. For example, the docs homepage (which has a chattier style and some custom formatting that Lexi fails to ignore) is still ~64. Most pages should be better than this.
These are the targets for each individual measure:
Metric Range Ideal score Flesch Reading Ease 100 (very easy read) to 0 (extremely difficult read) 60 Gunning Fog 6 (very easy read) to 17 (extremely difficult read) 8 or less Auto. Read. Index 6 (very easy read) to 14 (extremely difficult read) 8 or less Coleman Liau Index 6 (very easy read) to 17 (extremely difficult read) 8 or less Dale-Chall Readability 4.9 (very easy read) to 9.9 (extremely difficult read) 6.9 or less
Lexi adds the report to the conversation on your pull request. If you make changes, Lexi runs again. You can see reports for different commits by clicking edited.