Feature Tour

This note exists purely as a reference — every markdown feature, frontmatter field, and site-specific extension available when writing a note, with a live example of each. Nothing here is meant to be read as content; it’s meant to be copied from.

Frontmatter

Every note starts with YAML frontmatter. Only title and date are required:

---
title: My Note
date: 2026-09-09
summary: One line shown in listings and used as the page description.
tags: [research, research/some-subtopic]
draft: false
aliases: [old-slug-this-note-used-to-have]
kind: note
relations:
  - { type: extends, target: some-other-note-id }
updated: 2026-09-10
---

• tags — one or more topic paths (area/subarea/...). The first tag wins ties for which color/cluster a note gets in the graph.
• draft: true — hides the note from all public listings (index, tags, graph, search) without deleting it. Still builds and is viewable directly if you know the URL, in dev.
• aliases — old slugs that should still resolve/backlink to this note if something still links to them by the old id.
• kind — one of note, concept, experiment, review, idea, paper, document. Changes the shape used for this note in the graph (circle, diamond, triangle, pentagon, star, circle, circle respectively). Mostly visual, except document also needs url (see below) and renders a noticeably bigger circle in the graph — it’s an external resource, not a written note.
• relations — typed links to other notes beyond plain wikilinks, e.g. { type: extends, target: other-id } or { type: contradicts, target: other-id }. Rendered as differently-dashed edges in the graph. Any type string works; link/extends/contradicts/cites/topic get their own dash style, anything else falls back to a generic dash.
• updated — an optional last-updated date, separate from date.

Sharing a note privately (see docs/sharing.md in the site repo):

share: 3f9c2a1e8b7d4f60a1c9e2d7b6f4a805 # from `npm run new-share`
shareUntil: 2026-12-31 # optional expiry

A note with share set is published only at /s/<token>/ — it never appears in any listing, tag page, the graph, or search, and no other note’s backlinks reveal it exists.

Paper-specific fields (required together when kind: paper):

kind: paper
authors: [Cover, T. M., Thomas, J. A.]
year: 2006
bibkey: cover2006-elements
doi: 10.1002/047174882X # or arxiv / url — at least one required
venue: Wiley
rating: 5
cites: [some-other-note-id]

Documents — an external resource (a book, a PDF, a GoodNotes link) is just a note with kind: document and a url, conventionally filed under notes/lit/ alongside papers so it’s citable the same way (cites: [lit/some-document-id]):

kind: document
url: https://example.com/my-annotations

Tag it like any note to place it under a topic. It shows up on /notes/documents/, gets a prominent “Open document” link on its own page, and renders as a bigger circle in the graph.

Headings

Use ## and ### (not # — the note’s own title is already the page’s <h1>). Every heading gets a hover-to-reveal # anchor link automatically and is picked up by the table of contents on the right — no extra syntax needed for either.

A third-level heading

Nests under the ## above it in the table of contents.

Prose

A paragraph is just a blank-line-separated block of text. Bold, italic, bold italic, strikethrough, and inline code all work as standard markdown. A regular link opens like normal; the site adds nothing special there.

Wikilinks

The one non-standard-markdown syntax: [[note-id]] links to another note by its id (its path under notes/, without the extension) — e.g. feature-tour links back to this note. Variants:

• [[note-id|Display text]] — custom link text.
• [[note-id#some-heading]] — links straight to a heading on that page.
• [[note-id#some-heading|Display text]] — both together.

A wikilink to a note that doesn’t exist still renders as a link, just flagged as broken by npm run links and shown as a broken edge in the graph — it’s informational, not a build failure.

Lists

Unordered:

• First item
• Second item
  • Nested item
• Third item

Ordered:

1. First step
2. Second step
   1. A nested sub-step
3. Third step

Task lists:

• Done
• Not done yet

Blockquotes

A plain blockquote — for actually quoting something. Renders as an italicized, accent-tinted callout.

Callouts

Note-taking environments — definitions, theorems, proofs, worked examples, and asides — using Obsidian-style > [!TYPE] syntax. Everything is driven off one registry in remark-callout.mjs; adding a type there is a one-line change.

Syntax:

> [!TYPE]        body, no title at all
> [!TYPE] Title  body starts on the next line
> [!TYPE]- Title collapsible, starts closed
> [!TYPE]+ Title collapsible, starts open

A title is everything after the marker up to the first line break — it’s kept as real markdown, not flattened to plain text, so math/formatting in a title still renders ([!THEOREM] Chain rule for $H$ renders the $H$). An explicit -/+ always overrides a type’s own default fold behavior, in either direction, for every type — even ones that aren’t foldable by default.

Assertion environments — the “claim” family, one shared accent, no numbering:

DEFINITION/DEF, THEOREM/THM, LEMMA, PROPOSITION/PROP, COROLLARY/COR all render as this same shared accent (they’re all claims).

FORMULA/FORM renders the same way — use it right after introducing a term, to box up the formula that defines it (as opposed to DEFINITION, which is for the prose definition of the term itself):

Support environments — worked material, not a claim, rendered muted:

EXAMPLE/EG and EXERCISE share this muted styling too.

DERIVATION, SOLUTION, and ALGORITHM share PROOF’s muted styling (ALGORITHM isn’t foldable by default, the other two are).

INTUITION is aside-styled too. GitHub’s original five alert types still work, unchanged, for back-compat with older notes:

Every foldable callout (any -/+ or default-closed type, like PROOF above) shows a small triangle before its title that rotates to point down when expanded — a consistent fold indicator regardless of browser, since native <details> markers don’t animate the same way everywhere.

Nesting works — a [!PROOF] blockquote inside a [!THEOREM] blockquote renders as a folded proof nested inside the theorem, margin capped so it doesn’t stack into a staircase:

Toggle blocks

Plain HTML <details>/<summary> — markdown passes raw HTML straight through, so no special syntax is needed, just write it directly in the note:

Code

Inline: const x = 1.

Fenced, with syntax highlighting, a tab title, and specific lines highlighted:

function greet(name) {
  return `Hello, ${name}!`; // this line is highlighted
}

A terminal-style frame instead of an editor frame:

npm run build

Diff markers, via ins/del line ranges in the fence’s meta string (not inline comments):

```js ins={3} del={2}
function add(a, b) {
  return a - b;
  return a + b;
}
```

Rendered:

function add(a, b) {
  return a - b;
  return a + b;
}

Tables

Math

Inline math: $E = mc^2$.

Block math:

(See entropy-mutual-information for a note that leans on this heavily.)

Diagrams

Fenced ```mermaid blocks render as an actual diagram, not a code block:

flowchart LR
  A[Sender] -->|encodes| B[Channel]
  B -->|noisy| C[Receiver]

Images and figures

A standalone image on its own line (not inline with other text) is automatically wrapped in a <figure>, with its alt text used as the caption:

![A caption describing the image](./diagram.png)

Horizontal rule

Three dashes on their own line:

What you never have to write

These happen automatically and don’t need any markdown:

• Table of contents — generated from ##/### headings.
• Backlinks — “notes that link here” is computed from every other note’s wikilinks/relations, shown at the bottom of the page.
• Reading progress bar — tracks scroll position at the top of the page.
• Local graph — a small graph of this note’s immediate neighborhood, shown alongside the table of contents.
• Heading anchors — the # link that appears next to a heading on hover.