or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdindex.mdintegration.mdserver.md
tile.json

tessl/npm-astrojs--mdx

Astro integration that enables MDX support for creating interactive pages and components with Markdown and JSX

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@astrojs/mdx@4.3.x

To install, run

npx @tessl/cli install tessl/npm-astrojs--mdx@4.3.0

index.mddocs/

@astrojs/mdx

The @astrojs/mdx integration enables MDX (Markdown with JSX) support in Astro projects. It allows developers to create pages and components using .mdx files, combining the simplicity of Markdown with the power of React/JSX components. The integration provides comprehensive MDX processing with support for plugins, frontmatter, component imports, and static optimization.

Package Information

  • Package Name: @astrojs/mdx
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @astrojs/mdx
  • Peer Dependencies: astro ^5.0.0

Core Imports

import mdx from "@astrojs/mdx";
import { getContainerRenderer } from "@astrojs/mdx";

For server-side utilities:

import { check, renderToStaticMarkup } from "@astrojs/mdx/server.js";

Basic Usage

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

export default defineConfig({
  integrations: [
    mdx({
      // Extend Astro's markdown configuration
      extendMarkdownConfig: true,
      // Add remark/rehype plugins
      remarkPlugins: [],
      rehypePlugins: [],
      // Enable static optimization
      optimize: true,
    }),
  ],
});

Architecture

The @astrojs/mdx integration is built around several key components:

  • Integration Core: Main integration function that hooks into Astro's build system
  • MDX Processor: Handles MDX compilation with configurable remark/rehype plugins
  • Vite Plugins: Transform .mdx files during the build process
  • Server Renderer: Provides server-side rendering capabilities for MDX components
  • Content Collections: Enables .mdx files in Astro's content collections system
  • Static Optimization: Optional performance optimization for static content

Capabilities

Main Integration

Core integration functionality for adding MDX support to Astro projects. Handles configuration, plugin setup, and build system integration.

/**
 * Creates an Astro integration for MDX support
 * @param partialMdxOptions - Optional MDX configuration options
 * @returns AstroIntegration object with hooks and configuration
 */
export default function mdx(partialMdxOptions?: Partial<MdxOptions>): AstroIntegration;

/**
 * Returns container renderer configuration for MDX components
 * @returns ContainerRenderer configuration object
 */
export function getContainerRenderer(): ContainerRenderer;

Main Integration

Server-Side Rendering

Server-side rendering utilities for MDX components, including component validation and HTML generation.

/**
 * Checks if a component is a valid MDX component for rendering
 * @param Component - Component to check
 * @param props - Component properties
 * @param slotted - Slotted content with default children
 * @returns Promise resolving to boolean indicating validity
 */
export async function check(
  Component: any,
  props: any,
  slotted?: { default?: any; [key: string]: any }
): Promise<boolean>;

/**
 * Renders MDX component to static HTML markup
 * @param Component - Component to render  
 * @param props - Component properties
 * @param slotted - Slotted content with default children
 * @returns Promise resolving to object with html property
 */
export async function renderToStaticMarkup(
  Component: any,
  props?: any,
  slotted?: { default?: any; [key: string]: any }
): Promise<{ html: string }>;

Server-Side Rendering

Configuration and Types

Comprehensive type definitions and configuration options for customizing MDX behavior, plugin integration, and optimization settings.

interface MdxOptions {
  /** Whether to extend Astro's markdown configuration */
  extendMarkdownConfig: boolean;
  /** List of recma plugins to apply */
  recmaPlugins: PluggableList;
  /** List of remark plugins (overrides string support from markdown) */
  remarkPlugins: PluggableList;
  /** List of rehype plugins (overrides string support from markdown) */
  rehypePlugins: PluggableList;
  /** Options for remark-rehype transformation */
  remarkRehype: RemarkRehypeOptions;
  /** Enable/configure static optimization */
  optimize: boolean | OptimizeOptions;
  // Plus all other properties from Astro's markdownConfigDefaults
}

interface OptimizeOptions {
  /** Element names to exclude from optimization */
  ignoreElementNames?: string[];
}

Configuration

Types

interface ContainerRenderer {
  name: string;
  serverEntrypoint: string;
}

interface FileInfo {
  fileId: string;
  fileUrl: string;
}

type PluggableList = Array<Plugin | [Plugin, ...Parameters]>;

// Supporting types
type Plugin = any; // Plugin functions from unified ecosystem  
type Parameters = any[];

Content Collections Integration

MDX files can be used in Astro's content collections system with automatic frontmatter parsing and type safety. The integration automatically registers the .mdx content entry type and provides TypeScript definitions.

// Content module types are automatically available when using @astrojs/mdx
declare module 'astro:content' {
  interface Render {
    '.mdx': Promise<{
      /** Rendered MDX component for use in Astro templates */
      Content: import('astro').MarkdownInstance<{}>['Content'];
      /** Extracted heading information from the MDX content */
      headings: import('astro').MarkdownHeading[];
      /** Frontmatter data processed by remark plugins */
      remarkPluginFrontmatter: Record<string, any>;
      /** Available MDX components and their definitions */
      components: import('astro').MDXInstance<{}>['components'];
    }>;
  }
}

Usage in content collections:

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
  }),
});

export const collections = { blog };
// src/pages/blog/[...slug].astro
---
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { slug: post.slug },
    props: post,
  }));
}

const { Content, headings } = await Astro.props.render();
---

<html>
  <head>
    <title>{Astro.props.data.title}</title>
  </head>
  <body>
    <h1>{Astro.props.data.title}</h1>
    <Content />
  </body>
</html>