Writing notes in MDX

Why MDX?

Plain markdown covers 95% of long-form writing. MDX fills the remaining 5%: runnable components, callouts, interactive demos, or bespoke layouts — all while keeping the familiar markdown syntax around them.

The contract

Every MDX note exports a frontmatter constant:

export const frontmatter = {
  title: "…",
  summary: "…",
  date: "YYYY-MM-DD",
};

Register it once in src/lib/demo/mdx-notes.ts and it joins the rest of /notes — identical URL shape, identical card in the list, identical back-button. Your markdown authors keep writing .md; your designers pick up .mdx when they need components. Everyone stays on the same /notes/[slug] route.

Rendering path

MDX is compiled to a React component at build time. The [slug] route loads the module on demand, reads its frontmatter, and renders the component inside the same ButtercutProse wrapper that markdown uses — so typography, links, code blocks, and syntax highlighting all come for free.