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

Merged
ArmandPhilippot merged 20 commits into from
May 27, 2026
Merged

feat: docs for pluggable Markdown processors #13919

Show file tree
Hide file tree
Changes from 15 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
f294490
feat: docs for pluggable Markdown processors
Princesseuh May 21, 2026
9fc3795
Update src/content/docs/en/guides/markdown-content.mdx
Princesseuh May 22, 2026
3fa9a1a
Update src/content/docs/en/guides/markdown-content.mdx
Princesseuh May 22, 2026
0160ad7
Update src/content/docs/en/recipes/reading-time.mdx
Princesseuh May 22, 2026
543fb80
Update src/content/docs/en/guides/markdown-content.mdx
Princesseuh May 22, 2026
2b01f35
Merge branch 'main' into feat/markdown-agnostic
Princesseuh May 23, 2026
a84b870
fix: rework for main
Princesseuh May 23, 2026
c1ffee2
fix: bring back changes
Princesseuh May 23, 2026
03fd7e7
Apply suggestion from @Princesseuh
Princesseuh May 23, 2026
b49243c
fix: innacuracies
Princesseuh May 27, 2026
244d570
Apply suggestion from @Princesseuh
Princesseuh May 27, 2026
a5fed26
Apply suggestion from @Princesseuh
Princesseuh May 27, 2026
911e56c
Apply suggestion from @Princesseuh
Princesseuh May 27, 2026
1697382
fix: some tweaks
Princesseuh May 27, 2026
4f05377
feat: adjust for plugin ordering
Princesseuh May 27, 2026
b4ad1c1
Apply suggestions from code review
Princesseuh May 27, 2026
bd8b401
Apply suggestions from code review
Princesseuh May 27, 2026
b513e28
bad GitHub
ArmandPhilippot May 27, 2026
c891f36
Merge branch 'main' into feat/markdown-agnostic
ArmandPhilippot May 27, 2026
d71f973
ci: update configuration reference docs (#13943)
astrobot-houston May 27, 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
65 changes: 45 additions & 20 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,16 +255,18 @@
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 { unified } from '@astrojs/markdown-remark';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypePresetMinify from 'rehype-preset-minify';
Expand All @@ -275,21 +277,44 @@
mdx({
syntaxHighlight: 'shiki',
shikiConfig: { theme: 'dracula' },
remarkPlugins: [remarkToc],
rehypePlugins: [rehypePresetMinify],
remarkRehype: { footnoteLabel: 'Footnotes' },
gfm: false,
processor: unified({
remarkPlugins: [remarkToc],
rehypePlugins: [rehypePresetMinify],
remarkRehype: { footnoteLabel: 'Footnotes' },
Comment thread
Princesseuh marked this conversation as resolved.
Resolved
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:** `MarkdownProcessor`<br />
**Default:** inherited from [`markdown.processor`](/en/reference/configuration-reference/#markdownprocessor)<br />

Check failure on line 298 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 298: 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 render through the same [Markdown processor](/en/guides/markdown-content/#choosing-a-markdown-processor) as your `.md` files. Set `processor` to use a different processor, or the same processor with different options, for `.mdx` files only.

For example, to keep the default remark/rehype processor for `.md` files while rendering `.mdx` files with [Sätteri](https://satteri.bruits.org/) using `@astrojs/markdown-satteri`:

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

export default defineConfig({
integrations: [
mdx({ processor: satteri() }),
],
});
```

### `extendMarkdownConfig`

<p>
Expand All @@ -301,28 +326,27 @@

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 a different syntax highlighter and a different set of plugins for `.mdx` files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import mdx from '@astrojs/mdx';

export default defineConfig({
// ...
markdown: {
syntaxHighlight: 'prism',
remarkPlugins: [remarkPlugin1],
gfm: true,
processor: unified({ remarkPlugins: [remarkPlugin1] }),
},
integrations: [
mdx({
// `syntaxHighlight` inherited from Markdown
// Markdown `syntaxHighlight` overridden,
// `.mdx` files use Shiki instead.
syntaxHighlight: 'shiki',

// Markdown `remarkPlugins` ignored,
// only `remarkPlugin2` applied.
remarkPlugins: [remarkPlugin2],
// `gfm` overridden to `false`
gfm: false,
// `markdown.processor` gets overridden for `.mdx` files by this option
processor: unified({ remarkPlugins: [remarkPlugin2] }),
}),
],
});
Expand All @@ -332,18 +356,19 @@

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import mdx from '@astrojs/mdx';

export default defineConfig({
// ...
markdown: {
remarkPlugins: [remarkPlugin1],
processor: unified({ remarkPlugins: [remarkPlugin] }),
},
integrations: [
mdx({
// Markdown config now ignored
extendMarkdownConfig: false,
// No `remarkPlugins` applied
// Default `unified()` processor used
}),
],
});
Expand Down
Loading
Loading