MDXLD

MDXLD = MDX + Linked Data

A single document format that combines:

Layer	Format	Purpose
Structured Data	YAML	Machine-readable linked data
Unstructured Content	Markdown	Human-readable prose
Executable Code	JS/TS	Logic and data transformations
UI Components	JSX	Visual rendering

Document Structure

---
$context: https://schema.org.ai
$type: Startup
$id: https://startups.studio
name: Startups.Studio
tagline: AI-operated venture studio
stage: Growth
---

# {name}

{tagline}

We build **autonomous businesses** powered by AI agents.

export const metrics = await fetchMetrics()

<Hero title={name} subtitle={tagline} />

<Stats metrics={metrics} />

<StoryBrand />

<Team display="cards" />

The $ Properties (YAMLLD)

MDXLD uses YAMLLD - a variant of JSON-LD that uses $ instead of @:

Property	Purpose	Example
`$context`	Schema namespace	`https://schema.org.ai`
`$type`	Thing type	`Startup`, `Person`, `Agent`
`$id`	Unique identifier (URL)	`https://startups.studio`

Why $ instead of @?

Valid in YAML (no quoting needed)
Valid in JavaScript/TypeScript
Works as variable names in MDX expressions

---
$type: Startup
$id: https://startups.studio
---

<!-- These work because $ is valid in JS -->
<Card type={$type} />
The ID is {$id}

$context - The Triple Entendre

$context serves three purposes simultaneously:

1. JSON-LD Context (Schema Definition)

$context: https://schema.org.ai

Defines the vocabulary for interpreting the data. Properties like name, description, image are understood according to this schema.

2. AI/LLM Context (Understanding)

When rendered to markdown for an agent, $context tells the LLM how to interpret this document:

Context: https://schema.org.ai
Type: Startup
ID: https://startups.studio

This document describes a Startup entity...

3. Namespace (Domain)

$context can be any URL, creating domain-specific vocabularies:

$context: https://startups.studio
$type: Portfolio

$context: https://yourapp.com
$type: CustomThing

Automatic Context Injection

Components automatically receive the document's frontmatter context:

---
$type: Startup
$id: https://startups.studio
name: Startups.Studio
---

<!-- These are equivalent -->
<StoryBrand />
<StoryBrand of={$id} />

<!-- Reference a different thing -->
<StoryBrand of="https://other-startup.com" />

The of={$id} syntax is available for:

Clarity and explicitness
Referencing different Things
Dynamic references

Multi-Target Rendering

The same MDXLD document renders to multiple targets:

import { renderHTML, renderMarkdown, renderSlides } from 'mdxui'

const doc = await load('startup.mdx')

renderHTML(doc)      // Web page
renderMarkdown(doc)  // Agent context
renderSlides(doc)    // Pitch deck
renderImage(doc)     // OG image
renderVideo(doc)     // Explainer video
renderJSON(doc)      // API response
renderMCP(doc)       // AI tools
renderInk(doc)       // CLI interface

Target Outputs

Renderer	Output	Use Case
`renderHTML`	React/DOM	Web sites and apps
`renderMarkdown`	Markdown	Agent/LLM context
`renderSlides`	Slidev	Presentations
`renderImage`	Satori PNG/SVG	OG images, social cards
`renderVideo`	Remotion MP4	Explainer videos
`renderJSON`	JSON	API responses
`renderMCP`	MCP Tools	AI agent tools
`renderInk`	Ink/Terminal	CLI interfaces

Component Context

Components render differently based on context:

---
$type: StoryBrand
$id: https://startups.studio/brand
hero: Build Autonomous Businesses
problem: Manual operations don't scale
solution: AI agents run your business
---

<StoryBrand />

Context	Output
`renderHTML`	Hero section + problem/solution sections
`renderMarkdown`	Structured brand document for agents
`renderSlides`	Multi-slide pitch narrative
`renderImage`	Brand card with hero + tagline

The component declares what (semantic structure). The renderer determines how (output format).

Inheritance and Composition

MDXLD documents can reference and compose other documents:

---
$type: Site
$id: https://startups.studio
startup: https://startups.studio/startup
---

<Startup of={startup} level="page" />

<!-- Or embed sections from the startup -->
<StoryBrand of={startup} />
<Team of={startup} />
<LeanCanvas of={startup} />

Schema.org.ai Types

MDXLD uses schema.org.ai, which extends schema.org with AI-native types:

Core schema.org Types

Thing, Person, Organization, Product, Service
Event, Place, CreativeWork, Article

AI Extensions

Agent - AI agent with capabilities
Tool - Tool an agent can use
Model - AI/ML model
Prompt - Prompt template
Workflow - Multi-step process

Business Extensions

Business, Startup
LeanCanvas, StoryBrand
API, SDK, MCP

See schema.org.ai for the complete vocabulary.

MDXLD

On this page