How notes work here

Every file in src/content/notes/ becomes a page, a node in the graph, and a row in the index. Nothing else needs to be registered anywhere.

Frontmatter

Only title and date are required. Everything else earns its place:

Field	Why it exists
summary	Shown in the index and the graph tooltip. Write it for a stranger.
topics	Canonical slugs. Aliases fold automatically — nn lands on neural-networks.
status	seed, growing or evergreen. Honesty about maturity, not a promise.
source	What was consumed. A paper, a podcast, a report — or own for original thinking.
draft	Visible in npm run dev, never in a deploy.
translation	Only on a translation. Written by npm run stamp — see below.

Links are the graph

Write [[slug]] or [[slug|any label you like]] and it becomes both a link and an edge. Topic links work the same way: [[topic:skiing]] tags this note with Skiing mid-sentence, with no frontmatter echo needed.

The same syntax is what Obsidian uses, deliberately — a note body renders correctly in a vault and on this site, so the editor stays swappable.

A link to a note that does not exist yet is not an error, it is a to-do: npm run check lists every dangling link and every topic without a hub page.

Two languages, one note

foo.md and foo.zh.md are the same note. One slug, one set of topics, one node in the graph; the page offers a switch between them. A note written only in Chinese keeps the bare URL rather than being pushed to a sub-path.

The hard part is not having two files, it is keeping them saying the same thing. Editing the English leaves the Chinese quietly wrong, and a stale translation is worse than a missing one, because it reads as current.

So a translation records a hash of the version it was translated from:

translation:
  of: en
  rev: f38473579e4b

Recomputing that hash at build time makes drift a fact rather than a feeling. Not dates, which depend on remembering, and not file timestamps, which git does not preserve. The hash ignores rewrapping — these notes are hard-wrapped, so a one-word edit reflows a paragraph — and ignores topics, status and date entirely, so reorganising the garden never invalidates a translation.

npm run stamp lists what has drifted; -- --diff <slug> shows what moved in the source since. Stamping is always a command, never automatic: it asserts that someone read both versions and they agree, and a stamp applied by a build step would assert that without anyone having checked.

A reader who lands on a translation that has fallen behind is told so, at the top of the page, with a link to the source.

Maturity over polish

A seed is allowed to be one sentence. The alternative — only writing things once they are finished — is how a knowledge base dies. See Terrain as a first filter for one that is still thin on purpose.