---
title: 'How notes work here'
date: 2026-10-16
summary: 'The conventions this knowledge base runs on — frontmatter, wikilinks, topics and maturity. Read this one first.'
status: evergreen
topics: [generative, skiing]
canonical: 'https://yhzhan.me/notes/how-notes-work/'
source:
  type: own
links_to: [terrain-as-a-first-filter]
---
Every file in `src/content/notes/` becomes a page, a node in the
[graph](/graph/), and a row in the [index](/notes/). 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. |

## 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
[[topic: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.

## 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.