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:
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:
```md
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
```yaml
---
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
`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:
```md
## 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:
```md
## 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](/plans-and-limits).
## 4. Article shape
```md
# 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: ``.
- **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](/backup-and-restore-notes-in-notesnook)", 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:
- 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.
