The complete MDX ecosystem combining structured data, unstructured content, executable code, and UI components

MDX.org.ai

MDX.org.ai extends MDX to combine four integrated layers in a single document format:

Structured Data - YAML-LD frontmatter with JSON-LD semantics
Unstructured Content - Markdown prose with rich formatting
Executable Code - TypeScript/JSX for logic and interactions
UI Components - React components for rendering

The Four Layers

Every MDX document naturally contains these four distinct layers:

┌─────────────────────────────────────────────────────────────┐
│  ---                        ← STRUCTURED DATA (YAML-LD)     │
│  $type: BlogPost                                            │
│  $id: /posts/hello-world                                    │
│  author: /authors/jane                                      │
│  publishedAt: 2024-01-15                                    │
│  ---                                                        │
├─────────────────────────────────────────────────────────────┤
│  # Hello World              ← UNSTRUCTURED CONTENT (MD)     │
│                                                             │
│  Welcome to my blog. This is **prose** that can be         │
│  parsed, extracted, and rendered in multiple formats.       │
├─────────────────────────────────────────────────────────────┤
│  export const views = 1234  ← EXECUTABLE CODE (TS/JSX)      │
│                                                             │
│  {posts.filter(p =>                                         │
│    p.author === data.author                                 │
│  ).map(p => <Card {...p} />)}                              │
├─────────────────────────────────────────────────────────────┤
│  <Hero title={data.title} />  ← UI COMPONENTS (React)       │
│  <RelatedPosts author={data.author} />                      │
└─────────────────────────────────────────────────────────────┘

Why MDX.org.ai?

Traditional content systems force you to choose between:

CMS databases - structured but not code-friendly
Markdown files - portable but no schema validation
React apps - powerful but content is buried in code

MDX.org.ai unifies all four concerns in a single, portable file format that works with any database, any framework, and any rendering target.

Quick Start

npm install mdxld

Parse an MDXLD document:

import { parse } from 'mdxld'
 
const doc = parse(`---
$type: Article
$id: /articles/hello-world
title: Hello World
author: /authors/jane
---
 
# Hello World
 
This is an **MDXLD** document with linked data.
`)
 
console.log(doc.data.$type)  // 'Article'
console.log(doc.data.title)  // 'Hello World'
console.log(doc.content)     // '# Hello World\n\nThis is an **MDXLD**...'

The Four Layers in Detail

Structured Data

YAML-LD frontmatter provides typed, validated, linked data:

Package	Description
mdxld	Core parser for YAML-LD frontmatter
mdxdb	Database storage for MDX documents
@mdxld/jsonld	JSON-LD conversion and vocabularies
@mdxld/validate	Schema validation with ArkType

See the Structured Data overview.

Unstructured Content

Markdown content body with parsing and bi-directional extraction:

Package	Description
@mdxld/extract	Extract structured data from rendered markdown
@mdxld/ast	AST manipulation and traversal

See the Unstructured Content overview.

Executable Code

TypeScript functions, AI agents, and multi-runtime execution:

Package	Description
mdxe	MDX execution runtime
mdxai	AI agents with MCP server integration
@mdxe/workers	Cloudflare Workers runtime
@mdxe/hono	Hono web framework middleware

See the Executable Code overview.

UI Components

Component specifications and multi-format rendering:

Package	Description
mdxui	Component specifications (31 components)
@mdxui/html	Render to HTML strings
@mdxui/json	Render to JSON-LD
@mdxui/shadcn	Render with shadcn/ui
@mdxui/fumadocs	Documentation site rendering

See the UI Components overview.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        mdxai                                │
│              AI Agents & MCP Server Integration             │
├─────────────────────────────────────────────────────────────┤
│                         mdxe                                │
│        Execution: Next.js, Hono, Workers, Node, Bun        │
├─────────────────────────────────────────────────────────────┤
│                        mdxdb                                │
│     Storage: Filesystem, SQLite, Postgres, MongoDB, etc.   │
├─────────────────────────────────────────────────────────────┤
│                        mdxld                                │
│           Core: Parse, Validate, Compile, Extract           │
├─────────────────────────────────────────────────────────────┤
│                        mdxui                                │
│       Rendering: HTML, Markdown, JSON, Shadcn, Email        │
└─────────────────────────────────────────────────────────────┘

Key Features

Linked Data with YAML-LD

MDXLD extends frontmatter with JSON-LD compatible properties:

---
$type: BlogPost           # JSON-LD @type
$id: /posts/hello         # JSON-LD @id
$context: https://schema.org  # JSON-LD @context
author: /authors/jane     # Linked reference
tags:
  - typescript
  - mdx
---

Type-Safe Validation

Validate documents with ArkType schemas:

import { parse } from 'mdxld'
import { type } from 'arktype'
 
const Article = type({
  '$type': '"Article"',
  'title': 'string',
  'author': 'string',
  'publishedAt?': 'Date',
})
 
const doc = parse(content)
const result = Article(doc.data)

Multiple Storage Backends

Store MDX documents anywhere:

import { createDatabase } from '@mdxdb/fs'
// or @mdxdb/sqlite, @mdxdb/do, @mdxdb/clickhouse
 
const db = createDatabase({ path: './content' })
await db.set('posts/hello-world', doc)
const post = await db.get('posts/hello-world')

Cloudflare-Native Execution

Run MDX on Cloudflare Workers, and locally under Miniflare:

// Cloudflare Workers
import { createMDXHandler } from '@mdxe/workers'
 
// Local development (same workerd code, under Miniflare)
import { createLocalEvaluator } from '@mdxe/workers/local'
 
// Hono
import { mdx } from '@mdxe/hono'

Multi-Format Rendering

Render components to any output:

import { Hero } from 'mdxui'
import { toHTML } from '@mdxui/html'
import { toJSON } from '@mdxui/json'
import { toMarkdown } from '@mdxui/markdown'
 
const hero = <Hero title="Welcome" subtitle="Get started" />
 
await toHTML(hero)      // HTML string
await toJSON(hero)      // JSON-LD object
await toMarkdown(hero)  // Markdown string

License

MIT

MDX.org.ai Documentation