Skip to content

feat: docs for pluggable Markdown processors #13919

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Princesseuh wants to merge 2 commits into
base: v7
Choose a base branch
from
Open

feat: docs for pluggable Markdown processors #13919

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9495a11
feat: docs for pluggable Markdown processors
Princesseuh May 21, 2026
f9468a2
feat: update upgrade guide
Princesseuh May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 43 additions & 26 deletions src/content/docs/en/guides/integrations-guide/mdx.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -255,41 +255,61 @@
You can configure how your MDX is rendered with the following options:

* [Options inherited from Markdown config](#options-inherited-from-markdown-config)
* [`processor`](#processor)
* [`extendMarkdownConfig`](#extendmarkdownconfig)
* [`recmaPlugins`](#recmaplugins)
* [`optimize`](#optimize)

### Options inherited from Markdown config

All [`markdown` configuration options](/en/reference/configuration-reference/#markdown-options) can be configured separately in the MDX integration. This includes remark and rehype plugins, syntax highlighting, and more. Options will default to those in your Markdown config ([see the `extendMarkdownConfig` option](#extendmarkdownconfig) to modify this).
All [`markdown` configuration options](/en/reference/configuration-reference/#markdown-options) can be configured separately in the MDX integration, including the [Markdown processor](#processor), syntax highlighting, and more. Options will default to those in your Markdown config ([see the `extendMarkdownConfig` option](#extendmarkdownconfig) to modify this).

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import { defineConfig, satteri } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypePresetMinify from 'rehype-preset-minify';

export default defineConfig({
// ...
integrations: [
mdx({
syntaxHighlight: 'shiki',
shikiConfig: { theme: 'dracula' },
remarkPlugins: [remarkToc],
rehypePlugins: [rehypePresetMinify],
remarkRehype: { footnoteLabel: 'Footnotes' },
gfm: false,
processor: satteri({ features: { gfm: false } }),
}),
],
});
```

:::caution
MDX does not support passing remark and rehype plugins as a string. You should install, import, and apply the plugin function instead.
:::

<ReadMore>See the [Markdown Options reference](/en/reference/configuration-reference/#markdown-options) for a complete list of options.</ReadMore>

### `processor`

<p>

**Type:** `MarkdownProcessorEntry`<br />
**Default:** inherited from [`markdown.processor`](/en/reference/configuration-reference/#markdownprocessor)<br />

Check failure on line 290 in src/content/docs/en/guides/integrations-guide/mdx.mdx

View workflow job for this annotation

GitHub Actions / Check Links 

Broken fragment link in src/content/docs/en/guides/integrations-guide/mdx.mdx, line 290: The linked page does not contain a fragment with the name "#markdownprocessor". Available fragments: #theme-icons, #gradient, #starlight__sidebar, #__tab-tutorial, #__tab-guide, #__tab-reference, #__tab-ecosystem, #starlight__mobile-toc, #starlight__on-this-page--mobile, #starlight__on-this-page, #learn-astro-course-1, #_top, #top-level-options, #site, #base, #trailingslash, #redirects, #output, #adapter, #integrations, #root, #examples, #srcdir, #publicdir, #outdir, #cachedir, #compresshtml, #scopedstylestrategy, #prerenderconflictbehavior, #vite, #examples-1, #security, #securitycheckorigin, #securityalloweddomains, #securityactionbodysizelimit, #securityserverislandbodysizelimit, #securitycsp, #securitycspalgorithm, #securitycspdirectives, #securitycspstyledirective, #securitycspstyledirectivehashes, #securitycspstyledirectiveresources, #securitycspscriptdirective, #securitycspscriptdirectivehashes, #securitycspscriptdirectiveresources, #securitycspscriptdirectivestrictdynamic, #build-options, #buildformat, #effect-on-astrourl, #buildclient, #buildserver, #buildassets, #buildassetsprefix, #buildserverentry, #buildredirects, #buildinlinestylesheets, #buildconcurrency, #server-options, #serverhost, #serverport, #serverallowedhosts, #serveropen, #serverheaders, #session-options, #sessiondriver, #sessionoptions, #sessioncookie, #sessionttl, #dev-toolbar-options, #devtoolbarenabled, #devtoolbarplacement, #prefetch-options, #prefetchprefetchall, #prefetchdefaultstrategy, #image-options, #imageendpoint, #imageservice, #imageserviceconfiglimitinputpixels, #imageserviceconfigkernel, #imageserviceconfigjpeg, #imageserviceconfigwebp, #imageserviceconfigavif, #imageserviceconfigpng, #imagedangerouslyprocesssvg, #imagedomains, #imageremotepatterns, #imageresponsivestyles, #imagelayout, #imageobjectfit, #imageobjectposition, #imagebreakpoints, #markdown-options, #markdownshikiconfig, #markdownsyntaxhighlight, #markdownsyntaxhighlighttype, #markdownsyntaxhighlightexcludelangs, #markdownremarkplugins, #markdownrehypeplugins, #markdowngfm, #markdownsmartypants, #markdownremarkrehype, #i18n, #i18nlocales, #i18ndefaultlocale, #i18nfallback, #example, #i18nrouting, #i18nroutingprefixdefaultlocale, #i18nroutingredirecttodefaultlocale, #i18nroutingfallbacktype, #i18ndomains, #env, #envschema, #envvalidatesecrets, #fonts, #fontprovider, #fontname, #fontcssvariable, #fontfallbacks, #fontoptimizedfallbacks, #fontweights, #fontstyles, #fontsubsets, #fontformats, #fontoptions, #fontdisplay, #fontunicoderange, #fontstretch, #fontfeaturesettings, #fontvariationsettings, #docsearch-lvl0, #learn-astro-course-2
<Since v="6.0.0" pkg="@astrojs/mdx" />
</p>

By default, `.mdx` files are rendered with the same [Markdown processor](/en/guides/markdown-content/#choosing-a-markdown-processor) as your `.md` files. Both file types render through [Sätteri](https://satteri.bruits.org/) unless you configure `markdown.processor`.

Set `processor` to run `.mdx` files through a different processor, or the same processor with different options, than your `.md` files:

```js title="astro.config.mjs"
import { defineConfig, satteri } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
markdown: {
processor: satteri({ features: { directive: true } }),
},
integrations: [
// `.mdx` files render through Sätteri without the `directive` feature
mdx({ processor: satteri() }),
],
});
```

### `extendMarkdownConfig`

<p>
Expand All @@ -301,28 +321,25 @@

MDX will extend [your project's existing Markdown configuration](/en/reference/configuration-reference/#markdown-options) by default. To override individual options, you can specify their equivalent in your MDX configuration.

For example, say you need to disable GitHub-Flavored Markdown and apply a different set of remark plugins for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:
For example, say you need to use a different syntax highlighter and disable GitHub-Flavored Markdown for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:
Copy link
Copy Markdown
Member

@ArmandPhilippot ArmandPhilippot May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either we should remove this:

Suggested change
For example, say you need to use a different syntax highlighter and disable GitHub-Flavored Markdown for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:
For example, say you need to disable GitHub-Flavored Markdown for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:

or the example should configure a different syntax highlighter (e.g. Prism for Markdown, Shiki for MDX).

Because, if we set Shiki for Markdown, MDX will also use Shiki and so, we use the same syntax highlighter, right?


```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import { defineConfig, satteri } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
// ...
markdown: {
syntaxHighlight: 'prism',
remarkPlugins: [remarkPlugin1],
gfm: true,
syntaxHighlight: 'shiki',
processor: satteri({ features: { gfm: true } }),
},
integrations: [
mdx({
// `syntaxHighlight` inherited from Markdown

// Markdown `remarkPlugins` ignored,
// only `remarkPlugin2` applied.
remarkPlugins: [remarkPlugin2],
// `gfm` overridden to `false`
gfm: false,
// Markdown `processor` ignored,
// `.mdx` files use this processor instead.
processor: satteri({ features: { gfm: false } }),
}),
],
});
Expand All @@ -331,19 +348,19 @@
You may also need to disable `markdown` config extension in MDX. For this, set `extendMarkdownConfig` to `false`:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import { defineConfig, satteri } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
// ...
markdown: {
remarkPlugins: [remarkPlugin1],
processor: satteri({ features: { directive: true } }),
},
integrations: [
mdx({
// Markdown config now ignored
extendMarkdownConfig: false,
// No `remarkPlugins` applied
// Default `satteri()` processor used
}),
],
});
Expand Down Expand Up @@ -371,7 +388,7 @@
<Since v="0.19.5" pkg="@astrojs/mdx" />
</p>

This is an optional configuration setting to optimize the MDX output for faster builds and rendering via an internal rehype plugin. This may be useful if you have many MDX files and notice slow builds. However, this option may generate some unescaped HTML, so make sure your site's interactive parts still work correctly after enabling it.
This is an optional configuration setting to optimize the MDX output for faster builds and rendering via an internal optimization step. This may be useful if you have many MDX files and notice slow builds. However, this option may generate some unescaped HTML, so make sure your site's interactive parts still work correctly after enabling it.

This is disabled by default. To enable MDX optimization, add the following to your MDX integration configuration:

Expand Down
Loading
Loading