mdx authoring

rule

MDX is the authored-document format. convert an ordinary .md to .mdx in the next safe documentation change.
keep .md only where its consumer requires Markdown: AGENTS.md, CLAUDE.md, repository README.md, generator-owned output, or a tool contract naming the exact Markdown path or parser.
an exception is not permanent. when the consumer no longer needs .md, rename to .mdx, add frontmatter, update all references, remove the old path — one forward-only change.
.md without frontmatter is invisible to discovery, indexing, and lifecycle tracking: no kind, status, title, visibility means no classification, no content-type lookup, no staleness check. .md is for consumers that require it, not for lack of metadata.

why

a corpus an index cannot parse is a pile of files, not a knowledge system. MDX carries queryable frontmatter and a component vocabulary in one artifact, so one source serves the human reader and the machine boundary — no second copy of the truth. the risk avoided: pages that cannot be classified, discovered, or tracked for staleness, and structure reverse-engineered from prose on every consumption.

use fumadocs components by meaning

Fumadocs components clarify information structure; they are not decoration. use the components already registered for the documentation renderer.

component	use it for	do not use it for
`<Callout>`	a hard rule, warning, decision boundary, or non-obvious consequence.	restating ordinary prose.
`<Cards>` and `<Card>`	a domain landing page or a small set of mutually navigable next reads.	a long unordered list of every page.
`<Accordions>` and `<Accordion>`	detailed implementation evidence below a visible high-level decision.	the only place a reader can discover the purpose or outcome.
fenced code block	a complete copyable example, schema, command, or file fragment.	decorative one-line identifiers.
`CodeBlockTabs`	equivalent implementations a reader chooses between, such as package manager or runtime.	sequential steps or unrelated examples.

use normal headings, prose, lists, and tables for linear explanation, ordered workflows, and exact comparisons.
register a new Fumadocs component at the renderer boundary before using it in content; do not import React components ad hoc in individual documents.

ruling

do not hide a requirement in a component

a callout highlights a rule. the owning standard still states the rule in searchable prose and links to its related contracts.

conversion workflow

confirm the .md file is not an instruction, repository-entry, tool, or generator-required .md.
create the .mdx replacement with required frontmatter.
preserve canonical prose; add components only where they improve the information shape.
update every path reference and delete the old .md file.
parse or build the owning docs source and validate its links.

good and bad

bad

retries use the same operation ID.

no queryable identity or lifecycle state; no index can classify it, no lifecycle check can flag it stale — only a full-text scan ever finds it.

good

---
title: retry behavior
visibility: private
status: draft
kind: standard
---

the document body opens with its single `#` heading, then states the rule.

<Callout type="info" title="one operation, one identity">
  retries continue a recorded operation; they do not decide a new one.
</Callout>

parseable, classified, structured for human scan and machine retrieval. every new page enters the corpus already visible to indexing, lifecycle tracking, and retrieval — the query surface and the reading surface stay the same artifact.