withastro/astro · warning

To inherit Markdown plugins in MDX, please use explicit impo

Error message

To inherit Markdown plugins in MDX, please use explicit imports in your config instead of "strings." See Markdown docs: https://docs.astro.build/en/guides/markdown-content/#markdown-plugins

What it means

This is the one-time follow-up guidance emitted by ignoreStringPlugins() in @astrojs/mdx after at least one string-named markdown plugin was discarded. It explains why the preceding 'not applied' warnings happened: MDX cannot inherit string plugins from the markdown config, and points to the Markdown docs section on plugin imports. It is purely informational on top of the real problem (plugins were dropped).

Source

Thrown at packages/integrations/mdx/src/utils.ts:103

	};
}

export function ignoreStringPlugins(plugins: any[], logger: AstroIntegrationLogger): PluggableList {
	let validPlugins: PluggableList = [];
	let hasInvalidPlugin = false;
	for (const plugin of plugins) {
		if (typeof plugin === 'string') {
			logger.warn(`${colors.bold(plugin)} not applied.`);
			hasInvalidPlugin = true;
		} else if (Array.isArray(plugin) && typeof plugin[0] === 'string') {
			logger.warn(`${colors.bold(plugin[0])} not applied.`);
			hasInvalidPlugin = true;
		} else {
			validPlugins.push(plugin);
		}
	}
	if (hasInvalidPlugin) {
		logger.warn(
			`To inherit Markdown plugins in MDX, please use explicit imports in your config instead of "strings." See Markdown docs: https://docs.astro.build/en/guides/markdown-content/#markdown-plugins`,
		);
	}
	return validPlugins;
}

View on GitHub (pinned to 52e6c34790)

Solutions

1. Fix the underlying issue: convert every string plugin in markdown.remarkPlugins/rehypePlugins to an imported function (this warning disappears with them).
2. If a plugin cannot be imported (e.g. CJS-only), import it via createRequire or use its ESM entry, still passing the function value.
3. Verify by rebuilding: no 'not applied' lines and no 'To inherit Markdown plugins' guidance should print.

Example fix

// before
remarkPlugins: ['remark-gfm', ['remark-math', {}]]

// after
import remarkGfm from 'remark-gfm';
import remarkMath from 'remark-math';
remarkPlugins: [remarkGfm, [remarkMath, {}]]

// fail fast in a config-check script
import { remarkPlugins, rehypePlugins } from './astro.config.mjs';
const offenders = [...remarkPlugins, ...rehypePlugins].filter(
  (p) => typeof p === 'string' || (Array.isArray(p) && typeof p[0] === 'string'),
);
if (offenders.length) {
  throw new Error(`String plugins will not apply to MDX: ${offenders.join(', ')}`);
}

When it happens

Trigger: Any build or dev run where config.markdown.remarkPlugins/rehypePlugins contained at least one string or string-headed tuple, causing hasInvalidPlugin to be set true in ignoreStringPlugins() when the MDX integration reads the markdown config.

Common situations: Seen together with the per-plugin 'not applied' warnings; typically the first symptom a developer notices that their GFM tables, external-link handling, or math rendering work in .md pages but not in .mdx pages.

Related errors

• ${colors.bold(plugin)} not applied.
• ${colors.bold(plugin[0])} not applied.
• ${names} on `mdx({...})` ${isPlural ? 'are' : 'is'} deprecat
• The markdown processor "${processor.name}" does not provide
• [astro] ${names} ${isPlural ? 'are' : 'is'} deprecated. Move

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/cf9465426b43bc96. Report an issue: GitHub.