yhzhan.me

The problem this solves is that my reading was scattered across four apps and none of them could show me that a note about snowpack stability and a note about optimisation geometry were the same note.

The shape of it

Notes are flat markdown files in src/content/notes/. There are no folders — topics are the organising axis, so a note’s slug is just its filename and [[a-wikilink]] can never be ambiguous. Two plugins do the work: a remark pass turns [[...]] into real links, and a rehype pass resolves each one’s display text to the target’s actual title and visibly marks the ones whose target does not exist yet. The same syntax is what Obsidian uses, so the editor stays swappable.

The graph is built at compile time from those links plus topic membership — nodes, edges, backlinks and dangling links all come out of one pass over the note bodies. It renders to canvas with a d3 force simulation, and the whole thing is still a static site: no server, no database, no client-side fetch.

Decisions worth recording

Three domain colours, not eight. A force-directed graph is an all-pairs colour problem — any two nodes can land next to each other — and a validated categorical palette only clears the colourblind-separation gates at three chromatic slots under that constraint. So outdoor, technical and business carry hue and everything else is neutral. The alternative was a rainbow that looks informative and isn’t.

Capture friction is the real constraint. A site like this dies if adding a note takes more than a few seconds, so npm run new:note <url> reads the page’s title and author and writes the frontmatter. Topics do not need to exist before being used; npm run check reports the loose ends instead of blocking.

Maturity is stated, not implied. Every note is a seed, growing or evergreen. A one-sentence seed is a legitimate artifact. The alternative — only publishing finished thoughts — is how the whole thing silts up.