{
  "$type": "site.standard.document",
  "canonicalUrl": "https://notes.juergen.social/blog/using-mdx-v2",
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreiavs7pin35dsemn6p6kuyvck23poblngadxf6ejag7apw4zjoavgu"
    },
    "mimeType": "image/jpeg",
    "size": 155377
  },
  "description": "Most posts should stay as Markdown. Switch to MDX only when an Astro component belongs inline.",
  "path": "/blog/using-mdx-v2",
  "publishedAt": "2026-02-24T00:00:00.000Z",
  "site": "at://did:plc:2n2ukq3osdu3k37ncpn6hwiy/site.standard.publication/3mn57dpj54425",
  "tags": "MDX",
  "textContent": "import FigureNote from '../../components/FigureNote.astro';\n\nMarkdown handles most writing. Headings, paragraphs, links, lists, quotes, code, images. Stay in Markdown by default.\n\nSwitch to MDX when an Astro component needs to live inside the post — not next to it, not below it, but in the exact place the prose is referring to.\n\nThis file is an MDX file. Watch what FigureNote does here:\n\n<FigureNote title=\"MDX example\">\n  This block is an Astro component called from inside the post. The prose around it does not break,\n  and the component shares the site's design tokens.\n</FigureNote>\n\nThe component sits inline. The article continues. That is the only thing MDX is for.\n\nHow to switch a post to MDX\n\n1. Rename the file from .md to .mdx.\n2. After the frontmatter, import the component:\n\n   \n\n3. Use it like an HTML tag in the body:\n\n   \n\nThat is the whole switch. Markdown still works around the component.\n\nThe example component\n\nThe starter includes one prose component: FigureNote. It is small on purpose.\n\nsrc/components/FigureNote.astro:\n\nIts style lives with the FigureNote.astro component and uses the same tokens as the rest of the theme. If you change --color-blue or --label-tertiary, the note follows.\n\nBuild your own\n\nA useful prose component is small, reads like an HTML element, and earns its place by clarifying the explanation.\n\nGood candidates:\n\n- A callout with a specific tone (note, tip, warning).\n- A side-by-side comparison block.\n- A figure with a richer caption than caption allows.\n- A pull quote that needs different styling from a blockquote.\n\nSkip:\n\n- Decoration between paragraphs.\n- Cards that summarize what the prose already said.\n- Anything with internal state, network calls, or its own routing.\n\nIf a component needs state or behavior, it usually belongs in a page route, not in a post. The post can link to it.\n\nWhere the files live\n\nAstro components imported into MDX can live anywhere under src/components/. The starter keeps prose-specific components there too. FigureNote.astro is one.\n\nComponent-owned CSS can live in the same .astro file as a scoped <style> block:\n\nAstro scopes the style to the component output, so the note can carry its own presentation without adding a global selector.\n\nKeep the source readable\n\nAn MDX file is still a document. Two or three custom blocks per post is plenty. Once a post needs ten components and 50 lines of JSX, it has stopped being writing and started being a page template.\n\nThat is the moment to move the work into a real route under src/pages/ and link to it from a Markdown post.\n\nWhen Markdown wins\n\nIf a post does not need a custom block, leave it as Markdown:\n\n- Faster to read in the editor.\n- Easier to move between blogs.\n- No imports to track.\n- Renders the same way through the theme.\n\nMDX is a small upgrade, not a default. Use it when the upgrade pays for itself.",
  "title": "When to Reach for MDX"
}