MDX Superpowers for AI Builders

MDX combines Markdown ergonomics with component-driven content. This guide documents the features I reach for when translating complex AI workstreams into reusable knowledge.

1. Frontmatter drives metadata

Every MDX file starts with frontmatter. Astro parses it through the collection schema, making fields available for list views, SEO, or custom layouts.

---
title: "AI Runbook"
description: "How the incident bot escalates production issues"
publishDate: 2025-04-15
tags: ["runbook", "ops"]
---

Use frontmatter to:

• Populate cards and navigation summaries (cardSummary).
• Drive sort order with a numeric order field.
• Flag drafts you are not ready to publish (draft: true).

2. Author reusable shortcodes

MDX lets me define small components inline and reuse them throughout the document.

export const Callout = ({ tone = "note", children }) => (
  <div className={`callout callout--${tone}`}>
    <strong>{tone === "tip" ? "Implementation Tip" : "Note"}</strong>
    {children}
  </div>
);

You can also import components from the design system. For example, I often drop in Tabs, accordions, or metric tiles that already exist in Astro.

3. Mix Markdown with JSX

MDX honours Markdown syntax while allowing JSX where it is clearer.

- Pure Markdown for quick bullet lists
- **Bold** and _emphasis_ still work
- Drop into JSX when you need structure:
  <ul>
    <li>Render dynamic data</li>
    <li>Wrap custom classes without raw HTML escapes</li>
  </ul>

That balance keeps content approachable for collaborators who prefer Markdown while giving me full control when the layout demands more.

4. Compose dynamic content

Because MDX runs through the same build pipeline as Astro, I can execute JavaScript at build time.

const agentStages = ["Surface", "Intelligence", "Context", "Connectors"];

<ul>
  {agentStages.map((stage) => (
    <li key={stage}>{stage}</li>
  ))}
</ul>

This is perfect for referencing central config—no more copy/pasting the same lists across articles.

5. Slot in complex layouts

Need side-by-side comparisons or multi-column narratives? Compose them directly.

Because MDX runs JSX, you can hydrate richer experiences if needed—just swap TwoUp for a fully interactive component.

6. Highlight code and data

MDX respects fenced code blocks, table syntax, definition lists, and footnotes. I lean on them for:

\`\`\`json
{
  "connector": "gmail",
  "scopes": ["compose", "read"],
  "lastAudit": "2025-01-11"
}
\`\`\`

Pro tip: Combine code blocks with shortcodes so every snippet inherits consistent captions, copy buttons, or download links.

7. Enrich with interactive islands (optional)

If a tutorial benefits from live interaction, import an Astro component or framework component and hydrate it when needed.

import ScenarioPlanner from "../../components/ScenarioPlanner.astro";

<ScenarioPlanner client:visible />

Hydration requires the relevant renderer (React, Vue, Svelte, or Solid). Keep interactive widgets scoped so the majority of the article remains static for performance.

8. Share utilities between documents

MDX files can export helpers used by other files.

export const auditChecklist = [
  "Regenerate service accounts",
  "Rotate API keys",
  "Archive transcripts"
];

Other MDX documents or Astro pages can import auditChecklist to stay in sync. Think of it as content-driven constants.

9. Author structured callouts and metrics

Because we are in JSX, even metrics grids can live inside the document.

<div className="metrics">
  <div className="metrics__item">
    <span className="metrics__value">24h</span>
    <span className="metrics__label">Average response SLA</span>
  </div>
  <div className="metrics__item">
    <span className="metrics__value">4</span>
    <span className="metrics__label">Connectors managed</span>
  </div>
</div>

No need to fall back to HTML partials or JSON payloads—the content remains source-controlled and reviewable.

10. Keep authoring delightful

• Linting & previews: Astro’s content module validates schema at build time so mistakes surface early.
• Consistent theming: Use shared utility classes instead of inline styles whenever possible.
• Composable publishing: Because MDX is just files, it plays well with GitHub reviews, Docs-as-code workflows, and automation.