Structured Linked Data, Unstructured Content, Executable Code, and UI Components all in a single file

MDXLD

MDXLD solves a fundamental problem in modern software development: how do you represent business logic, documentation, data, and user interface in a unified, human-readable, semantically-linked format?

Traditional approaches force you to separate these concerns:

Configuration in JSON/YAML files
Documentation in Markdown files
Code in TypeScript/JavaScript files
Data in databases or CSV files
UI in component libraries

MDX brings them together in a single format that combines four essential capabilities:

Structured Linked Data

Use YAML frontmatter to define schemas, metadata, and semantic types:

---
$type: BlogPost
$id: https://blog.example.com/posts/hello-world
title: Hello World
author: Jane Developer
date: 2025-10-27
tags: [tutorial, mdx, introduction]
status: published
---

# Hello World

This is a blog post with structured frontmatter.

The frontmatter is parsed as structured data, validated against schemas (using Zod or JSON Schema), and can be queried like a database. The $type and $id fields enable semantic web patterns, making your documents part of a global knowledge graph following JSON-LD conventions.

Unstructured Content

Write natural language documentation, explanations, and narrative content in Markdown:

## Why Use MDX?

MDX allows you to **document your code** alongside the code itself.
You can use all standard Markdown features:

- Lists
- **Bold** and _italic_ text
- [Links](https://mdxld.do)
- Code blocks
- Images and media
- Tables
- And more...

This content is human-readable, versionable in git, and can be transformed into HTML, PDF, or any other format. Markdown's simplicity makes it accessible to both developers and non-technical team members.

Executable Code

Embed TypeScript/JavaScript directly in your MDX files:

export const greeting = 'Hello, World!'

export function greet(name: string) {
  return `Hello, ${name}!`
}

export const timestamp = new Date().toISOString()

<div>{greet('MDX')} - Generated at {timestamp}</div>

The code is executed at build time or runtime, allowing you to:

Generate content dynamically
Validate data against schemas
Transform and process information
Create interactive experiences
Compute values from structured data
Implement business logic

UI Components

Use React components to create interactive, styled content:

<Callout type="info">
  This is an informational callout component with custom styling.
</Callout>

<Tabs>
  <Tab title="JavaScript">
    ```js
    console.log("Hello, World!")
    ```
  </Tab>
  <Tab title="TypeScript">
    ```ts
    console.log("Hello, World!" as string)
    ```
  </Tab>
</Tabs>

<Chart data={chartData} type="line" />

<Button onClick={() => alert('Clicked!')}>
  Interactive Button
</Button>

Components can be:

Interactive: Buttons, forms, tabs, accordions, modals
Data-driven: Charts, tables, dashboards, visualizations
Styled: Using Tailwind, CSS-in-JS, or any styling solution
Composable: Build complex UIs from simple, reusable components
Accessible: Following WCAG guidelines and best practices

Packages

The .do platform provides five core packages for working with mdxld:

mdxld - MDX + Linked Data

View mdxld docs →

Parse, validate, and transform MDX documents with semantic types ($type, $id, $context). Converts between MDX and JSON-LD, validates against Zod schemas, and integrates with 70+ .org.ai ontologies.

import { parseMDXLD } from 'mdxld'
const { frontmatter, content } = parseMDXLD(mdx)

mdxe - Zero-Config CLI

View mdxe docs →

Develop, test, build, and deploy MDX apps with zero configuration. Pure MDX development with hot reload, built-in testing, and one-command deployment to Cloudflare Workers.

mdxe dev      # Start dev server
mdxe test     # Run tests
mdxe deploy   # Deploy to .do platform

mdxai - AI Agent

View mdxai docs →

AI agent for creating, editing, enriching, and organizing MDX files (local and remote). Conversational interface for content management, SEO optimization, and maintenance.

mdxai agent ./content --remote platform.do

mdxdb - Local Database

View mdxdb docs →

Expose .mdx files as a queryable database with sync to .do platform backend. Query local content like SQL/MongoDB, with push/pull sync to remote collections.

const db = await mdxdb.init({ source: './content' })
const posts = await db.posts.list({ where: { published: true } })

mdxui - Type-Aware Components

View mdxui docs →

React components that render based on $type. Same MDX content renders as LandingPage, Documentation, BlogPost, Product, API, App, or Site depending on semantic type.

---
$type: LandingPage
---
{/* Automatically renders with Hero, Features, Pricing */}

---
$type: Worker
$id: https://workers.do/api
name: api-worker
main: src/index.ts
compatibility_date: 2025-10-27
---

# API Worker

A Cloudflare Worker with embedded configuration and documentation.

Knowledge Bases

Create interconnected knowledge bases using wikilinks and semantic types:

---
$type: Documentation
$id: https://docs.example.com/business-as-code
---

# Business-as-Code

[[Business-as-Code]] enables autonomous business operations using:

- [[Services-as-Software]]
- [[MDXLD]]
- [[$.Subject.predicate.Object]] patterns

See [[Getting Started]] to begin.

Product Catalogs

Store product data with schema validation and rich content:

---
$type: schema.org.ai/Product
$id: https://products.example.com/widget-x
sku: WIDGET-X-001
name: Widget X
price: 99.99
inStock: true
brand:
  $type: schema.org.ai/Brand
  name: Acme Corp
---

# Widget X

Premium widget with advanced features. Perfect for businesses that need reliability and performance.

<Features items={features} />
<Pricing plans={pricingPlans} />
<Testimonials reviews={reviews} />

MDX.do