Write docs

This page explains how to run the Nod docs on your computer, how to write a page that reads like the rest of the site, and which components and diagrams you can use.

The short version: write for a busy person who has never seen Nod's code. Lead with the answer. Use short sentences, "you", and a diagram whenever something moves between parts.

Run the docs locally

The docs are an Astro Starlight site in the docs folder. It has its own lockfile, like desktop.

Install the docs dependencies.

pnpm --dir docs install --frozen-lockfile

Start the dev server. It reloads when you save a page.
Terminal
```
pnpm --dir docs dev
```
Open http://localhost:4321/ in your browser.
Before you open a pull request, build the site. The build fails on a broken link or a missing heading anchor.
Terminal
```
pnpm --dir docs build
```

On every pull request that changes the site, the Docs workflow builds it as it ships to nod.n8n.io, checks every internal link, and attaches the built site to the run as the nod-site artifact.

Publish the docs

The docs are live at nod-docs.pages.dev, in the Cloudflare Pages project nod-docs, and under /docs/ on nod.n8n.io. The Docs workflow publishes only nod.n8n.io; see Publish the landing page. Update nod-docs by hand.

Use a Cloudflare account with access to the existing project. Run pnpm dlx [email protected] pages project list to check access. If nod-docs is absent, ask the project's owner for access before continuing. The rename PR records its initial deployment. Do not create a replacement project to update the existing site.

Build the reviewed revision:

pnpm --dir docs install --frozen-lockfile
pnpm --dir docs build

The output is docs/dist. The default site address is https://nod-docs.pages.dev, with no path prefix. Set DOCS_SITE and DOCS_BASE at build time only when publishing to another address or path.

Confirm the Pages project's production branch. For a Direct Upload project, read production_branch through Cloudflare's Get Project API; its dashboard does not expose branch controls. Replace PRODUCTION_BRANCH below with that branch before uploading the built site:

pnpm dlx [email protected] pages deploy docs/dist --project-name nod-docs --branch PRODUCTION_BRANCH

Use a different branch for a preview deployment. Open the returned deployment URL, check the changed pages and their links, then check the live address after a production deployment.

Publish the landing page

The Cloudflare Pages project nod-n8n, at nod-n8n.pages.dev and nod.n8n.io, serves the landing page, src/pages/next.astro, at its root and these docs under /docs/. Its production branch is main. The build puts the docs under /docs/, then copies the landing page and the 404 page to the root. Without a root 404.html, Pages serves the landing page for every unknown address.

Every push to main that changes the site runs the Docs workflow, which builds the site and deploys it. To redeploy without a change, run the workflow on main from the Actions tab. The deploy job runs in the nod-n8n GitHub environment, which only main can use, and reads its CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN secrets. The token needs Cloudflare Pages: Edit on the project's account. That permission covers every Pages project in the account, so keep the token in that environment only.

Where pages live

Directorydocs/
- astro.config.mjs site settings, sidebar and plugins
- Directorysrc/
  - Directorycontent/docs/ every page, one file per page
    index.mdx the home page
    Directoryget-started/
    …
    Directoryuse/
    …
    Directorytrust/
    …
    Directoryconnect/
    …
    Directoryhow-it-works/
    …
    Directorydeploy/
    …
    Directorycontribute/
    …
  - Directoryassets/ images and screenshots
    …
  - styles/theme.css the Nod theme

Each folder under src/content/docs is one sidebar section. The file name becomes the URL, so trust/payments.md is published at /trust/payments/. Set the order inside a section with sidebar.order in the front matter.

Use .md for most pages. Use .mdx only when the page needs a component such as <Steps> or <Tabs>.

Start from this template

---
title: Do the thing
description: One sentence that says what this page helps you do. Search engines and link previews show it.
sidebar:
  order: 3
---

One sentence that answers the question this page is about.

A short paragraph with the context a newcomer needs.

## Do the thing

1. Open **Settings → Example**.
2. Turn on **Example**.

## How it works

A diagram, then two or three short paragraphs.

## Related resources

- [Parent page](/use/chat/)
- [Sibling page](/use/tasks/)

Write like the rest of the docs

Nod's docs follow the n8n docs style, which builds on the Microsoft Writing Style Guide.

Plain language

Avoid	Use instead
utilize, leverage	use
in order to	to
functionality, capabilities	features, what it does
It's important to note that X	X
Nod provides a powerful, seamless way to ...	Nod lets you ...
The owner	you
Pi, the agent, the LLM (in user pages)	Nod, or the model

Lead with the answer. Put one sentence under the title that says what the page lets you do.
Keep sentences short. One idea each, under 25 words. Split anything held together by a semicolon.
Cut filler and marketing. No "simply", "powerful", "robust" or "seamless". Say what happens.
Be exact. Write "for 90 days", not "for a while". Write "Nod asks you", not "Nod may ask".
Lead with the action. "To stop Nod, select Stop", not "There is a button that stops Nod".

Voice and person

Talk to the reader as "you". Name Nod in the third person: "Nod asks", not "we ask".
Use active voice: "The server checks the action", not "The action is checked".
Use contractions: "don't", "can't", "you'll".
Use "they" for an unknown person.

Formatting

Headings use sentence case and say what the section is about: "Approve a payment", not "Payments flow".
UI labels are bold and match the app exactly: Settings → Memory, Sign in again.
File names, commands, settings and code are in code. Placeholders look like <your-key>.
Use the Oxford comma, one space between sentences, and no em dashes or ellipses.
Write numbers from zero to nine as words and 10 or more as numerals, except for versions, sizes and percentages.

Page shape

One page, one job. Split a page when it mixes how-to steps with a long explanation.
Self-contained sections. Someone may land on a heading from search. Restate the one fact the section needs instead of writing "as mentioned above".
Landing pages list their children under In this section, with one line each.
Child pages end with Related resources: a link to the parent and to sibling pages.
Explain limits honestly. If a check doesn't cover something, say so in a caution aside.

Link to other pages

Write internal links as site paths that start and end with /. The build adds any configured DOCS_BASE prefix and checks that every page and heading exists.

See [Approve one payment](/trust/payments/#approve-one-payment).

Link to source files with full GitHub URLs, such as src/server/trust.ts. Link at the first useful mention only.

Components

Import components at the top of an .mdx page:

import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';

Asides

Use an aside for one thing the reader must not miss. Keep it to two sentences.

:::caution[Back up the Vault key]
Saved logins can't be read without it.
:::

Asides work in .md and .mdx pages.

Steps

Wrap a numbered list in <Steps> for a procedure. Each step starts with a verb.

Open Vault.
Select Add, then Login.
Enter the website, username and password, then select Save.

Tabs

Use tabs when the same task differs by platform or setup.

macOS
Linux

Nod keeps the Vault key in the macOS Keychain.

Set NOD_VAULT_KEY in .env before the first start.

Tabs with the same syncKey switch together across the page.

Cards and link cards

Use cards for a short grid of ideas, and link cards to send readers onward.

Card

Two lines at most.

Another card

Starlight's icon names work here.

Trust and VaultHow Nod keeps you in control.

Badges

Mark status inline: Preview Local only New.

<Badge text="Local only" variant="note" />

Code blocks

Give a code block a title when it's a file or a terminal. Mark lines to draw attention.

PORT=4310
NOD_VAULT_KEY=<your-key>
OPENAI_API_KEY=<your-key>

```sh title=".env" {2} ins={3}
PORT=4310
NOD_VAULT_KEY=<your-key>
OPENAI_API_KEY=<your-key>
```

Images

Store screenshots in src/assets/screens and use synthetic data only. Write alt text that says what the image shows.

![Vault with saved logins and the selected login's activity.](../../../assets/screens/vault-light.png)

Diagrams

Draw diagrams with Mermaid in a mermaid code block. They follow the site's light and dark theme. Keep each diagram small: about eight boxes, short labels and one idea. Draw decisions as hexagons, {{Like this?}}, because diamonds grow very tall. Prefer flowchart TD when a left-to-right chart would be wider than about five boxes.

Add a class to highlight a box:

Class	Use it for
`:::accent`	The part the page is about, or you
`:::muted`	Background or optional parts
`:::go`	A step that runs
`:::stop`	A step that is refused or held

Flowchart

Use a flowchart for parts and the paths between them.

flowchart LR
  action[App action] --> check{{Allowed?}}
  check -- yes --> run[Run it]:::go
  check -- not sure --> ask[Ask you]:::accent
  ask -- no --> stop[Don't run]:::stop
  ask -- yes --> run

```mermaid
flowchart LR
  action[App action] --> check{{Allowed?}}
  check -- yes --> run[Run it]:::go
  check -- not sure --> ask[Ask you]:::accent
  ask -- no --> stop[Don't run]:::stop
  ask -- yes --> run
```

Sequence diagram

Use a sequence diagram when the order of messages matters.

sequenceDiagram
  actor You
  participant Nod
  participant Server
  participant Site as Website
  You->>Nod: Read the report with my saved login
  Nod->>Server: Use this account on this website
  Server->>Server: Check task, account and website
  Server->>Site: Fill in and submit privately
  Site-->>Nod: Page after sign-in, secrets masked
  Nod-->>You: Here is the report

State diagram

Use a state diagram for something that moves through a few states.

stateDiagram-v2
  direction LR
  [*] --> Running: claim saved
  Running --> Submitted: entry finished
  Running --> Uncertain: interrupted
  Submitted --> [*]
  Uncertain --> [*]

Check your page

The first sentence answers what the page is for.
Every heading says what its section covers.
Steps start with a verb and match the labels in the app.
Diagrams have eight boxes or fewer and short labels.
No keys, real accounts or private data in text, code or screenshots.
pnpm --dir docs build passes.