MDXLD

MDXLD is an extension of MDX. It adds one thing: a small set of $-prefixed linked-data keys in the YAML frontmatter — $id, $type, $context — so that a document says what it is, and not only how it renders.

What is ours, and what is not

MDX is an open standard authored by the MDX community, not by us. That Markdown, JSX and ESM compose in a single file is the MDX project’s achievement; everything on this site is written in it. We are downstream users of that work, and we conform to it.

MDXLD is ours. It is a superset of MDX — every valid MDX document is a valid MDXLD document — and, in the frontmatter, a superset of YAML-LD. The relationship reads the same way twice over:


  Markdown  ──▶  MDX             ──▶  MDXLD
  (theirs)       (theirs, open)       (ours, superset)

  JSON-LD   ──▶  YAML-LD         ──▶  MDXLD frontmatter
  (theirs)       (theirs, open)       (ours, superset)

It is the same pattern as schema.org → schema.org.ai : conform on the shared core, extend deliberately above it, and say plainly which half is which.

MDXUI is ours too. It is one of the eleven primitives — the component layer that renders an MDXLD document — and it is a separate piece of work from the format described on this page. It has no published site yet, so there is nothing here to link to.

The frontmatter

Markdown YAML JSON-LD Javascript / Typescript JSX / React


---
$context: https://schema.org.ai
$id: https://example.com
$type: WebSite
title: Example Domain
description: This domain is for use in illustrative examples in documents
---
 
# Example Domain
 
This domain is for use in illustrative examples in documents. You may use this
domain in literature without prior coordination or asking for permission.
 
[More information...](https://www.iana.org/domains/example)

Three keys carry the linked data. Everything else in that block is ordinary YAML frontmatter and keeps whatever meaning your toolchain already gave it — which is the point of being a superset rather than a replacement.

`$context`

The vocabulary binding IRI. Here it is always https://schema.org.ai — unversioned, and permanently so. A versioned context URL is a defect: the binding IRI is an identity, and identities do not carry version numbers. schema.org.ai is our superset of schema.org , so a $type that schema.org already defines keeps schema.org’s meaning.

`$type`

What the document is. Resolved against $context, so $type: WebSite and $type: https://schema.org.ai/WebSite name the same class.

`$id`

The document’s identity as a URI — what other documents point at when they refer to this one.

Why the dollar sign

$id and $type are not a deviation. JSON-LD 1.1 permits keyword aliasing through the context, and the JSON-LD community publishes exactly this alias set at dollar-convenience.jsonld. MDXLD’s $id and $type are that convention, not an invention of ours.

$context is the deviation, and it is a real one: @context is the single JSON-LD keyword that cannot be aliased , and an alias could not be used inside a context in any case. (Note that dollar-convenience.jsonld contains no $context entry, for exactly this reason.) MDXLD spells it $context regardless, for one mechanical reason — an MDX document compiles to ESM, @context is not a legal JavaScript identifier, and a document forced to quote '@context' has lost the very property that makes the $ set worth having. In YAML, too, a bare @ is a reserved indicator character and must be quoted.

The compatibility shim is one rename: a conforming JSON-LD processor reads MDXLD frontmatter by renaming $context to @context. User-defined keys never begin with $.

Status

MDXLD is pre-1.0 and deliberately unfixed. Nothing here freezes until at least two real external implementations prove the shape. If you are building on it, say so — that is the signal that decides what gets fixed and when.

Where this is documented

MDXLD’s home is mdx.org.ai. This site is a serving surface for that home.