MDX
@ecopages/mdx has two parts. The standalone MDXPlugin is an IntegrationPlugin for third-party JSX runtimes such as @kitajs/html. The core export (@ecopages/mdx/core) holds the shared loader and option helpers that the React and Ecopages JSX Integrations reuse for their own MDX. For where Integrations sit, see /dev/plugin-pipeline.
The standalone plugin
mdxPlugin({ compilerOptions }) extends IntegrationPlugin with the name MDX, the MDXRenderer, and extensions defaulting to ['.mdx'].
compilerOptions.jsxImportSourceis required. The constructor throws forreact(andreact/*) and for@ecopages/jsx(and@ecopages/jsx/*), pointing atreactPlugin({ mdx })andecopagesJsxPlugin({ mdx }).- Defaults are
format: 'detect',outputFormat: 'program',jsxRuntime: 'automatic', anddevelopmentfrom the runtime. plugins(app)returns onemdx-loaderbuild plugin, withprojectRootset toapp.rootDir.
The renderer uses core's shared route renderer with two hooks: normalizePageModule (requires a default function export, normalizes config.layout onto config.layouts and config.layoutEntries with ensurePageConfigLayouts, and returns no layout of its own, since core renders the whole config.layouts stack outer to inner) and a Page Browser Graph contribution that adds the layouts' and the Page's config as components. See /dev/pages-layouts-components.
Where the options live
| Plugin | MDX options | Plugin lists (remarkPlugins, rehypePlugins, recmaPlugins) |
|---|---|---|
mdxPlugin | compilerOptions (required jsxImportSource) | Inside compilerOptions |
reactPlugin({ mdx }) | mdx object enables MDX, omit it to disable | Top level of mdx, not accepted in compilerOptions |
ecopagesJsxPlugin({ mdx }) | Same shape as React | Top level of mdx |
React and Ecopages JSX both go through resolveMdxCompilerOptions, which forces their jsxImportSource and writes mdx.extensions over mdxExtensions instead of merging. Why: ['.react.mdx'] must not also claim plain .mdx through a leftover mdxExtensions.
Extension handling and .md
The loader's filter is built from [...mdxExtensions, ...mdExtensions] of the compiler options, matched as a suffix that allows a trailing query string.
.mdis never claimed implicitly. The standalone plugin sorts itsextensionsintomdxExtensionsandmdExtensions; only a declared.mdlands in the latter. The React loader passesdefaultMdExtensions: [].- A
.mdfile is compiled withformat: 'mdx'unless a non-detectformat is configured. Why: indetectmode.mdis plain markdown, and top-levelimportandexportwould render as text.
Scoping by extension
Each Integration registers its own loader, and a loader only matches its own extensions: mdx-loader for the standalone plugin, react-mdx-loader, and ecopages-jsx-mdx-loader. The extensions are also added to the Integration's extensions, so route matching and the loader agree on which files the Integration owns. Two Integrations can therefore compile MDX side by side as long as their extensions are disjoint, and an entry compiled by one is a Component owned by that Integration. See /dev/integrations-foreign-children and /dev/content-processor for how an entry rendered under another lane is handed off or rejected.
The loader and its compile cache
createMdxLoaderPlugin is one onLoad per file. projectRoot is required and the factory throws without it.
- The cache is a per-loader
Mapkeyed by file path, reused while the source text is unchanged. One loader instance serves server builds, browser bundles and HMR rebuilds, so they share compiles. A new loader, for example after a config reload, starts empty. - Only the compile is cached. Identity attribution runs on every load, so a change to an imported Component applies without recompiling the MDX.
attributeMdxComponentIdentitybinds Component identity (integration name and project root), discovers top-level Component and stylesheet imports, and attaches them toconfig. Stylesheet imports are stripped from the output. The loader receives the app's stylesheet kinds (getStylesheetKinds(app), from the registered stylesheet Processor) from the Integration that creates it and passes them on, so an.mdxdocument discoversimport './card.scss'exactly as a.tsxPage does; without a declaring Processor only.cssis discovered. Imports inside code blocks and functions are left alone. See /dev/plugin-pipeline for identity attribution.- Source maps: the compiler map is composed with the identity edits and returned unless
includeSourceMapis false. The Ecopages JSX loader sets it to false. - The plugin's
cacheKeyfingerprints compiler options, extensions,includeSourceMapandloader, neverprojectRoot, as no plugin key holds an absolute path. Functions such as remark plugins enter by name, so two loaders differing only in an anonymous plugin's closure share a key. loaderisjsxwhencompilerOptions.jsxis set, otherwisejs.
Sources
This page describes the code below.
packages/integrations/mdx/src/mdx.plugin.tspackages/integrations/mdx/src/mdx-loader-plugin.tspackages/integrations/mdx/src/mdx-renderer.tspackages/integrations/mdx/src/mdx.types.tspackages/integrations/mdx/src/core/packages/integrations/react/src/mdx/mdx-loader-plugin.tspackages/integrations/ecopages-jsx/src/ecopages-jsx-mdx.tspackages/core/src/plugins/eco-component-meta-plugin.ts