Reference

MDX Content Conventions

Frontmatter schemas, draft workflow, and where long code samples belong in content-driven sites.

  • mdx
  • content
Raw markdown Manifest JSON ← Agent Kit

Suggested Cursor path: .cursor/rules/mdx-content.mdc

MDX Content Conventions

For Astro sites using content collections.

Frontmatter

Schemas live in content.config.ts. Required fields must validate at build time — fix schema errors before deploy.

Content vs. code

  • Long code samples belong in collection MDX bodies, not in page templates
  • Cross-link related entries with stable paths (/projects/slug, /notes/slug)
  • Fix obvious typos in published code samples before merge

Adding entries

  1. Create file in the correct collection folder
  2. Set draft: true until ready
  3. Run production build to validate
  4. Flip draft: false and deploy

Do not

  • Store raw datasets or generated logs in content folders
  • Duplicate site-wide marketing copy that belongs in a central data module