Why MDX

MDXLD is built on MDX , and the first thing to say about MDX is that it is not ours. It is an open standard authored and maintained by the MDX community at mdxjs.com . We chose it; we did not make it.

What MDX gives us

MDX lets a single file hold Markdown prose and JSX components, and compile to ESM. That combination is the whole reason MDXLD is possible:

1. Write content in familiar Markdown syntax
2. Import and use components
3. Pass data between components
4. Compile the result to a JavaScript module

The last point matters more than it looks. Because an MDX document is an ES module, its exports are addressable by ordinary tooling — and that is what lets a linked-data identity ride along with the content instead of sitting in a sidecar file.

Example

---
$context: https://schema.org.ai
$type: TechArticle
title: Using Components in MDX
---
 
# {frontmatter.title}
 
Here's a regular markdown paragraph.
 
<Alert type='info'>This is a component in the middle of Markdown.</Alert>
 
- List items work
- Just like regular markdown
- But you can also use <Highlight>components inline</Highlight>

One thing MDX deliberately leaves open

MDX itself does not define YAML frontmatter — frontmatter is supplied by remark-frontmatter, and MDX assigns it no semantics. It is parsed and handed to the host, which decides what it means.

That open seam is exactly where MDXLD lives. We are not overriding an MDX rule; we are filling in a space MDX left for its hosts on purpose.

MDX + Linked Data = MDXLD

MDXLD is a superset of MDX. Every valid MDX document is already a valid MDXLD document — one that simply declares no linked data. What MDXLD adds is:

• $id, $type and $context in the frontmatter — a superset of YAML-LD
• Typed data structures resolved against $context
• Semantic relationships between documents, via $id
• Component props typed from $type

Note that MDXLD’s relationship to MDX is stricter than MDX’s own relationship to Markdown. MDX does not claim to be a superset of Markdown and is careful to say so — indented code blocks, autolinks and raw HTML all behave differently under MDX. MDXLD makes the stronger promise, because it only ever adds frontmatter keys and never changes how a document parses or renders.

See Linked Data for how the frontmatter half works, and mdx.org.ai  for the full documentation.