Fix: MDX Integration Missing in Astro

Astro shows “MDX integration missing” when it needs to render an .mdx file but the @astrojs/mdx integration isn’t installed. The message says Astro was “Unable to render” the file and to “Ensure that the @astrojs/mdx integration is installed.” Run npx astro add mdx, restart the dev server, and MDX pages and collection entries render.

Key Takeaways

• .md works out of the box; .mdx needs @astrojs/mdx.
• npx astro add mdx installs it and adds it to integrations.
• Content collections also need mdx in the glob() pattern to load .mdx files.
• Restart astro dev after installing.

Fix

npx astro add mdx

Result:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
});

Restart the dev server. Integrations aren’t picked up by hot reload.

Load .mdx in content collections

If your collection pattern only lists md, .mdx files are ignored (no error, just missing entries). Include both:

const blog = defineCollection({
  loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: './src/content/blog' }),
  schema: z.object({ title: z.string() }),
});

MDX-specific gotchas after installing

Curly braces and angle brackets in prose

MDX treats { as the start of a JavaScript expression and < as the start of a component. Prose that mentions {slug} or a <div> without backticks breaks the page. Put code in backticks:

Use `{slug}` in the route and wrap it in a `<div>`.

Imports go after frontmatter

---
title: "Using components in MDX"
---

import Callout from '../../components/Callout.astro';

<Callout type="tip">MDX can render components.</Callout>

HTML comments

MDX doesn’t support <!-- comments -->. Use {/* comment */}.

Do you need MDX?

If your content is plain prose with code blocks, .md is simpler and has no parsing surprises. Reach for MDX when you want components inside content (callouts, tabs, embedded demos). You can also map Markdown elements to components without converting files, by passing components to <Content />.

The Astro content collections guide covers rendering MDX entries, and the content docs for Komal themes show MDX in a theme. If MDX content renders a framework component, you may also hit No matching renderer found. The MDX integration docs list every option.

FAQ

Do .md and .mdx files share Markdown config?

By default, yes: MDX inherits markdown options like remark and rehype plugins. Set extendMarkdownConfig: false in mdx() to separate them.

Can I mix .md and .mdx in one collection?

Yes, as long as the glob() pattern includes both extensions.