Help docs — writing conventions

Every page on notesnook.com/help follows these. They cover accuracy, plan tags, SEO and linking.

1. Accuracy is non-negotiable

Never describe UI from memory. Every menu label, settings path, limit, default and plan gate must be traced to source in this monorepo before it is written:

user-facing strings — packages/intl/src/strings.ts
web/desktop UI — apps/web/src/, apps/desktop/src/
mobile UI — apps/mobile/app/
limits and plan gates — packages/common/src/utils/is-feature-available.ts
behaviour, sync, encryption, retention — packages/core/src/

Quote labels by key, not by hand

Don't type a label and hope it stays true. Write the string key and the build resolves it from the app's own catalogue:

Click on `{{archive}}` renders: Click on `Archive`
Open `{{privacyAndSecurity}}` renders: Open `Privacy & security`

Keys come from packages/intl/src/strings.ts — the same catalogue the apps render from — so when someone renames a string in the app, every page quoting it updates on the next build. An unknown key fails the build; it never ships as a placeholder.

Plural entries take a count: {{notebooks:2}}.
npm run strings lists labels that could be keys but aren't; -- --fix rewrites the unambiguous ones.
Never add a string to packages/intl for the docs' sake. If a label has no key — third-party UI, native OS text, a screen that isn't localized — write it as plain text.

If web and mobile differ, both go in the platform tabs. If you cannot verify something, leave it out and flag it — never guess.

2. Frontmatter

---
title: Archive # short sidebar label, 2–3 words
pageTitle: How to archive notes… # optional: SEO <title>, ~60 chars
description: One sentence… # required, <160 chars, becomes the search snippet
keywords: # optional, real search phrases
  - archive notes notesnook
schema: howto # optional: howto | faq | article (default article)
faqs: # required when schema: faq
  - q: …
    a: …
---

schema: howto turns the page's numbered steps into HowTo structured data automatically. schema: faq emits FAQPage structured data from the faqs list — the same Q&As must also appear in the page body.

3. Plan tags

Any feature that needs a paid plan is tagged inline, on the heading that introduces it:

## Set a note to expire <PlanTag plan="pro" />

plan is the lowest plan that unlocks it: essential, pro or believer. Plans are cumulative — a pro tag means Pro and Believer. For platform-limited features add a note:

## Pin a note to your notifications <PlanTag plan="pro" note="Android only" />

Verify the tier in is-feature-available.ts before tagging. Also state the consequence in prose where it matters ("free plans keep 100 versions per note"), and link to Plans & limits.

4. Article shape

# Full human title

One or two sentences: what this is and why someone would want it.

## Task in imperative form

:::tabs key:platform
== Desktop/Web

1. …

== Mobile

1. …

:::

One # H1, first line of the body.
## per task, phrased as an action: "Archive a note", not "Archiving".
Numbered steps, one action each, ideally ≤ 6.
Close with the confirmation state — what the user should now see.
key:platform is mandatory on platform tabs so the choice syncs sitewide. Labels: Desktop/Web, Desktop, Web, Mobile, Android, iOS, Windows, macOS, Linux.
If a feature is missing on a platform, say so in that tab rather than omitting it.

5. Callouts

::: info context · ::: tip shortcut · ::: warning data loss or something irreversible · ::: danger unrecoverable · ::: details folded tangent.

Anything touching the vault, encryption, recovery or deletion must state plainly that Notesnook cannot recover data or passwords for you.

6. SEO

The help site already ranks #1 for high-intent queries like import enex, so each page is a landing page:

Write the H1 as the question a person types. "How do I import notes from Evernote?" beats "Evernote importing".
Use real phrasings in ## headings — "Can I use it offline?", "Why is my note not syncing?" — they win featured snippets.
Answer in the first 40 words after the H1. That paragraph is what Google quotes.
Never leave alt text empty. Describe what the reader should look for: ![The Archive item in the note context menu](/img.png).
Every page ends with a ## Related pages list of 3–6 links with descriptive anchors (the home page, /docs and /404 are exempt — they are already link lists) — "backing up your notes", never "click here". This is what builds the internal link graph.
Link the first mention of any concept that has its own page, in body text, with the concept as the anchor.
Add <GetNotesnook /> to pages people arrive at from search with buying intent — importers, comparisons, "how do I move from X" — placed after the instructions, never before them.
Prefer one page that fully answers a question over three thin pages.

7. Internal linking clusters

Pages are grouped into clusters, each with a hub that links to every member and members that link back to the hub and sideways to siblings:

Cluster	Hub
Importing	Importing notes
Editor	Editor toolbar
Organization	Notebooks
Privacy & security	How is my data encrypted?
Sync	How sync works
Plans	Plans & limits

Any page that mentions a paid feature links to the plans hub. Any page that mentions encryption links to the encryption hub.

8. Things that are not allowed

Undocumented guesses about UI, limits or plan gates.
Version numbers in body copy ("as of v3.2").
"Simply", "just", "easily", "seamlessly", "powerful".
Telling the reader to contact support before the documented steps.
Image paths that don't exist — leave  instead.
Renaming or moving an existing page (its URL is live and linked from the apps). Some pages are linked from inside the app itself via packages/intl/src/strings.ts — grep it before touching a slug.
More than one # H1 on a page, and ##/### headings inside a :::tabs block. Headings in tabs are emitted once per tab, so they show up twice in the page outline with duplicate anchors.
Unquoted frontmatter values containing : — the YAML parser fails the build. Quote them.
Alt text that describes nothing: drawing, a filename, or an unfilled template. Inline UI glyphs ("press the ⋯ button") are the one case where a short label is correct.

7.1 KiB Raw Blame History Unescape Escape