notesnook/docs/help/coverage-audit.md

Help documentation coverage audit

Notesnook 3.4.x · help site 93 pages · last run 2026-08-01.

Method: mechanical sweeps over the whole contents/ tree, plus targeted verification of every load-bearing claim against the monorepo source (packages/common/src/utils/is-feature-available.ts, packages/crypto/src/, packages/theme/src/theme-engine/types.ts, packages/intl/src/strings.ts, apps/web/src/, apps/mobile/app/).

Where it stands

Pages	93
Orphan pages / dead sidebar links	0 / 0
Pages with a meta description	93 / 93
Pages with pageTitle and keywords	91 / 93 (404, index excluded)
Pages ending in a ## Related pages cluster	90 / 90 (404, docs, index excluded)
Internal links in body content	~810
Gated features (35) documented	35 / 35
Structured data	BreadcrumbList + TechArticle on all 93; HowTo on 57; FAQPage on 13
Images with descriptive alt text	100%
Outstanding screenshot TODOs	24
npm run build	passes — 0 dead internal links, 0 unresolved string keys
Legacy URLs still resolving	71 / 71 (8 section indexes now 301)

Verified against source this run

These were re-derived from the source rather than taken on trust:

Claim	Source	Result
All plan limits and every gated feature	is-feature-available.ts	35 / 35 correct
All 35 <PlanTag> placements	is-feature-available.ts	all correct
Trash cleanup default of 7 days	packages/core/src/collections/settings.ts:65	correct
297 code-block languages	packages/editor/.../languages.json	correct
Encryption primitives	packages/crypto/src/	corrected — see below
Theme scopes / variants / colors	packages/theme/src/theme-engine/types.ts	corrected — see below
Refund windows	apps/web/src/dialogs/buy-dialog/plans.ts	7 / 14 / 30 days, now documented
Keyboard shortcut registry	packages/common/src/utils/keybindings.ts	page regenerates with zero diff

Source bugs from earlier audits — all fixed in the app

The four app-side bugs earlier runs surfaced have since been fixed in the source, and keyboard-shortcuts.md regenerates with no diff:

Bug	Status
strings.none() returned "Cell border width"	fixed — returns None
strings.alignCenter() returned "Alignment"	fixed — returns Align center
sinkListItem bound to Mod-Shift-Down	fixed — page reads Tab
Font-size shortcuts inverted, and Ctrl- macified on Mac	fixed — registry uses Mod-[ / Mod-], and font-size.ts binds from tiptapKeys, so labels and handlers cannot disagree

There are no known outstanding source-side bugs affecting the docs.

Errors found and fixed in this run

Contradictions and wrong facts

• plans-and-limits.md referred to a refund "window listed above" that was never stated. The real windows (7 / 14 / 30 days by billing period) are now documented in their own section and in the FAQ schema.
• Regional pricing was described as Pro-only in the body and as all-plans in the FAQPage schema. Both now say the same verifiable thing.
• The flat "all plans have a 14-day free trial" claim was not verifiable — trial length is server-driven and passed into trialPlanConditions(duration). The page now says the length is shown on the plan before you start it.
• attachments-and-files.md and trash.md gave three different answers to "does deleting attachments free storage". All three now describe storage as a monthly allowance, consistent with the 50MB/mo captions in is-feature-available.ts. See open questions below.
• rich-text-editor-toolbar.md said toolbar config "is automatically synced across all your devices" and then that it is not.
• how-is-my-data-encrypted.md named the cipher "XChaCha-Poly1305-IETF" (it is XChaCha20-Poly1305-IETF, crypto_aead_xchacha20poly1305_ietf) and called the KDF "PKDF". Both corrected; the page now also distinguishes argon2i (key derivation) from argon2id (password hashing), matching keyutils.ts and password.ts.
• custom-themes/introduction.md claimed 10 scopes (there are 11 — titleBar was undocumented), 5 variants (there are 6 — disabled was undocumented) and "12 colors" above a table of 11 (there are 13 — shade and textSelection were missing). The transparency column was also wrong for background and placeholder.
• recovering-your-account.md documented the first and third recovery options and skipped the second ({{backupFileMethod}}), had a truncated two-step Mobile tab, and carried an unresolved <!--Needs Validation--> comment. Mobile recovery is real (apps/mobile/app/components/auth/forgot-password.tsx) and is now documented.
• Two images were wrong: the "clear completed tasks" step pointed at sort-task-icon.png, and the notebook "create a note" steps used the desktop plus button in the mobile tab with "Three dot button" as alt text.
• faqs/what-are-merge-conflicts.md said "which version of the name you want to keep".

Structure

• The VitePress migration dropped the ten README.md section stubs the legacy docgen site served as directory landing pages, so /organizing-notes, /rich-text-editor, /custom-themes, /faqs, /mobile-integration, /desktop-integration, /web-clipper and /inbox-api started returning 404. Every article slug survived the migration unchanged; only these eight moved. They are now 301'd to their cluster hub from contents/public/_redirects. (/ and /importing-notes were already covered by index.md and importing-notes/index.md.)
• backup-and-restore-notes-in-notesnook.md and custom-themes/publish-a-theme.md each had two # H1s, which hid a whole section from the page outline. Both now use one H1.
• app-lock.md had ### headings inside both tab panels, so each appeared twice in the outline with duplicate anchor slugs, plus step numbering that ran across headings and six alt="drawing" images. Rewritten with headings outside the tabs and real UI string keys.
• keyboard-shortcuts.md started at ###, leaving the page outline empty. The generator (scripts/document-keyboard-shortcuts.mjs) now emits ## per category and a ## Related pages block, and the page carries proper SEO frontmatter.
• /self-hosting was commented out of sidebar.mjs while remaining live, canonical and in the sitemap. It is now in the sidebar under Advanced.
• faqs/what-are-merge-conflicts.md had an ### Example: with no H2 parent.
• mobile-integration/pin-notes-to-notifications.md rendered an empty ::: info box.

Accessibility and SEO

• 82 images had useless or missing alt text: 37 reading " in Notesnook", 27 reading "Toolbar" on theme screenshots, 9 alt="drawing", 6 "Step in Notesnook", 2 raw <img> tags with no alt at all, and 1 filename. All now describe what the reader should look for.
• 33 pages had no pageTitle or keywords. All now do.
• 5 pages had a body FAQ section but emitted only TechArticle. They now emit FAQPage (13 pages total, up from 5).
• 4 meta descriptions exceeded 160 characters.
• 32 uses of the banned words "simply", "just", "easily" across 30 files, and two version numbers in body copy ("Starting from v3", "Starting from v2.6.0"), both forbidden by STYLE.md.

Voice and editorial

• faqs/is-there-an-eta.md hotlinked an image from imgs.xkcd.com — a third-party request from a privacy product's help site — and told users that asking about ETAs "is annoying". Rewritten to point at the roadmap and issue tracker.
• First-person asides removed from how-is-my-data-encrypted.md ("that is when I found out"), create-a-theme-with-theme-builder.md ("like me") and publish-a-theme.md, which linked to a maintainer's personal fork.
• The two "login to … attachments" FAQs were 83-word near-duplicates with trailing whitespace in their titles. Both keep their URLs — packages/intl/src/strings.ts:2625 and :2741 link to them from inside the app — and are now distinct, question-shaped pages.
• import-notes-from-standardnotes.md warned that its own steps could not be completed, then presented them anyway. Restructured around the Markdown/plaintext route that actually works.

Open questions that need a product answer

These could not be settled from this repo and are the main risk of a wrong claim shipping:

1. Storage accounting. is-feature-available.ts captions the limit 50MB/mo, 1GB/mo and so on, and storageUsed / totalStorage arrive from the server. Whether the counter is a monthly upload allowance that resets, or a measure of bytes currently stored, is not determinable client-side. The docs now consistently describe it as a monthly allowance that does not return when you delete a file — this needs confirming, and correcting everywhere if it is wrong.
2. Trial length per plan and period, which is server-driven.
3. Monograph 15 MB limit and whether links-and-embeds gating is enforced anywhere client-side.
4. Inbox API 10 MB body cap and 60 req/min rate limit — both server-side.
5. Per-provider "supported formats" checklists, which depend on @notesnook-importer/core rather than this repo.

Screenshots

24 TODO markers remain, in three groups:

Group	Why it isn't captured	Examples
Needs a signed-in account	The capture harness runs logged out on purpose	attachment manager, sync status indicator, 2FA recovery codes, note links panel
Needs a paid plan	Feature is gated	the expiry badge on a note (Pro)
Needs a device or a date	Not reproducible in a browser	Android widgets, quick settings tile, Wrapped (December only)

Five screenshots in contents/public/screenshots/ were captured from a real production build of the web app and are current.

Existing images are old

69 of 81 images date from 2023, 9 from 2024 and 3 from 2026. The app has been through a major redesign since — editor tabs, a restructured settings dialog, the new side menu — so most screenshots predate the UI they illustrate.

Image	Age	Problem
config-toolbar-desktop.png	2023-06	Dialog is titled "Configure toolbar"; the current label is "Customize toolbar"
first-note-desktop.png	2023-02	Toolbar predates the bi-directional note link tool
desktop-enable-app-lock.png	2024	Matches 3.4 except the new Inbox section is missing

The 2023 cohort covering tables (11 images), publishing themes (16), colors, backups and the first-note flow should be re-shot wholesale rather than audited one by one.

Remaining work, in priority order

1. Answer the five open questions above, then correct any page that guessed wrong.
2. Screenshots — 25 TODOs, plus the 2023-era images. The account-gated ones need a throwaway account; the Android ones need a device or emulator.
3. Thin coverage worth deepening: debug logs (other-settings.ts:400, the first thing support asks for), desktop CLI arguments (apps/desktop/src/cli.ts:38-83), the nn:// protocol handler on desktop, and subscription management detail (payment method, cancel trial, mobile restore purchase).

Notes for whoever writes here next

• docs/help/STYLE.md is the contract: verification requirement, plan tags, platform tabs, SEO frontmatter, linking clusters.
• Plan tiers come from packages/common/src/utils/is-feature-available.ts and nowhere else. All 35 gated features are monotonic across tiers, so "Pro includes Essential" is provably true.
• Where keybindings.ts and an editor extension disagree about a shortcut, the extension wins.
• keyboard-shortcuts.md is generated. Edit scripts/document-keyboard-shortcuts.mjs, never the page.
• A frontmatter value containing : must be quoted, or the YAML parser fails the build.
• Some help URLs are linked from inside the app via packages/intl/src/strings.ts. Grep it before renaming or deleting a page.
• contents/v<version>/ is generated build output. Never edit it; edit the root copy, and use npm run fork to preserve old text for an archived version.