pnpm add @mdxld/markdown

import { toMarkdown, fromMarkdown } from '@mdxld/markdown'
import { diff, applyExtract } from '@mdxld/extract' // path diff / apply, implemented once in @mdxld/diff
 
// Object to Markdown
const customer = {
  name: 'Customer',
  description: 'A customer entity',
  properties: [
    { name: 'id', type: 'string', required: true, description: 'Unique identifier' },
    { name: 'email', type: 'string', required: true, description: 'Email address' },
  ]
}
 
const markdown = toMarkdown(customer)

# Customer
 
A customer entity
 
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| id | string | ✓ | Unique identifier |
| email | string | ✓ | Email address |

function toMarkdown<T extends object>(
  object: T,
  options?: ToMarkdownOptions
): string
 
interface ToMarkdownOptions {
  /** Starting heading depth (default: 1) */
  headingDepth?: number
  /** Include table of contents */
  toc?: boolean
  /** Use frontmatter for metadata */
  frontmatter?: boolean
  /** Table style: 'github' | 'simple' */
  tableStyle?: 'github' | 'simple'
  /** List style: 'dash' | 'asterisk' | 'plus' */
  listStyle?: 'dash' | 'asterisk' | 'plus'
}

const markdown = toMarkdown(entity, {
  headingDepth: 2,      // Start at ## instead of #
  tableStyle: 'github', // GFM tables
  listStyle: 'dash',    // Use - for lists
})

function fromMarkdown<T = Record<string, unknown>>(
  markdown: string,
  options?: FromMarkdownOptions
): T
 
interface FromMarkdownOptions {
  /** Expected type for validation */
  type?: string
  /** Strict mode - throw on parse errors */
  strict?: boolean
}

const markdown = `# Customer
 
A customer entity
 
| Property | Type | Required |
|----------|------|----------|
| id | string | ✓ |
| email | string | ✓ |
`
 
const customer = fromMarkdown<Customer>(markdown)
// {
//   name: 'Customer',
//   description: 'A customer entity',
//   properties: [
//     { name: 'id', type: 'string', required: true },
//     { name: 'email', type: 'string', required: true },
//   ]
// }

renderTable(['name', 'slug'], [{ name: 'JavaScript', slug: 'javascript' }])
// '| name | slug |\n|---|---|\n| JavaScript | javascript |'
 
parseTable('| name | slug |\n|---|---|\n| JavaScript | javascript |')
// { headers: ['name', 'slug'], rows: [{ name: 'JavaScript', slug: 'javascript' }] }

import { fromMarkdown } from '@mdxld/markdown'
import { diff, applyExtract } from '@mdxld/extract'
 
const changes = diff(original, fromMarkdown(edited))
// { added: {...}, modified: { 'age': { from: 30, to: 31 } }, removed: [], hasChanges: true }
 
const updated = applyExtract(original, fromMarkdown(edited), { arrayMerge: 'append' })

const entity = {
  name: 'User',
  description: 'A user account',
  properties: [
    { name: 'id', type: 'string', required: true },
    { name: 'email', type: 'string', required: true },
    { name: 'role', type: 'string', enum: ['admin', 'user'] },
  ]
}
 
toMarkdown(entity)

# User
 
A user account
 
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| id | string | ✓ |  |
| email | string | ✓ |  |
| role | string |  |  |

const doc = {
  name: 'Getting Started',
  sections: [
    { name: 'Installation', content: 'Run `npm install`' },
    { name: 'Usage', content: 'Import and use' },
  ]
}
 
toMarkdown(doc)

# Getting Started
 
## Installation
 
Run `npm install`
 
## Usage
 
Import and use

const list = {
  name: 'Features',
  items: ['Fast', 'Reliable', 'Scalable']
}
 
toMarkdown(list)

# Features
 
- Fast
- Reliable
- Scalable

import { toMarkdown } from '@mdxld/markdown'
 
const apiEndpoint = {
  name: 'Create User',
  description: 'Creates a new user account',
  properties: [
    { name: 'email', type: 'string', required: true, description: 'User email' },
    { name: 'password', type: 'string', required: true, description: 'User password' },
  ]
}
 
const docs = toMarkdown(apiEndpoint)
await Bun.write('docs/create-user.md', docs)

import { toMarkdown, fromMarkdown } from '@mdxld/markdown'
import { diff, applyExtract } from '@mdxld/extract'
 
// Load structured content
const post = await db.BlogPost.get('hello-world')
 
// Render for editing
const markdown = toMarkdown(post)
 
// User edits in WYSIWYG editor...
const edited = await editor.edit(markdown)
 
// Extract changes
const extracted = fromMarkdown(edited)
const changes = diff(post, extracted)
 
if (changes.hasChanges) {
  // Review changes before saving
  console.log('Modified:', Object.keys(changes.modified))
 
  // Apply and save
  const updated = applyExtract(post, extracted)
  await db.BlogPost.update('hello-world', updated)
}

import { toMarkdown, fromMarkdown } from '@mdxld/markdown'
 
// Render to markdown for AI
const markdown = toMarkdown(content)
 
// AI improves the content
const improved = await ai.improve(markdown, 'Make it more engaging')
 
// Extract changes back
const updated = fromMarkdown(improved)