---

name: "mdx-content" description: "Content schema design and MDX configuration patterns for knowledge bases. Use when designing content structure, configuring MDX processing, or setting up frontmatter schemas."

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

```typescript
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.