Choosing a Page (File) Format

Every content page is one of three formats. Pick the lightest one that does the job — reach for .mdoc only once you actually need a tag from Adding Components to Your Pages.

Format	Use it when	Pros	Cons
.md	Plain prose — no components, just headings, text, links, images, code blocks. The default; use for most pages.	Simplest format; nothing to learn; fully Keystatic-editable.	No components/tags — asides, cards, etc. aren’t available.
.mdoc (Markdoc)	You need a component — an aside, a card, real embedded source via {% showcode %}, tabs, and so on.	Components via tags, no imports, so the page stays Keystatic-editable; “docs as data, not docs as code.”	A small amount of tag syntax to learn; a typo’d tag renders as literal text rather than failing loudly.
.mdx	You need a genuine JS/component import that Markdoc’s tag set can’t cover. Avoid otherwise.	Full MDX/JSX power — any Astro or framework component.	Not Keystatic-editable — Keystatic forbids imports and errors on this format. Currently used only by Editing These Docs itself.

See docs/decisions/0001-markdoc-vs-mdx.md for the full rationale behind standardizing on Markdoc over MDX for component-using content.