notesnook/docs/help

Notesnook Help

The source of help.notesnook.com, built with VitePress.

npm install
npm run dev      # http://localhost:5173
npm run build    # production build; fails on dead internal links
npm run preview  # serve the built site

Where things are

contents/	the articles — a file's path here is its public URL
contents/public/	images and fonts, served from /
.vitepress/config.mts	site config, nav, head
.vitepress/sidebar.mjs	the sidebar — add every new article here
.vitepress/theme/	Notesnook design tokens and self-hosted fonts

UI labels come from the app

Button and menu labels are written as string keys and resolved at build time from @notesnook/intl:

Click on `{{archive}}` to archive the note.

Rename that string in the app and this page updates on the next build. An unknown key fails the build. Run npm run strings to see which hardcoded labels could become keys (-- --fix rewrites them). Don't add strings to packages/intl for the docs — if there's no key, write plain text.

Writing an article

1. Create contents/<section>/<slug>.md with title (short, used in the sidebar) and description (one sentence, used as the search snippet) frontmatter.
2. Add it to the right group in .vitepress/sidebar.mjs.
3. Run npm run build before opening a PR.

Steps that differ per platform go in tabs, which stay in sync across the whole site via key:platform:

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

1. Right click on a note to open the `Note properties` menu.

== Mobile

1. Press the three dot button on a note.

:::

Callouts use VitePress containers — ::: info, ::: tip, ::: warning, ::: danger, ::: details.

Renaming or moving a file changes a live URL that the apps and support replies link to. Don't, unless a 301 goes into contents/public/_redirects with it. Some pages are linked from inside the app via packages/intl/src/strings.ts, and the importer package links to the importing-notes/* slugs — grep both before touching a slug.

Versioning

The docs are versioned by Notesnook version. The latest version lives at the site root, so canonical URLs never move; older versions are served from /v<version>/ and reachable from the version picker in the nav bar.

Older versions are stored as differences, not copies. A page is shared by every version until it actually changes; only then does the old text get its own file. .vitepress/versions.mjs holds LATEST and the list of older versions.

When Notesnook ships a new version:

npm run version -- <next-version>

Nothing is copied — the outgoing version becomes an older version whose pages are all still shared with the root.

When you change a page in a way that doesn't apply to the old version, preserve the old text first, then edit the root copy as usual:

npm run fork -- <old-version> organizing-notes/archive-notes

That writes contents/_versions/<old-version>/organizing-notes/archive-notes.md — the only file that version needs. For a page that didn't exist in an older version, add its path to contents/_versions/<version>/_excluded.txt instead.

npm run versions (run automatically before dev and build) composes the full /v<version>/ trees from the shared pages plus those overrides. The composed trees live in contents/v<version>/ and are gitignored — never edit them.

Archived pages carry a banner linking to the current version of the same page, are excluded from search and the sitemap, and are noindex so they don't compete with the latest docs. Images are shared across versions.

Deployment

.github/workflows/help.publish.yml builds and deploys .vitepress/dist/ to Cloudflare Pages on every push to master that touches docs/help/**.