Skip to content

Styles

Jump to bottom
Deborah edited this page Jan 25, 2024 · 35 revisions

n8n docs writing style

We base our styles loosely on the Microsoft Writing Style Guide.

Quickstart

Text formatting

  • Headings: sentence case (more info)
  • UI elements: bold (more info)
  • User input: bold, with italics for placeholders (see User input part way down this page for more info)
  • File names, directory names, and paths: code formatted.
  • Make sure you match brand names precisely. For example: "GitHub", not "Github".

Numbers

Write zero to nine in letters, 10 and above in numerals.

More info

Links

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.

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.
  • 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.

Admonitions

We have access to all the admonitions styles provided by the Material theme. Use them as follows:

  • note for general notes, information you want to stand out.
  • 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)
  • info for 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.
///

Collapsible admonition blocks

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.

Linting

n8n uses Vale to lint documentation. Linting supports writing quality, and helps writers use the style 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 for Microsoft, write-good, and alex.

Using Vale

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.

Running Vale locally

  1. Follow the Vale docs to install Vale CLI.
  2. Choose whether to lint from the command line, or install a text editor plugin:
    1. Running vale --glob='*.md' docs will lint 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 by ChrisChinchilla.

View the GitHub Action linting output

check-vale-results-on-pr.mp4

Writing tips

  • Plain language:
    • 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.
Clone this wiki locally