Unstructured Content

The Unstructured Content layer handles the Markdown body of MDX documents - the human-readable prose that sits between the frontmatter and components.

Markdown Processing

MDX extends standard Markdown with JSX support, allowing rich content that combines prose with interactive components.

# Welcome
 
This is **markdown** content with an embedded component:
 
<Chart data={salesData} />
 
And more prose continues here...

Templates (Layouts)

Templates define how structured data renders to markdown and extracts back to objects.

Convention-Based Layouts

Objects automatically render to markdown following conventions:

import { toMarkdown, fromMarkdown } from '@mdxld/markdown'
 
// Object → Markdown (auto layout)
const markdown = toMarkdown({
  name: 'Customer',
  plural: 'Customers',
  description: 'A person who purchases products.',
  properties: [
    { name: 'id', type: 'string', required: true },
    { name: 'email', type: 'string', required: true },
  ]
})

Output:

# Customer (Customers)
 
A person who purchases products.
 
## Properties
 
| Property | Type | Required |
|----------|------|----------|
| id | string | ✓ |
| email | string | ✓ |

Layout Conventions

Shape Pattern	Markdown Output
`name` (top-level)	`# {name}`
`description`	Paragraph after title
Nested object	`## {Key}` section
`string[]`	Bullet list
`object[]` (flat)	Table
`object[]` (complex)	`### {name}` subsections

Custom Layouts

For full control, use explicit templates:

const template = `
# {name}
 
> {tagline}
 
## The Hero
 
{hero.persona}
 
**Works as:** {hero.occupation}
`
 
// Render with template
const markdown = render(template, storyBrand)
 
// Extract from edited markdown
const data = extract(editedMarkdown, template)

Bi-directional Extraction

The @mdxld/markdown package enables round-trip editing:

import { toMarkdown, fromMarkdown } from '@mdxld/markdown'
 
// 1. Render to markdown
const markdown = toMarkdown(storyBrand)
 
// 2. User or AI edits the markdown
const edited = markdown.replace('VP of Engineering', 'CTO')
 
// 3. Extract changes back to object
const updated = fromMarkdown<StoryBrand>(edited)
 
// 4. Diff to see what changed (one diff implementation: @mdxld/diff, re-exported by @mdxld/extract)
import { diff } from '@mdxld/extract'
const changes = diff(storyBrand, updated)
// { modified: { 'hero.occupation': { from: 'VP of Engineering', to: 'CTO' } } }

Use Cases

Headless CMS - Edit rendered content, sync back to frontmatter
AI Editing - Let AI improve content, extract the changes
Round-trip Sync - Keep source MDX and rendered output in sync
Content Migration - Transform between formats while preserving structure
Documentation - Generate docs from schemas, accept edits back

See Structured Data for schema definitions and UI Components for JSX rendering.