astro-xmdx

astro-xmdx

Astro integration for xmdx, a high-performance MDX compiler.

Runnable Examples

• Starlight: examples/starlight

Installation

npm install astro-xmdx
# or
pnpm add astro-xmdx
# or
yarn add astro-xmdx

Basic Setup

// astro.config.mjs
import { defineConfig } from 'astro/config';
import xmdx from 'astro-xmdx';

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

Presets

Use presets to quickly configure common stacks.

Starlight

import { defineConfig } from 'astro/config';
import xmdx from 'astro-xmdx';
import { starlightPreset } from 'astro-xmdx/presets';

export default defineConfig({
  integrations: [
    xmdx({
      presets: [starlightPreset()],
    }),
  ],
});

Expressive Code

import { defineConfig } from 'astro/config';
import xmdx from 'astro-xmdx';
import { expressiveCodePreset } from 'astro-xmdx/presets';

export default defineConfig({
  integrations: [
    xmdx({
      presets: [expressiveCodePreset()],
    }),
  ],
});

Multiple Presets

import { defineConfig } from 'astro/config';
import xmdx from 'astro-xmdx';
import { astroPreset, starlightPreset } from 'astro-xmdx/presets';

export default defineConfig({
  integrations: [
    xmdx({
      presets: [astroPreset(), starlightPreset()],
    }),
  ],
});

Configuration

import { defineConfig } from 'astro/config';
import xmdx from 'astro-xmdx';
import { starlightPreset } from 'astro-xmdx/presets';

export default defineConfig({
  integrations: [
    xmdx({
      include: (id) => id.endsWith('.md') || id.endsWith('.mdx'),
      presets: [starlightPreset()],
      expressiveCode: {
        enabled: true,
        componentName: 'Code',
        importSource: '@astrojs/starlight/components',
      },
      mdx: {
        allowImports: ['@astrojs/starlight/*', '~/components/*'],
        ignoreCodeFences: true,
      },
      compiler: {
        jsx: {
          code_sample_components: ['Code'],
        },
      },
    }),
  ],
});

Starlight Behavior

When @astrojs/starlight is detected, astro-xmdx automatically applies safe defaults unless explicitly overridden:

• enables Starlight component injection
• allows common Starlight import patterns for MDX fallback handling
• enables Expressive Code rewriting for fenced code blocks

In Starlight setups, the Code component resolution prefers @astrojs/starlight/components.

Options

Option	Type	Description
include	(id: string) => boolean	File filter. Defaults to .md and .mdx files.
libraries	ComponentLibrary[]	Component libraries to register.
presets	PresetConfig[]	Presets merged in order (later presets win on conflicts).
starlightComponents	boolean | { enabled: boolean; importSource?: string }	Starlight component injection config.
expressiveCode	boolean | { enabled: boolean; componentName?: string; importSource?: string }	Expressive Code code-block rewrite config.
compiler	{ jsx?: { code_sample_components?: string[] } }	Compiler options passed to xmdx.
plugins	XmdxPlugin[]	Pipeline hooks (preprocess, afterParse, beforeInject, beforeOutput).
mdx	{ allowImports?: string[]; ignoreCodeFences?: boolean }	Controls import fallback behavior for MDX files.

Exports

Export	Description
astro-xmdx	Main Astro integration.
astro-xmdx/server	Server entrypoint export alias.
astro-xmdx/server.js	Server entrypoint export.
astro-xmdx/presets	Preset helpers (starlightPreset, expressiveCodePreset, astroPreset).
astro-xmdx/vite-plugin	Standalone Vite plugin.
astro-xmdx/pipeline	Pipeline utilities.
astro-xmdx/transforms	Transform utilities.

License

MIT