Using MDX for component-rich writing
MDX lets you import Astro components directly into prose. Use it when a writing piece needs embedded demos, structured callouts, or interactive diagrams — not for every post.
Plain Markdown handles the vast majority of writing on this site. MDX is the escape hatch for the cases where prose alone is not enough.
When to reach for MDX
The rule of thumb from @portfolio-engine/workflow-kit:
- Use
.mdfor essays, notes, and anything that reads as pure prose. - Use
.mdxwhen the post needs a component — an embedded demo, a metric strip, an interactive diagram.
Avoid MDX for structure you can express in frontmatter. A list of related links belongs in YAML, not in JSX sprinkled through prose.
Component imports work like any ES module
import IframeEmbed from '@portfolio-engine/editorial-theme/components/IframeEmbed.astro';
<IframeEmbed
src="/assets/demos/architecture/"
title="Four-layer architecture"
height={520}
sandbox="allow-scripts"
/>
The import resolves at build time — no runtime JS needed. The component runs in Astro’s static pipeline and its output is plain HTML.
Security note for embedded iframes
<IframeEmbed> validates its src at build time: https:// or a same-origin /path only. http://, data:, and javascript: fail the build. The sandbox attribute is restrictive by default; add permissions narrowly.
What this file demonstrates
This .mdx file is part of the demo-site’s format showcase:
| Format | Used for | Example in this repo |
|---|---|---|
.md | Prose essays, writing posts | writing/two-repo-model.md |
.mdx | Component-rich posts | This file |
.yaml | Structured records, page data | notes/portfolio-engine-at-a-glance.yaml |
.json | Config and profile data | config/site.json, profile/person.json |
Each format is validated by a Zod schema defined in src/content.config.ts.