Fix Astro 7 markdown.rehypePlugins Deprecation Warning

Why the warning happens

Astro 7 defaults to Sätteri, a new Rust Markdown processor with no plugin system of its own. Setting markdown.remarkPlugins, markdown.rehypePlugins, or markdown.remarkRehype at the top level tells Astro to fall back to the older @astrojs/markdown-remark unified pipeline instead, since only that pipeline can run remark and rehype plugins at all.

That fallback still works. The top-level config keys used to trigger it are deprecated, in favor of passing the same options directly to a unified() processor object. This site’s own astro.config.mjs hits the warning for exactly this reason: it sets markdown.rehypePlugins to add scope="col" to table headers and to style code block chrome, both real rehype plugins this site depends on.

[astro] `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` are deprecated. Pass them to `unified({...})` from `@astrojs/markdown-remark` directly instead.

The fix: move plugins into unified()

@astrojs/markdown-remark exports a unified() processor factory built exactly for this. Its own type definitions document the replacement shape directly:

// BROKEN, prints the deprecation warning on every build
markdown: {
  rehypePlugins: [rehypeTableHeaderScope, rehypeCodeBlockChrome],
},

import { unified } from "@astrojs/markdown-remark";

// FIXED, same plugins, no warning
markdown: {
  processor: unified({
    rehypePlugins: [rehypeTableHeaderScope, rehypeCodeBlockChrome],
  }),
},

remarkPlugins and remarkRehype move the same way, as options on that same unified({...}) call.

Confirmed against a real build

Applying this exact change to this site’s own astro.config.mjs and running npx astro build removes the warning completely, with all 52 pages still building. The scope="col" attribute the rehypeTableHeaderScope plugin adds still shows up in the rendered output afterward, confirmed by grepping the built HTML for both posts that use a table. Nothing about the page output changed, only the warning disappeared.

This site hasn’t made the change permanent yet since the deprecated form still works cleanly on astro@7.1.3, but the fix above is the exact, tested change to make when migrating ahead of Astro 8.

See the Guides & Fixes archive for more fixes from this same upgrade.