MDX Content Management

Content Schema Design

Frontmatter Schema Pattern

Required fields for all content:

---
title: string        # Page title
description: string  # Short description (for nav, search)
---

Common optional fields:

date: date          # Publication/update date
tags: string[]      # Categorization
draft: boolean      # Hide from production
order: number       # Manual ordering
category: string    # Primary category

Type-Safe Schema Definition

import { z } from 'zod';

const schema = z.object({
  title: z.string(),
  description: z.string(),
  date: z.date().optional(),
  tags: z.array(z.string()).optional(),
  draft: z.boolean().default(false),
});

Critical: Validate at build time, not runtime. Catch schema errors early.

MDX Plugin Configuration

Essential Plugins

Markdown processing (remark):

• remark-gfm: GitHub Flavored Markdown (tables, task lists)
• remark-frontmatter: Parse YAML frontmatter

HTML processing (rehype):

• rehype-slug: Add IDs to headings (required for TOC)
• rehype-autolink-headings: Clickable heading links
• rehype-pretty-code: Syntax highlighting (Shiki-based)

Minimal Config Example

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: [
      rehypeSlug,
      [rehypeAutolinkHeadings, { behavior: 'wrap' }],
      [rehypePrettyCode, { theme: 'github-dark' }],
    ],
  },
});

Content Organization Patterns

Directory Structure

content/
  docs/              # Main documentation
    index.md
    getting-started.md
    api/             # Nested sections
      auth.md
  guides/            # Tutorials/guides
  changelog.md       # Special pages

Routing: Directory structure maps to URLs

• docs/index.md → /docs
• docs/api/auth.md → /docs/api/auth

Collection Organization

Group related content into collections:

export const collections = {
  'docs': docsCollection,
  'guides': guidesCollection,
  'blog': blogCollection,
};

Benefits: Separate schemas, different processing, type safety per collection.

Custom Components in MDX

Providing Components

// Make components available in MDX
const components = {
  // Override defaults
  h1: CustomH1,
  code: CustomCode,

  // Add custom components
  Callout: CalloutComponent,
  Tabs: TabsComponent,
};

Common Patterns

Callout/Alert:

<Callout type="warning">
Important information here
</Callout>

Code with tabs:

<Tabs>
  <Tab label="JavaScript">...</Tab>
  <Tab label="TypeScript">...</Tab>
</Tabs>

Syntax Highlighting

Shiki Configuration

[rehypePrettyCode, {
  theme: 'github-dark',
  keepBackground: false,  // Use CSS custom properties
}]

Theme switching: Set keepBackground: false, control via CSS:

pre {
  background: var(--code-background);
}

Code Block Features

```js title="example.js" {3-5}
// Line 1
// Line 2
// Lines 3-5 highlighted
// ...

Supported: Line highlighting, titles, line numbers (framework-dependent).

## Content Queries

### Basic Filtering

import { getCollection } from 'astro:content';

// Get published docs const docs = await getCollection('docs', ({ data }) => { return !data.draft; });

// Sort by date docs.sort((a, b) => b.data.date.getTime() - a.data.date.getTime() );

### Navigation Generation

// Generate nav from content const nav = docs .filter(doc => !doc.data.draft) .map(doc => ({ label: doc.data.title, href: /docs/${doc.slug}, order: doc.data.order ?? 999, })) .sort((a, b) => a.order - b.order);

## Table of Contents Generation

### Extract Headings

// From markdown AST or rendered HTML function extractHeadings(content: string) { const headings = []; // Parse headings from content return headings.map(h => ({ depth: h.depth, text: h.text, slug: h.slug, })); }

**Display**: Show h2 and h3 only, indent by depth.

## Validation Checklist

Before committing content schema:
- [ ] Required fields defined
- [ ] TypeScript types generated
- [ ] Validation runs at build time
- [ ] Example content validates
- [ ] Frontmatter documented for authors
- [ ] Collections organized logically

## Common Issues

**Frontmatter not parsing:**
- Ensure triple dashes `---` around YAML
- Check indentation (YAML is whitespace-sensitive)
- Validate against schema

**Custom components not rendering:**
- Verify component is provided to MDX
- Check import paths
- Ensure component is exported

**Syntax highlighting broken:**
- Verify plugin is configured
- Check language identifier is valid
- Ensure theme is loaded

## Content Authoring Guidelines

Document for content authors:

Content Guidelines

1. Frontmatter: Required fields: title, description
2. Headings: Start with h2 (h1 is title)
3. Links: Use relative paths: ./other-doc.md
4. Images: Place in src/assets/, use relative paths
5. Code blocks: Include language identifier

## Decision Points

**Schema design:**
- What content types exist?
- What metadata does each need?
- How will content be filtered/sorted?

**MDX features:**
- Which custom components are needed?
- What markdown extensions are required?
- How will code blocks be styled?

**Organization:**
- How to structure directories?
- How to handle navigation?
- How to generate TOC?

Document decisions in CLAUDE.md under "Content Structure" section.