tessl/npm-astrojs--mdx
Astro integration that enables MDX support for creating interactive pages and components with Markdown and JSX
—
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Pending
The risk profile of this skill
integration.mddocs/
Main Integration
Core integration functionality for adding MDX support to Astro projects. The integration handles configuration, plugin setup, build system integration, and content collection support.
Capabilities
Default MDX Integration Function
Creates an Astro integration that enables MDX support throughout the project.
/**
* Creates an Astro integration for MDX support
* @param partialMdxOptions - Optional configuration object for customizing MDX behavior
* @returns AstroIntegration object that hooks into Astro's build system
*/
export default function mdx(partialMdxOptions?: Partial<MdxOptions>): AstroIntegration;The returned AstroIntegration object contains:
name: "@astrojs/mdx"hooks: Integration hooks that run during different phases of the build
Usage Examples:
import { defineConfig } from "astro/config";
import mdx from "@astrojs/mdx";
// Basic usage with default settings
export default defineConfig({
integrations: [mdx()],
});
// With custom configuration
export default defineConfig({
integrations: [
mdx({
extendMarkdownConfig: false,
remarkPlugins: [remarkGfm],
rehypePlugins: [rehypeSlug],
optimize: true,
}),
],
});
// With advanced plugin configuration
export default defineConfig({
integrations: [
mdx({
remarkPlugins: [
[remarkToc, { heading: "contents" }],
remarkMath,
],
rehypePlugins: [
[rehypeMathjax, { tex: { displayMath: [["$$", "$$"]] } }],
],
recmaPlugins: [],
}),
],
});Container Renderer Function
Returns the container renderer configuration for MDX components in server contexts.
/**
* Returns container renderer configuration for MDX components
* @returns ContainerRenderer configuration object
*/
export function getContainerRenderer(): ContainerRenderer;
interface ContainerRenderer {
/** Renderer identifier */
name: string;
/** Path to server entrypoint for rendering */
serverEntrypoint: string;
}Usage Example:
import { getContainerRenderer } from "@astrojs/mdx";
// Get renderer configuration
const renderer = getContainerRenderer();
// Returns: { name: 'astro:jsx', serverEntrypoint: '@astrojs/mdx/server.js' }Integration Hooks
The MDX integration uses two main Astro hooks:
astro:config:setup Hook
This hook runs during Astro's configuration setup phase and:
- Adds the JSX renderer for MDX components
- Registers the
.mdxpage extension - Configures content entry type for
.mdxfiles in content collections - Sets up Vite plugins for MDX processing
astro:config:done Hook
This hook runs after configuration is finalized and:
- Resolves final MDX options by merging user config with defaults
- Handles markdown config inheritance via
extendMarkdownConfigoption - Configures processor options for the Vite plugin
Content Collections Support
The integration automatically configures support for .mdx files in Astro's content collections:
// Automatic content entry type registration
{
extensions: ['.mdx'],
async getEntryInfo({ fileUrl, contents }) {
const parsed = safeParseFrontmatter(contents, fileURLToPath(fileUrl));
return {
data: parsed.frontmatter,
body: parsed.content.trim(),
slug: parsed.frontmatter.slug,
rawData: parsed.rawFrontmatter,
};
},
contentModuleTypes: "...", // TypeScript definitions
handlePropagation: true, // Enable script/style propagation
}This enables using .mdx files in content collections with:
- Automatic frontmatter parsing
- Type-safe content queries
- Component and script propagation
- Custom slug generation
Default Configuration
The integration applies these defaults when no options are provided:
const defaultMdxOptions = {
extendMarkdownConfig: true,
recmaPlugins: [],
optimize: false,
};When extendMarkdownConfig is true, the integration inherits configuration from Astro's markdown settings, including:
- Syntax highlighting configuration
- Built-in plugins (GFM, Smartypants)
- Remark and rehype plugins
- Shiki/Prism configuration