From f29449060685865ea1719096e5e8ff34ffcededb Mon Sep 17 00:00:00 2001
From: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
Date: Thu, 21 May 2026 02:00:20 +0200
Subject: [PATCH 01/18] feat: docs for pluggable Markdown processors
---
.../docs/en/guides/integrations-guide/mdx.mdx | 69 ++++----
.../docs/en/guides/markdown-content.mdx | 147 +++++++++++++-----
.../docs/en/guides/migrate-to-astro/index.mdx | 2 +-
.../docs/en/recipes/external-links.mdx | 29 ++--
src/content/docs/en/recipes/modified-time.mdx | 11 +-
src/content/docs/en/recipes/reading-time.mdx | 14 +-
.../en/reference/content-loader-reference.mdx | 2 +-
.../en/reference/modules/astro-content.mdx | 2 +-
.../en/reference/programmatic-reference.mdx | 2 +-
9 files changed, 182 insertions(+), 96 deletions(-)
diff --git a/src/content/docs/en/guides/integrations-guide/mdx.mdx b/src/content/docs/en/guides/integrations-guide/mdx.mdx
index 94872d9efb6bf..b300d24259ee4 100644
--- a/src/content/docs/en/guides/integrations-guide/mdx.mdx
+++ b/src/content/docs/en/guides/integrations-guide/mdx.mdx
@@ -255,19 +255,18 @@ Once the MDX integration is installed, no configuration is necessary to use `.md
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({
// ...
@@ -275,21 +274,42 @@ export default defineConfig({
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.
-:::
-
See the [Markdown Options reference](/en/reference/configuration-reference/#markdown-options) for a complete list of options.
+### `processor`
+
+
+
+**Type:** `MarkdownProcessorEntry`
+**Default:** inherited from [`markdown.processor`](/en/reference/configuration-reference/#markdownprocessor)
+
+
+
+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`
@@ -301,28 +321,25 @@ MDX does not support passing remark and rehype plugins as a string. You should i
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:
```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 } }),
}),
],
});
@@ -331,19 +348,19 @@ export default defineConfig({
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
}),
],
});
@@ -371,7 +388,7 @@ We suggest [using AST Explorer](https://astexplorer.net/) to play with estree ou
-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:
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index e6439ebeaa121..b8904c3f6d072 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -10,6 +10,7 @@ import { FileTree } from '@astrojs/starlight/components';
import RecipeLinks from "~/components/RecipeLinks.astro";
import ReadMore from '~/components/ReadMore.astro';
import { Steps } from '@astrojs/starlight/components';
+import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
[Markdown](https://daringfireball.net/projects/markdown/) is commonly used to author text-heavy content like blog posts and documentation. Astro includes built-in support for Markdown files that can also include [frontmatter YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) (or [TOML](https://toml.io)) to define custom properties such as a title, description, and tags.
@@ -71,7 +72,7 @@ const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }));
When fetching data from your collections with the helper functions `getCollection()` or `getEntry()`, your Markdown's frontmatter properties are available on a `data` object (e.g. `post.data.title`). Additionally, `body` contains the raw, uncompiled body content as a string.
-The [`render()`](/en/reference/modules/astro-content/#render) function returns your Markdown body content, a generated list of headings, as well as a modified frontmatter object after any remark or rehype plugins have been applied.
+The [`render()`](/en/reference/modules/astro-content/#render) function returns your Markdown body content, a generated list of headings, as well as a modified frontmatter object after any [Markdown plugins](#markdown-plugins) have been applied.
Read more about [using content returned by a collections query](/en/guides/content-collections/#using-content-in-astro-templates).
@@ -158,76 +159,138 @@ Astro generates heading `id`s based on `github-slugger`. You can find more examp
Astro injects an `id` attribute into all heading elements (`` to ``) in Markdown and MDX files. You can retrieve this data from the `getHeadings()` utility available as a [Markdown exported property](#available-properties) from an imported file, or from the `render()` function when [using Markdown returned from a content collections query](#markdown-from-content-collections-queries).
-You can customize these heading IDs by adding a rehype plugin that injects `id` attributes (e.g. `rehype-slug`). Your custom IDs, instead of Astro's defaults, will be reflected in the HTML output and the items returned by `getHeadings()`.
+You can customize these heading IDs with a [Markdown processor](#choosing-a-markdown-processor) plugin that injects `id` attributes (e.g. `rehype-slug`). Your custom IDs, instead of Astro's defaults, will be reflected in the HTML output and the items returned by `getHeadings()`.
-By default, Astro injects `id` attributes after your rehype plugins have run. If one of your custom rehype plugins needs to access the IDs injected by Astro, you can import and use Astro’s `rehypeHeadingIds` plugin directly. Be sure to add `rehypeHeadingIds` before any plugins that rely on it:
+When using the [remark/rehype processor](#using-remark-and-rehype-plugins), Astro injects `id` attributes after your rehype plugins have run. If one of your custom rehype plugins needs to access the IDs injected by Astro, you can import and use Astro’s `rehypeHeadingIds` plugin directly. Be sure to add `rehypeHeadingIds` before any plugins that rely on it:
-```js title="astro.config.mjs" ins={2, 8}
+```js title="astro.config.mjs" ins={2-3, 9}
import { defineConfig } from 'astro/config';
-import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+import { unified, rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';
export default defineConfig({
markdown: {
- rehypePlugins: [
- rehypeHeadingIds,
- otherPluginThatReliesOnHeadingIDs,
- ],
+ processor: unified({
+ rehypePlugins: [
+ rehypeHeadingIds,
+ otherPluginThatReliesOnHeadingIDs,
+ ],
+ }),
},
});
```
-## Markdown Plugins
+## Markdown plugins
+
+Astro renders Markdown using a configurable **Markdown processor**. By default, this is [Sätteri](https://satteri.bruits.org/), a fast, native Markdown and MDX compiler.
+
+The default processor applies [GitHub-Flavored Markdown](https://github.github.com/gfm/) and [SmartyPants](https://daringfireball.net/projects/smartypants/) automatically. This brings some niceties like generating clickable links from text, and formatting for quotations and em-dashes.
+
+You can extend Markdown processing with plugins, enable additional parser features, or switch to a different processor entirely. See the full list of [Markdown configuration options](/en/reference/configuration-reference/#markdown-options).
-Markdown support in Astro is powered by [remark](https://remark.js.org/), a powerful parsing and processing tool with an active ecosystem. Other Markdown parsers like Pandoc and markdown-it are not currently supported.
+### Choosing a Markdown processor
-Astro applies the [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) and [SmartyPants](https://github.com/silvenon/remark-smartypants) plugins by default. This brings some niceties like generating clickable links from text, and formatting for [quotations and em-dashes](https://daringfireball.net/projects/smartypants/).
+The [`markdown.processor` option](/en/reference/configuration-reference/#markdownprocessor) controls which engine renders your `.md` and `.mdx` files. Astro provides two built-in processors:
-You can customize how remark parses your Markdown in `astro.config.mjs`. See the full list of [Markdown configuration options](/en/reference/configuration-reference/#markdown-options).
+- **`satteri()`** (default): the native [Sätteri](https://satteri.bruits.org/) pipeline. Accepts Sätteri plugins and optional parser features.
+- **`unified()`**: the [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype) pipeline, for projects that depend on their plugin ecosystems. Provided by the separate `@astrojs/markdown-remark` package.
-### Adding remark and rehype plugins
-Astro supports adding third-party [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugins for Markdown. These plugins allow you to extend your Markdown with new capabilities, like [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and [styling your Markdown](/en/guides/styling/#markdown-styling).
+### Adding Sätteri plugins and features
+
+The default [`satteri()` processor](#choosing-a-markdown-processor) accepts plugins and parser feature toggles. Import `satteri` from `astro/config`, configure it, and pass it to `markdown.processor`:
+
+```js title="astro.config.mjs"
+import { defineConfig, satteri } from 'astro/config';
+import myMdastPlugin from './my-mdast-plugin.js';
+import myHastPlugin from './my-hast-plugin.js';
+
+export default defineConfig({
+ markdown: {
+ processor: satteri({
+ mdastPlugins: [myMdastPlugin],
+ hastPlugins: [myHastPlugin],
+ features: { directive: true, definitionList: true },
+ }),
+ },
+});
+```
-We encourage you to browse [awesome-remark](https://github.com/remarkjs/awesome-remark) and [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for popular plugins! See each plugin's own README for specific installation instructions.
+- `mdastPlugins` and `hastPlugins` add Sätteri plugins that transform the Markdown (MDAST) or HTML (HAST) syntax tree.
+- `features` toggles optional parser features, such as directives, definition lists, and smart punctuation.
+
+See the [Sätteri documentation](https://satteri.bruits.org/) for the available plugins and parser features.
+
+### Using remark and rehype plugins
+
+Astro also supports the third-party [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugin ecosystems through the `unified()` processor. These plugins allow you to extend your Markdown with new capabilities, like [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and [styling your Markdown](/en/guides/styling/#markdown-styling).
+
+To use remark and rehype plugins, first install the `@astrojs/markdown-remark` package, which is no longer included in Astro by default:
+
+
+
+ ```shell
+ npm install @astrojs/markdown-remark
+ ```
+
+
+ ```shell
+ pnpm add @astrojs/markdown-remark
+ ```
+
+
+ ```shell
+ yarn add @astrojs/markdown-remark
+ ```
+
+
+
+Then, import `unified` from `@astrojs/markdown-remark` and pass your plugins to it through `markdown.processor`. We encourage you to browse [awesome-remark](https://github.com/remarkjs/awesome-remark) and [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for popular plugins! See each plugin's own README for specific installation instructions.
This example applies [`remark-toc`](https://github.com/remarkjs/remark-toc) and [`rehype-accessible-emojis`](https://www.npmjs.com/package/rehype-accessible-emojis) to Markdown files:
```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
export default defineConfig({
markdown: {
- remarkPlugins: [ [remarkToc, { heading: 'toc', maxDepth: 3 } ] ],
- rehypePlugins: [rehypeAccessibleEmojis],
+ processor: unified({
+ remarkPlugins: [[remarkToc, { heading: 'toc', maxDepth: 3 }]],
+ rehypePlugins: [rehypeAccessibleEmojis],
+ }),
},
});
```
### Customizing a plugin
-In order to customize a plugin, provide an options object after it in a nested array.
+In order to customize a remark or rehype plugin, provide an options object after it in a nested array.
The example below adds the [heading option to the `remarkToc` plugin](https://github.com/remarkjs/remark-toc#options) to change where the table of contents is placed, and the [`behavior` option to the `rehype-autolink-headings` plugin](https://github.com/rehypejs/rehype-autolink-headings#options) in order to add the anchor tag after the headline text.
```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
-export default {
+export default defineConfig({
markdown: {
- remarkPlugins: [ [remarkToc, { heading: "contents"} ] ],
- rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
+ processor: unified({
+ remarkPlugins: [[remarkToc, { heading: 'contents' }]],
+ rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
+ }),
},
-}
+});
```
### Modifying frontmatter programmatically
-You can add frontmatter properties to all of your Markdown and MDX files by using a [remark or rehype plugin](#markdown-plugins).
+Using the [remark/rehype processor](#using-remark-and-rehype-plugins), you can add frontmatter properties to all of your Markdown and MDX files with a remark or rehype plugin.
1. Append a `customProperty` to the `data.astro.frontmatter` property from your plugin's `file` argument:
@@ -249,27 +312,30 @@ You can add frontmatter properties to all of your Markdown and MDX files by usin
2. Apply this plugin to your `markdown` or `mdx` integration config:
- ```js title="astro.config.mjs" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';" "remarkPlugins: [exampleRemarkPlugin],"
+ ```js title="astro.config.mjs" "import { unified } from '@astrojs/markdown-remark';" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';"
import { defineConfig } from 'astro/config';
+ import { unified } from '@astrojs/markdown-remark';
import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
export default defineConfig({
markdown: {
- remarkPlugins: [exampleRemarkPlugin]
+ processor: unified({ remarkPlugins: [exampleRemarkPlugin] }),
},
});
```
or
- ```js title="astro.config.mjs" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';" "remarkPlugins: [exampleRemarkPlugin],"
+ ```js title="astro.config.mjs" "import { unified } from '@astrojs/markdown-remark';" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';"
import { defineConfig } from 'astro/config';
+ import mdx from '@astrojs/mdx';
+ import { unified } from '@astrojs/markdown-remark';
import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
export default defineConfig({
integrations: [
mdx({
- remarkPlugins: [exampleRemarkPlugin],
+ processor: unified({ remarkPlugins: [exampleRemarkPlugin] }),
}),
],
});
@@ -282,29 +348,26 @@ Now, every Markdown or MDX file will have `customProperty` in its frontmatter, m
### Extending Markdown config from MDX
-Astro's MDX integration 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.
+Astro's MDX integration will extend [your project's existing Markdown configuration](/en/reference/configuration-reference/#markdown-options) by default, including the [Markdown processor](#choosing-a-markdown-processor). To override individual options, you can specify their equivalent in your MDX configuration.
-The following example disables GitHub-Flavored Markdown and applies a different set of remark plugins for MDX files:
+The following example applies different processor options and a different syntax highlighter for `.mdx` files than for `.md` files:
```ts 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 } }),
})
]
});
@@ -313,18 +376,18 @@ export default defineConfig({
To avoid extending your Markdown config from MDX, set [the `extendMarkdownConfig` option](/en/guides/integrations-guide/mdx/#extendmarkdownconfig) (enabled by default) to `false`:
```ts 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: [remarkPlugin],
+ processor: satteri({ features: { directive: true } }),
},
integrations: [
mdx({
// Markdown config now ignored
extendMarkdownConfig: false,
- // No `remarkPlugins` applied
+ // Default `satteri()` processor used
})
]
});
diff --git a/src/content/docs/en/guides/migrate-to-astro/index.mdx b/src/content/docs/en/guides/migrate-to-astro/index.mdx
index 2705cb30b852e..9d76519fcbc61 100644
--- a/src/content/docs/en/guides/migrate-to-astro/index.mdx
+++ b/src/content/docs/en/guides/migrate-to-astro/index.mdx
@@ -27,7 +27,7 @@ Depending on your existing project, you may be able to use your existing:
- [CSS stylesheets or libraries](/en/guides/styling/) including Tailwind.
-- [Markdown/MDX files](/en/guides/markdown-content/), configured using your existing [remark and rehype plugins](/en/guides/markdown-content/#markdown-plugins).
+- [Markdown/MDX files](/en/guides/markdown-content/), with a [configurable Markdown processor](/en/guides/markdown-content/#markdown-plugins) and optional support for remark and rehype plugins.
- [Content from a CMS](/en/guides/cms/) through an integration or API.
diff --git a/src/content/docs/en/recipes/external-links.mdx b/src/content/docs/en/recipes/external-links.mdx
index 678869369b3d5..325319a27e813 100644
--- a/src/content/docs/en/recipes/external-links.mdx
+++ b/src/content/docs/en/recipes/external-links.mdx
@@ -16,45 +16,48 @@ Using a rehype plugin, you can identify and modify links in your Markdown files
## Recipe
-1. Install the `rehype-external-links` plugin.
+1. Install the `rehype-external-links` plugin, along with `@astrojs/markdown-remark`, which provides the remark/rehype Markdown processor.
```shell
- npm install rehype-external-links
+ npm install rehype-external-links @astrojs/markdown-remark
```
```shell
- pnpm add rehype-external-links
+ pnpm add rehype-external-links @astrojs/markdown-remark
```
```shell
- yarn add rehype-external-links
+ yarn add rehype-external-links @astrojs/markdown-remark
```
-2. Import the plugin into your `astro.config.mjs` file.
+2. Import the plugins into your `astro.config.mjs` file.
- Pass `rehypeExternalLinks` to the `rehypePlugins` array, along with an options object that includes a content property. Set this property's `type` to `text` if you want to add plain text to the end of the link. To add HTML to the end of the link instead, set the property `type` to `raw`.
+ Pass `rehypeExternalLinks` to the `rehypePlugins` array of the `unified()` processor, along with an options object that includes a content property. Set this property's `type` to `text` if you want to add plain text to the end of the link. To add HTML to the end of the link instead, set the property `type` to `raw`.
```ts
// ...
+ import { unified } from '@astrojs/markdown-remark';
import rehypeExternalLinks from 'rehype-external-links';
export default defineConfig({
// ...
markdown: {
- rehypePlugins: [
- [
- rehypeExternalLinks,
- {
- content: { type: 'text', value: ' 🔗' }
- }
+ processor: unified({
+ rehypePlugins: [
+ [
+ rehypeExternalLinks,
+ {
+ content: { type: 'text', value: ' 🔗' }
+ }
+ ],
],
- ]
+ }),
},
});
```
diff --git a/src/content/docs/en/recipes/modified-time.mdx b/src/content/docs/en/recipes/modified-time.mdx
index d54d2b9f1b03f..8257221c87d70 100644
--- a/src/content/docs/en/recipes/modified-time.mdx
+++ b/src/content/docs/en/recipes/modified-time.mdx
@@ -18,22 +18,22 @@ This recipe calculates time based on your repository’s Git history and may not
1. Install Helper Packages
- Install [`Day.js`](https://www.npmjs.com/package/dayjs) to modify and format times:
+ Install [`Day.js`](https://www.npmjs.com/package/dayjs) to modify and format times, and [`@astrojs/markdown-remark`](https://www.npmjs.com/package/@astrojs/markdown-remark) to run remark plugins through the `unified()` processor:
```shell
- npm install dayjs
+ npm install dayjs @astrojs/markdown-remark
```
```shell
- pnpm add dayjs
+ pnpm add dayjs @astrojs/markdown-remark
```
```shell
- yarn add dayjs
+ yarn add dayjs @astrojs/markdown-remark
```
@@ -76,11 +76,12 @@ This recipe calculates time based on your repository’s Git history and may not
```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
+ import { unified } from '@astrojs/markdown-remark';
import { remarkModifiedTime } from './remark-modified-time.mjs';
export default defineConfig({
markdown: {
- remarkPlugins: [remarkModifiedTime],
+ processor: unified({ remarkPlugins: [remarkModifiedTime] }),
},
});
```
diff --git a/src/content/docs/en/recipes/reading-time.mdx b/src/content/docs/en/recipes/reading-time.mdx
index bc0407c3b9c71..598bf84d06475 100644
--- a/src/content/docs/en/recipes/reading-time.mdx
+++ b/src/content/docs/en/recipes/reading-time.mdx
@@ -14,24 +14,25 @@ Create a [remark plugin](https://github.com/remarkjs/remark) which adds a readin
1. Install Helper Packages
- Install these two helper packages:
+ Install these helper packages:
- [`reading-time`](https://www.npmjs.com/package/reading-time) to calculate minutes read
- [`mdast-util-to-string`](https://www.npmjs.com/package/mdast-util-to-string) to extract all text from your markdown
+ - [`@astrojs/markdown-remark`](https://www.npmjs.com/package/@astrojs/markdown-remark) to run remark plugins through the `unified()` processor
```shell
- npm install reading-time mdast-util-to-string
+ npm install reading-time mdast-util-to-string @astrojs/markdown-remark
```
```shell
- pnpm add reading-time mdast-util-to-string
+ pnpm add reading-time mdast-util-to-string @astrojs/markdown-remark
```
```shell
- yarn add reading-time mdast-util-to-string
+ yarn add reading-time mdast-util-to-string @astrojs/markdown-remark
```
@@ -57,13 +58,14 @@ Create a [remark plugin](https://github.com/remarkjs/remark) which adds a readin
3. Add the plugin to your config:
- ```js title="astro.config.mjs" "import { remarkReadingTime } from './remark-reading-time.mjs';" "remarkPlugins: [remarkReadingTime],"
+ ```js title="astro.config.mjs" "import { unified } from '@astrojs/markdown-remark';" "import { remarkReadingTime } from './remark-reading-time.mjs';"
import { defineConfig } from 'astro/config';
+ import { unified } from '@astrojs/markdown-remark';
import { remarkReadingTime } from './remark-reading-time.mjs';
export default defineConfig({
markdown: {
- remarkPlugins: [remarkReadingTime],
+ processor: unified({ remarkPlugins: [remarkReadingTime] }),
},
});
```
diff --git a/src/content/docs/en/reference/content-loader-reference.mdx b/src/content/docs/en/reference/content-loader-reference.mdx
index e7a93a1bb0efd..b04f13944c847 100644
--- a/src/content/docs/en/reference/content-loader-reference.mdx
+++ b/src/content/docs/en/reference/content-loader-reference.mdx
@@ -1305,7 +1305,7 @@ Specifies the list of headings present in this file. Each heading is described b
**Type:** `Record`
-Describes the raw frontmatter, parsed from the file. This may include [programmatically injected data from remark plugins](/en/guides/markdown-content/#modifying-frontmatter-programmatically).
+Describes the raw frontmatter, parsed from the file. This may include [programmatically injected data from Markdown plugins](/en/guides/markdown-content/#modifying-frontmatter-programmatically).
## Live loader API
diff --git a/src/content/docs/en/reference/modules/astro-content.mdx b/src/content/docs/en/reference/modules/astro-content.mdx
index 3d604a783c191..3ef4bb60bf3e4 100644
--- a/src/content/docs/en/reference/modules/astro-content.mdx
+++ b/src/content/docs/en/reference/modules/astro-content.mdx
@@ -328,7 +328,7 @@ A function to compile a given entry for rendering. This returns the following pr
- `` - A component used to render the document's contents in an Astro file.
- `headings` - A generated list of headings, [mirroring Astro's `getHeadings()` utility](/en/guides/markdown-content/#available-properties) on Markdown and MDX imports.
-- `remarkPluginFrontmatter ` - The modified frontmatter object after any [remark or rehype plugins have been applied](/en/guides/markdown-content/#modifying-frontmatter-programmatically). Set to type `any`.
+- `remarkPluginFrontmatter ` - The modified frontmatter object after any [Markdown plugins have been applied](/en/guides/markdown-content/#modifying-frontmatter-programmatically). Set to type `any`.
```astro title="src/pages/blog/entry-1.astro"
---
diff --git a/src/content/docs/en/reference/programmatic-reference.mdx b/src/content/docs/en/reference/programmatic-reference.mdx
index c088a11b9ee89..51bb2b9f98405 100644
--- a/src/content/docs/en/reference/programmatic-reference.mdx
+++ b/src/content/docs/en/reference/programmatic-reference.mdx
@@ -190,7 +190,7 @@ The following utilities can be [imported from `astro/config`](/en/reference/modu
Takes an Astro configuration object and a partial object containing any set of valid Astro configuration options, and returns a valid Astro configuration combining the two values such that:
-- Arrays are concatenated (including integrations and remark plugins).
+- Arrays are concatenated (including integrations).
- Objects are merged recursively.
- Vite options are merged using [Vite's own `mergeConfig()` function](https://vite.dev/guide/api-javascript#mergeconfig) with the default `isRoot` flag.
- Options that can be provided as functions are wrapped into new functions that recursively merge the return values from both configurations with these same rules.
From 9fc3795c97b612d402c39e1e6b6b452279ef5dfe Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Fri, 22 May 2026 17:04:51 +0200
Subject: [PATCH 02/18] Update src/content/docs/en/guides/markdown-content.mdx
Co-authored-by: Armand Philippot
---
src/content/docs/en/guides/markdown-content.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index b8904c3f6d072..0c3c6fedbbb26 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -265,7 +265,7 @@ export default defineConfig({
});
```
-### Customizing a plugin
+### Customizing a remark or rehype plugin
In order to customize a remark or rehype plugin, provide an options object after it in a nested array.
From 3fa9a1a4c5bf96f12d40a735cba75be81687ae94 Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Fri, 22 May 2026 17:30:55 +0200
Subject: [PATCH 03/18] Update src/content/docs/en/guides/markdown-content.mdx
Co-authored-by: Armand Philippot
---
src/content/docs/en/guides/markdown-content.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index 0c3c6fedbbb26..6b033f418dfb3 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -312,7 +312,7 @@ Using the [remark/rehype processor](#using-remark-and-rehype-plugins), you can a
2. Apply this plugin to your `markdown` or `mdx` integration config:
- ```js title="astro.config.mjs" "import { unified } from '@astrojs/markdown-remark';" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';"
+ ```js title="astro.config.mjs" {2,3}
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
From 0160ad784a963b8f75d740f51810172f4fbe0dbd Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Fri, 22 May 2026 17:31:06 +0200
Subject: [PATCH 04/18] Update src/content/docs/en/recipes/reading-time.mdx
Co-authored-by: Armand Philippot
---
src/content/docs/en/recipes/reading-time.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/content/docs/en/recipes/reading-time.mdx b/src/content/docs/en/recipes/reading-time.mdx
index 598bf84d06475..fd462e36002f3 100644
--- a/src/content/docs/en/recipes/reading-time.mdx
+++ b/src/content/docs/en/recipes/reading-time.mdx
@@ -58,7 +58,7 @@ Create a [remark plugin](https://github.com/remarkjs/remark) which adds a readin
3. Add the plugin to your config:
- ```js title="astro.config.mjs" "import { unified } from '@astrojs/markdown-remark';" "import { remarkReadingTime } from './remark-reading-time.mjs';"
+ ```js title="astro.config.mjs" {2,3}
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import { remarkReadingTime } from './remark-reading-time.mjs';
From 543fb806a0ed992776d022dd45a3159a303ace72 Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Fri, 22 May 2026 17:32:44 +0200
Subject: [PATCH 05/18] Update src/content/docs/en/guides/markdown-content.mdx
Co-authored-by: Armand Philippot
---
src/content/docs/en/guides/markdown-content.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index 6b033f418dfb3..a7e28a9e4630b 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -326,7 +326,7 @@ Using the [remark/rehype processor](#using-remark-and-rehype-plugins), you can a
or
- ```js title="astro.config.mjs" "import { unified } from '@astrojs/markdown-remark';" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';"
+ ```js title="astro.config.mjs" {2,3}
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { unified } from '@astrojs/markdown-remark';
From a84b870dfc065faa47080186f5ceb779c49de864 Mon Sep 17 00:00:00 2001
From: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
Date: Sat, 23 May 2026 04:35:11 +0200
Subject: [PATCH 06/18] fix: rework for main
---
.../docs/en/guides/integrations-guide/mdx.mdx | 48 ++---
.../docs/en/guides/markdown-content.mdx | 169 +++++++-----------
.../docs/en/guides/migrate-to-astro/index.mdx | 2 +-
.../docs/en/recipes/external-links.mdx | 29 ++-
src/content/docs/en/recipes/modified-time.mdx | 11 +-
src/content/docs/en/recipes/reading-time.mdx | 14 +-
.../en/reference/content-loader-reference.mdx | 2 +-
.../en/reference/modules/astro-content.mdx | 2 +-
.../en/reference/programmatic-reference.mdx | 2 +-
9 files changed, 119 insertions(+), 160 deletions(-)
diff --git a/src/content/docs/en/guides/integrations-guide/mdx.mdx b/src/content/docs/en/guides/integrations-guide/mdx.mdx
index b300d24259ee4..6a22c44b8dfa2 100644
--- a/src/content/docs/en/guides/integrations-guide/mdx.mdx
+++ b/src/content/docs/en/guides/integrations-guide/mdx.mdx
@@ -262,11 +262,13 @@ You can configure how your MDX is rendered with the following options:
### Options inherited from Markdown config
-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).
+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).
```js title="astro.config.mjs"
-import { defineConfig, satteri } from 'astro/config';
+import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
+import remarkToc from 'remark-toc';
+import rehypePresetMinify from 'rehype-preset-minify';
export default defineConfig({
// ...
@@ -274,12 +276,19 @@ export default defineConfig({
mdx({
syntaxHighlight: 'shiki',
shikiConfig: { theme: 'dracula' },
- processor: satteri({ features: { gfm: false } }),
+ remarkPlugins: [remarkToc],
+ rehypePlugins: [rehypePresetMinify],
+ remarkRehype: { footnoteLabel: 'Footnotes' },
+ 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.
+:::
+
See the [Markdown Options reference](/en/reference/configuration-reference/#markdown-options) for a complete list of options.
### `processor`
@@ -291,20 +300,16 @@ export default defineConfig({
-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`.
+By default, `.mdx` files render through the same Markdown processor as your `.md` files — remark and rehype, unless you've opted in to [Sätteri](/en/guides/markdown-content/#using-the-sätteri-processor). Set `processor` to use a different processor — or the same processor with different options — for `.mdx` files only.
-Set `processor` to run `.mdx` files through a different processor, or the same processor with different options, than your `.md` files:
+For example, to keep remark/rehype for `.md` files while rendering `.mdx` files with Sätteri:
```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() }),
],
});
@@ -321,25 +326,28 @@ export default defineConfig({
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 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 and apply a different set of remark plugins for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:
```js title="astro.config.mjs"
-import { defineConfig, satteri } from 'astro/config';
+import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
// ...
markdown: {
- syntaxHighlight: 'shiki',
- processor: satteri({ features: { gfm: true } }),
+ syntaxHighlight: 'prism',
+ remarkPlugins: [remarkPlugin1],
+ gfm: true,
},
integrations: [
mdx({
// `syntaxHighlight` inherited from Markdown
- // Markdown `processor` ignored,
- // `.mdx` files use this processor instead.
- processor: satteri({ features: { gfm: false } }),
+ // Markdown `remarkPlugins` ignored,
+ // only `remarkPlugin2` applied.
+ remarkPlugins: [remarkPlugin2],
+ // `gfm` overridden to `false`
+ gfm: false,
}),
],
});
@@ -348,19 +356,19 @@ export default defineConfig({
You may also need to disable `markdown` config extension in MDX. For this, set `extendMarkdownConfig` to `false`:
```js title="astro.config.mjs"
-import { defineConfig, satteri } from 'astro/config';
+import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
// ...
markdown: {
- processor: satteri({ features: { directive: true } }),
+ remarkPlugins: [remarkPlugin1],
},
integrations: [
mdx({
// Markdown config now ignored
extendMarkdownConfig: false,
- // Default `satteri()` processor used
+ // No `remarkPlugins` applied
}),
],
});
@@ -388,7 +396,7 @@ We suggest [using AST Explorer](https://astexplorer.net/) to play with estree ou
-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 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 disabled by default. To enable MDX optimization, add the following to your MDX integration configuration:
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index a7e28a9e4630b..b7637f1bdefde 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -10,7 +10,6 @@ import { FileTree } from '@astrojs/starlight/components';
import RecipeLinks from "~/components/RecipeLinks.astro";
import ReadMore from '~/components/ReadMore.astro';
import { Steps } from '@astrojs/starlight/components';
-import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
[Markdown](https://daringfireball.net/projects/markdown/) is commonly used to author text-heavy content like blog posts and documentation. Astro includes built-in support for Markdown files that can also include [frontmatter YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) (or [TOML](https://toml.io)) to define custom properties such as a title, description, and tags.
@@ -72,7 +71,7 @@ const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }));
When fetching data from your collections with the helper functions `getCollection()` or `getEntry()`, your Markdown's frontmatter properties are available on a `data` object (e.g. `post.data.title`). Additionally, `body` contains the raw, uncompiled body content as a string.
-The [`render()`](/en/reference/modules/astro-content/#render) function returns your Markdown body content, a generated list of headings, as well as a modified frontmatter object after any [Markdown plugins](#markdown-plugins) have been applied.
+The [`render()`](/en/reference/modules/astro-content/#render) function returns your Markdown body content, a generated list of headings, as well as a modified frontmatter object after any remark or rehype plugins have been applied.
Read more about [using content returned by a collections query](/en/guides/content-collections/#using-content-in-astro-templates).
@@ -159,138 +158,76 @@ Astro generates heading `id`s based on `github-slugger`. You can find more examp
Astro injects an `id` attribute into all heading elements (`` to ``) in Markdown and MDX files. You can retrieve this data from the `getHeadings()` utility available as a [Markdown exported property](#available-properties) from an imported file, or from the `render()` function when [using Markdown returned from a content collections query](#markdown-from-content-collections-queries).
-You can customize these heading IDs with a [Markdown processor](#choosing-a-markdown-processor) plugin that injects `id` attributes (e.g. `rehype-slug`). Your custom IDs, instead of Astro's defaults, will be reflected in the HTML output and the items returned by `getHeadings()`.
+You can customize these heading IDs by adding a rehype plugin that injects `id` attributes (e.g. `rehype-slug`). Your custom IDs, instead of Astro's defaults, will be reflected in the HTML output and the items returned by `getHeadings()`.
-When using the [remark/rehype processor](#using-remark-and-rehype-plugins), Astro injects `id` attributes after your rehype plugins have run. If one of your custom rehype plugins needs to access the IDs injected by Astro, you can import and use Astro’s `rehypeHeadingIds` plugin directly. Be sure to add `rehypeHeadingIds` before any plugins that rely on it:
+By default, Astro injects `id` attributes after your rehype plugins have run. If one of your custom rehype plugins needs to access the IDs injected by Astro, you can import and use Astro’s `rehypeHeadingIds` plugin directly. Be sure to add `rehypeHeadingIds` before any plugins that rely on it:
-```js title="astro.config.mjs" ins={2-3, 9}
+```js title="astro.config.mjs" ins={2, 8}
import { defineConfig } from 'astro/config';
-import { unified, rehypeHeadingIds } from '@astrojs/markdown-remark';
+import { rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';
export default defineConfig({
markdown: {
- processor: unified({
- rehypePlugins: [
- rehypeHeadingIds,
- otherPluginThatReliesOnHeadingIDs,
- ],
- }),
+ rehypePlugins: [
+ rehypeHeadingIds,
+ otherPluginThatReliesOnHeadingIDs,
+ ],
},
});
```
-## Markdown plugins
-
-Astro renders Markdown using a configurable **Markdown processor**. By default, this is [Sätteri](https://satteri.bruits.org/), a fast, native Markdown and MDX compiler.
-
-The default processor applies [GitHub-Flavored Markdown](https://github.github.com/gfm/) and [SmartyPants](https://daringfireball.net/projects/smartypants/) automatically. This brings some niceties like generating clickable links from text, and formatting for quotations and em-dashes.
+## Markdown Plugins
-You can extend Markdown processing with plugins, enable additional parser features, or switch to a different processor entirely. See the full list of [Markdown configuration options](/en/reference/configuration-reference/#markdown-options).
+Markdown support in Astro is powered by [remark](https://remark.js.org/), a powerful parsing and processing tool with an active ecosystem. Other Markdown parsers like Pandoc and markdown-it are not currently supported.
-### Choosing a Markdown processor
+Astro applies the [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) and [SmartyPants](https://github.com/silvenon/remark-smartypants) plugins by default. This brings some niceties like generating clickable links from text, and formatting for [quotations and em-dashes](https://daringfireball.net/projects/smartypants/).
-The [`markdown.processor` option](/en/reference/configuration-reference/#markdownprocessor) controls which engine renders your `.md` and `.mdx` files. Astro provides two built-in processors:
+You can customize how remark parses your Markdown in `astro.config.mjs`. See the full list of [Markdown configuration options](/en/reference/configuration-reference/#markdown-options).
-- **`satteri()`** (default): the native [Sätteri](https://satteri.bruits.org/) pipeline. Accepts Sätteri plugins and optional parser features.
-- **`unified()`**: the [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype) pipeline, for projects that depend on their plugin ecosystems. Provided by the separate `@astrojs/markdown-remark` package.
+### Adding remark and rehype plugins
+Astro supports adding third-party [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugins for Markdown. These plugins allow you to extend your Markdown with new capabilities, like [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and [styling your Markdown](/en/guides/styling/#markdown-styling).
-### Adding Sätteri plugins and features
-
-The default [`satteri()` processor](#choosing-a-markdown-processor) accepts plugins and parser feature toggles. Import `satteri` from `astro/config`, configure it, and pass it to `markdown.processor`:
-
-```js title="astro.config.mjs"
-import { defineConfig, satteri } from 'astro/config';
-import myMdastPlugin from './my-mdast-plugin.js';
-import myHastPlugin from './my-hast-plugin.js';
-
-export default defineConfig({
- markdown: {
- processor: satteri({
- mdastPlugins: [myMdastPlugin],
- hastPlugins: [myHastPlugin],
- features: { directive: true, definitionList: true },
- }),
- },
-});
-```
-
-- `mdastPlugins` and `hastPlugins` add Sätteri plugins that transform the Markdown (MDAST) or HTML (HAST) syntax tree.
-- `features` toggles optional parser features, such as directives, definition lists, and smart punctuation.
-
-See the [Sätteri documentation](https://satteri.bruits.org/) for the available plugins and parser features.
-
-### Using remark and rehype plugins
-
-Astro also supports the third-party [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugin ecosystems through the `unified()` processor. These plugins allow you to extend your Markdown with new capabilities, like [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and [styling your Markdown](/en/guides/styling/#markdown-styling).
-
-To use remark and rehype plugins, first install the `@astrojs/markdown-remark` package, which is no longer included in Astro by default:
-
-
-
- ```shell
- npm install @astrojs/markdown-remark
- ```
-
-
- ```shell
- pnpm add @astrojs/markdown-remark
- ```
-
-
- ```shell
- yarn add @astrojs/markdown-remark
- ```
-
-
-
-Then, import `unified` from `@astrojs/markdown-remark` and pass your plugins to it through `markdown.processor`. We encourage you to browse [awesome-remark](https://github.com/remarkjs/awesome-remark) and [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for popular plugins! See each plugin's own README for specific installation instructions.
+We encourage you to browse [awesome-remark](https://github.com/remarkjs/awesome-remark) and [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for popular plugins! See each plugin's own README for specific installation instructions.
This example applies [`remark-toc`](https://github.com/remarkjs/remark-toc) and [`rehype-accessible-emojis`](https://www.npmjs.com/package/rehype-accessible-emojis) to Markdown files:
```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
-import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
export default defineConfig({
markdown: {
- processor: unified({
- remarkPlugins: [[remarkToc, { heading: 'toc', maxDepth: 3 }]],
- rehypePlugins: [rehypeAccessibleEmojis],
- }),
+ remarkPlugins: [ [remarkToc, { heading: 'toc', maxDepth: 3 } ] ],
+ rehypePlugins: [rehypeAccessibleEmojis],
},
});
```
-### Customizing a remark or rehype plugin
+### Customizing a plugin
-In order to customize a remark or rehype plugin, provide an options object after it in a nested array.
+In order to customize a plugin, provide an options object after it in a nested array.
The example below adds the [heading option to the `remarkToc` plugin](https://github.com/remarkjs/remark-toc#options) to change where the table of contents is placed, and the [`behavior` option to the `rehype-autolink-headings` plugin](https://github.com/rehypejs/rehype-autolink-headings#options) in order to add the anchor tag after the headline text.
```js title="astro.config.mjs"
-import { defineConfig } from 'astro/config';
-import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
-export default defineConfig({
+export default {
markdown: {
- processor: unified({
- remarkPlugins: [[remarkToc, { heading: 'contents' }]],
- rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
- }),
+ remarkPlugins: [ [remarkToc, { heading: "contents"} ] ],
+ rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
},
-});
+}
```
### Modifying frontmatter programmatically
-Using the [remark/rehype processor](#using-remark-and-rehype-plugins), you can add frontmatter properties to all of your Markdown and MDX files with a remark or rehype plugin.
+You can add frontmatter properties to all of your Markdown and MDX files by using a [remark or rehype plugin](#markdown-plugins).
1. Append a `customProperty` to the `data.astro.frontmatter` property from your plugin's `file` argument:
@@ -312,30 +249,27 @@ Using the [remark/rehype processor](#using-remark-and-rehype-plugins), you can a
2. Apply this plugin to your `markdown` or `mdx` integration config:
- ```js title="astro.config.mjs" {2,3}
+ ```js title="astro.config.mjs" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';" "remarkPlugins: [exampleRemarkPlugin],"
import { defineConfig } from 'astro/config';
- import { unified } from '@astrojs/markdown-remark';
import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
export default defineConfig({
markdown: {
- processor: unified({ remarkPlugins: [exampleRemarkPlugin] }),
+ remarkPlugins: [exampleRemarkPlugin]
},
});
```
or
- ```js title="astro.config.mjs" {2,3}
+ ```js title="astro.config.mjs" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';" "remarkPlugins: [exampleRemarkPlugin],"
import { defineConfig } from 'astro/config';
- import mdx from '@astrojs/mdx';
- import { unified } from '@astrojs/markdown-remark';
import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
export default defineConfig({
integrations: [
mdx({
- processor: unified({ remarkPlugins: [exampleRemarkPlugin] }),
+ remarkPlugins: [exampleRemarkPlugin],
}),
],
});
@@ -348,26 +282,29 @@ Now, every Markdown or MDX file will have `customProperty` in its frontmatter, m
### Extending Markdown config from MDX
-Astro's MDX integration will extend [your project's existing Markdown configuration](/en/reference/configuration-reference/#markdown-options) by default, including the [Markdown processor](#choosing-a-markdown-processor). To override individual options, you can specify their equivalent in your MDX configuration.
+Astro's MDX integration 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.
-The following example applies different processor options and a different syntax highlighter for `.mdx` files than for `.md` files:
+The following example disables GitHub-Flavored Markdown and applies a different set of remark plugins for MDX files:
```ts title="astro.config.mjs"
-import { defineConfig, satteri } from 'astro/config';
+import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
- syntaxHighlight: 'shiki',
- processor: satteri({ features: { gfm: true } }),
+ syntaxHighlight: 'prism',
+ remarkPlugins: [remarkPlugin1],
+ gfm: true,
},
integrations: [
mdx({
// `syntaxHighlight` inherited from Markdown
- // Markdown `processor` ignored,
- // `.mdx` files use this processor instead.
- processor: satteri({ features: { gfm: false } }),
+ // Markdown `remarkPlugins` ignored,
+ // only `remarkPlugin2` applied.
+ remarkPlugins: [remarkPlugin2],
+ // `gfm` overridden to `false`
+ gfm: false,
})
]
});
@@ -376,23 +313,43 @@ export default defineConfig({
To avoid extending your Markdown config from MDX, set [the `extendMarkdownConfig` option](/en/guides/integrations-guide/mdx/#extendmarkdownconfig) (enabled by default) to `false`:
```ts title="astro.config.mjs"
-import { defineConfig, satteri } from 'astro/config';
+import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
- processor: satteri({ features: { directive: true } }),
+ remarkPlugins: [remarkPlugin],
},
integrations: [
mdx({
// Markdown config now ignored
extendMarkdownConfig: false,
- // Default `satteri()` processor used
+ // No `remarkPlugins` applied
})
]
});
```
+## Using the Sätteri processor
+
+By default, Astro renders Markdown with [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype). You can opt in to [Sätteri](https://satteri.bruits.org/), a native Markdown and MDX compiler, with the [`markdown.processor`](/en/reference/configuration-reference/#markdownprocessor) option:
+
+```js title="astro.config.mjs"
+import { defineConfig, satteri } from 'astro/config';
+
+export default defineConfig({
+ markdown: {
+ processor: satteri({
+ features: { directive: true, definitionList: true },
+ }),
+ },
+});
+```
+
+The Sätteri processor accepts its own plugins through `mdastPlugins` and `hastPlugins`, and toggles optional parser features through `features`. See the [Sätteri documentation](https://satteri.bruits.org/) for the available plugins and features.
+
+Switching processors replaces remark and rehype for both `.md` and `.mdx` files. Any `remarkPlugins`/`rehypePlugins` set in your config will not apply. To use Sätteri only for `.mdx` files, set the [`processor` option on the MDX integration](/en/guides/integrations-guide/mdx/#processor) instead.
+
## Individual Markdown pages
:::tip
diff --git a/src/content/docs/en/guides/migrate-to-astro/index.mdx b/src/content/docs/en/guides/migrate-to-astro/index.mdx
index 9d76519fcbc61..2705cb30b852e 100644
--- a/src/content/docs/en/guides/migrate-to-astro/index.mdx
+++ b/src/content/docs/en/guides/migrate-to-astro/index.mdx
@@ -27,7 +27,7 @@ Depending on your existing project, you may be able to use your existing:
- [CSS stylesheets or libraries](/en/guides/styling/) including Tailwind.
-- [Markdown/MDX files](/en/guides/markdown-content/), with a [configurable Markdown processor](/en/guides/markdown-content/#markdown-plugins) and optional support for remark and rehype plugins.
+- [Markdown/MDX files](/en/guides/markdown-content/), configured using your existing [remark and rehype plugins](/en/guides/markdown-content/#markdown-plugins).
- [Content from a CMS](/en/guides/cms/) through an integration or API.
diff --git a/src/content/docs/en/recipes/external-links.mdx b/src/content/docs/en/recipes/external-links.mdx
index 325319a27e813..678869369b3d5 100644
--- a/src/content/docs/en/recipes/external-links.mdx
+++ b/src/content/docs/en/recipes/external-links.mdx
@@ -16,48 +16,45 @@ Using a rehype plugin, you can identify and modify links in your Markdown files
## Recipe
-1. Install the `rehype-external-links` plugin, along with `@astrojs/markdown-remark`, which provides the remark/rehype Markdown processor.
+1. Install the `rehype-external-links` plugin.
```shell
- npm install rehype-external-links @astrojs/markdown-remark
+ npm install rehype-external-links
```
```shell
- pnpm add rehype-external-links @astrojs/markdown-remark
+ pnpm add rehype-external-links
```
```shell
- yarn add rehype-external-links @astrojs/markdown-remark
+ yarn add rehype-external-links
```
-2. Import the plugins into your `astro.config.mjs` file.
+2. Import the plugin into your `astro.config.mjs` file.
- Pass `rehypeExternalLinks` to the `rehypePlugins` array of the `unified()` processor, along with an options object that includes a content property. Set this property's `type` to `text` if you want to add plain text to the end of the link. To add HTML to the end of the link instead, set the property `type` to `raw`.
+ Pass `rehypeExternalLinks` to the `rehypePlugins` array, along with an options object that includes a content property. Set this property's `type` to `text` if you want to add plain text to the end of the link. To add HTML to the end of the link instead, set the property `type` to `raw`.
```ts
// ...
- import { unified } from '@astrojs/markdown-remark';
import rehypeExternalLinks from 'rehype-external-links';
export default defineConfig({
// ...
markdown: {
- processor: unified({
- rehypePlugins: [
- [
- rehypeExternalLinks,
- {
- content: { type: 'text', value: ' 🔗' }
- }
- ],
+ rehypePlugins: [
+ [
+ rehypeExternalLinks,
+ {
+ content: { type: 'text', value: ' 🔗' }
+ }
],
- }),
+ ]
},
});
```
diff --git a/src/content/docs/en/recipes/modified-time.mdx b/src/content/docs/en/recipes/modified-time.mdx
index 8257221c87d70..d54d2b9f1b03f 100644
--- a/src/content/docs/en/recipes/modified-time.mdx
+++ b/src/content/docs/en/recipes/modified-time.mdx
@@ -18,22 +18,22 @@ This recipe calculates time based on your repository’s Git history and may not
1. Install Helper Packages
- Install [`Day.js`](https://www.npmjs.com/package/dayjs) to modify and format times, and [`@astrojs/markdown-remark`](https://www.npmjs.com/package/@astrojs/markdown-remark) to run remark plugins through the `unified()` processor:
+ Install [`Day.js`](https://www.npmjs.com/package/dayjs) to modify and format times:
```shell
- npm install dayjs @astrojs/markdown-remark
+ npm install dayjs
```
```shell
- pnpm add dayjs @astrojs/markdown-remark
+ pnpm add dayjs
```
```shell
- yarn add dayjs @astrojs/markdown-remark
+ yarn add dayjs
```
@@ -76,12 +76,11 @@ This recipe calculates time based on your repository’s Git history and may not
```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
- import { unified } from '@astrojs/markdown-remark';
import { remarkModifiedTime } from './remark-modified-time.mjs';
export default defineConfig({
markdown: {
- processor: unified({ remarkPlugins: [remarkModifiedTime] }),
+ remarkPlugins: [remarkModifiedTime],
},
});
```
diff --git a/src/content/docs/en/recipes/reading-time.mdx b/src/content/docs/en/recipes/reading-time.mdx
index fd462e36002f3..bc0407c3b9c71 100644
--- a/src/content/docs/en/recipes/reading-time.mdx
+++ b/src/content/docs/en/recipes/reading-time.mdx
@@ -14,25 +14,24 @@ Create a [remark plugin](https://github.com/remarkjs/remark) which adds a readin
1. Install Helper Packages
- Install these helper packages:
+ Install these two helper packages:
- [`reading-time`](https://www.npmjs.com/package/reading-time) to calculate minutes read
- [`mdast-util-to-string`](https://www.npmjs.com/package/mdast-util-to-string) to extract all text from your markdown
- - [`@astrojs/markdown-remark`](https://www.npmjs.com/package/@astrojs/markdown-remark) to run remark plugins through the `unified()` processor
```shell
- npm install reading-time mdast-util-to-string @astrojs/markdown-remark
+ npm install reading-time mdast-util-to-string
```
```shell
- pnpm add reading-time mdast-util-to-string @astrojs/markdown-remark
+ pnpm add reading-time mdast-util-to-string
```
```shell
- yarn add reading-time mdast-util-to-string @astrojs/markdown-remark
+ yarn add reading-time mdast-util-to-string
```
@@ -58,14 +57,13 @@ Create a [remark plugin](https://github.com/remarkjs/remark) which adds a readin
3. Add the plugin to your config:
- ```js title="astro.config.mjs" {2,3}
+ ```js title="astro.config.mjs" "import { remarkReadingTime } from './remark-reading-time.mjs';" "remarkPlugins: [remarkReadingTime],"
import { defineConfig } from 'astro/config';
- import { unified } from '@astrojs/markdown-remark';
import { remarkReadingTime } from './remark-reading-time.mjs';
export default defineConfig({
markdown: {
- processor: unified({ remarkPlugins: [remarkReadingTime] }),
+ remarkPlugins: [remarkReadingTime],
},
});
```
diff --git a/src/content/docs/en/reference/content-loader-reference.mdx b/src/content/docs/en/reference/content-loader-reference.mdx
index b04f13944c847..e7a93a1bb0efd 100644
--- a/src/content/docs/en/reference/content-loader-reference.mdx
+++ b/src/content/docs/en/reference/content-loader-reference.mdx
@@ -1305,7 +1305,7 @@ Specifies the list of headings present in this file. Each heading is described b
**Type:** `Record`
-Describes the raw frontmatter, parsed from the file. This may include [programmatically injected data from Markdown plugins](/en/guides/markdown-content/#modifying-frontmatter-programmatically).
+Describes the raw frontmatter, parsed from the file. This may include [programmatically injected data from remark plugins](/en/guides/markdown-content/#modifying-frontmatter-programmatically).
## Live loader API
diff --git a/src/content/docs/en/reference/modules/astro-content.mdx b/src/content/docs/en/reference/modules/astro-content.mdx
index 3ef4bb60bf3e4..3d604a783c191 100644
--- a/src/content/docs/en/reference/modules/astro-content.mdx
+++ b/src/content/docs/en/reference/modules/astro-content.mdx
@@ -328,7 +328,7 @@ A function to compile a given entry for rendering. This returns the following pr
- `` - A component used to render the document's contents in an Astro file.
- `headings` - A generated list of headings, [mirroring Astro's `getHeadings()` utility](/en/guides/markdown-content/#available-properties) on Markdown and MDX imports.
-- `remarkPluginFrontmatter ` - The modified frontmatter object after any [Markdown plugins have been applied](/en/guides/markdown-content/#modifying-frontmatter-programmatically). Set to type `any`.
+- `remarkPluginFrontmatter ` - The modified frontmatter object after any [remark or rehype plugins have been applied](/en/guides/markdown-content/#modifying-frontmatter-programmatically). Set to type `any`.
```astro title="src/pages/blog/entry-1.astro"
---
diff --git a/src/content/docs/en/reference/programmatic-reference.mdx b/src/content/docs/en/reference/programmatic-reference.mdx
index 51bb2b9f98405..c088a11b9ee89 100644
--- a/src/content/docs/en/reference/programmatic-reference.mdx
+++ b/src/content/docs/en/reference/programmatic-reference.mdx
@@ -190,7 +190,7 @@ The following utilities can be [imported from `astro/config`](/en/reference/modu
Takes an Astro configuration object and a partial object containing any set of valid Astro configuration options, and returns a valid Astro configuration combining the two values such that:
-- Arrays are concatenated (including integrations).
+- Arrays are concatenated (including integrations and remark plugins).
- Objects are merged recursively.
- Vite options are merged using [Vite's own `mergeConfig()` function](https://vite.dev/guide/api-javascript#mergeconfig) with the default `isRoot` flag.
- Options that can be provided as functions are wrapped into new functions that recursively merge the return values from both configurations with these same rules.
From c1ffee2fa6dd06fddb5cf84d3b59a98a5499699d Mon Sep 17 00:00:00 2001
From: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
Date: Sat, 23 May 2026 05:00:27 +0200
Subject: [PATCH 07/18] fix: bring back changes
---
.../docs/en/guides/integrations-guide/mdx.mdx | 41 +++---
.../docs/en/guides/markdown-content.mdx | 136 ++++++++++--------
.../docs/en/guides/migrate-to-astro/index.mdx | 2 +-
.../en/reference/content-loader-reference.mdx | 2 +-
.../en/reference/modules/astro-content.mdx | 2 +-
.../en/reference/programmatic-reference.mdx | 2 +-
6 files changed, 100 insertions(+), 85 deletions(-)
diff --git a/src/content/docs/en/guides/integrations-guide/mdx.mdx b/src/content/docs/en/guides/integrations-guide/mdx.mdx
index 6a22c44b8dfa2..ab97eb085ef45 100644
--- a/src/content/docs/en/guides/integrations-guide/mdx.mdx
+++ b/src/content/docs/en/guides/integrations-guide/mdx.mdx
@@ -262,10 +262,11 @@ You can configure how your MDX is rendered with the following options:
### 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';
@@ -276,19 +277,16 @@ export default defineConfig({
mdx({
syntaxHighlight: 'shiki',
shikiConfig: { theme: 'dracula' },
- remarkPlugins: [remarkToc],
- rehypePlugins: [rehypePresetMinify],
- remarkRehype: { footnoteLabel: 'Footnotes' },
- gfm: false,
+ processor: unified({
+ remarkPlugins: [remarkToc],
+ rehypePlugins: [rehypePresetMinify],
+ remarkRehype: { footnoteLabel: 'Footnotes' },
+ }),
}),
],
});
```
-:::caution
-MDX does not support passing remark and rehype plugins as a string. You should install, import, and apply the plugin function instead.
-:::
-
See the [Markdown Options reference](/en/reference/configuration-reference/#markdown-options) for a complete list of options.
### `processor`
@@ -300,9 +298,9 @@ MDX does not support passing remark and rehype plugins as a string. You should i
-By default, `.mdx` files render through the same Markdown processor as your `.md` files — remark and rehype, unless you've opted in to [Sätteri](/en/guides/markdown-content/#using-the-sätteri-processor). Set `processor` to use a different processor — or the same processor with different options — for `.mdx` files only.
+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 remark/rehype for `.md` files while rendering `.mdx` files with Sätteri:
+For example, to keep the default remark/rehype processor for `.md` files while rendering `.mdx` files with [Sätteri](https://satteri.bruits.org/):
```js title="astro.config.mjs"
import { defineConfig, satteri } from 'astro/config';
@@ -326,28 +324,26 @@ export default defineConfig({
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,
+ syntaxHighlight: 'shiki',
+ processor: unified({ remarkPlugins: [remarkPlugin1] }),
},
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: unified({ remarkPlugins: [remarkPlugin2] }),
}),
],
});
@@ -357,18 +353,19 @@ You may also need to disable `markdown` config extension in MDX. For this, set `
```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
}),
],
});
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index b7637f1bdefde..8e3cbc0b72746 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -158,76 +158,112 @@ Astro generates heading `id`s based on `github-slugger`. You can find more examp
Astro injects an `id` attribute into all heading elements (`` to ``) in Markdown and MDX files. You can retrieve this data from the `getHeadings()` utility available as a [Markdown exported property](#available-properties) from an imported file, or from the `render()` function when [using Markdown returned from a content collections query](#markdown-from-content-collections-queries).
-You can customize these heading IDs by adding a rehype plugin that injects `id` attributes (e.g. `rehype-slug`). Your custom IDs, instead of Astro's defaults, will be reflected in the HTML output and the items returned by `getHeadings()`.
+You can customize these heading IDs with a [Markdown processor](#choosing-a-markdown-processor) plugin that injects `id` attributes (e.g. `rehype-slug`). Your custom IDs, instead of Astro's defaults, will be reflected in the HTML output and the items returned by `getHeadings()`.
-By default, Astro injects `id` attributes after your rehype plugins have run. If one of your custom rehype plugins needs to access the IDs injected by Astro, you can import and use Astro’s `rehypeHeadingIds` plugin directly. Be sure to add `rehypeHeadingIds` before any plugins that rely on it:
+When using the default [remark/rehype processor](#using-remark-and-rehype-plugins), Astro injects `id` attributes after your rehype plugins have run. If one of your custom rehype plugins needs to access the IDs injected by Astro, you can import and use Astro’s `rehypeHeadingIds` plugin directly. Be sure to add `rehypeHeadingIds` before any plugins that rely on it:
-```js title="astro.config.mjs" ins={2, 8}
+```js title="astro.config.mjs" ins={2-3, 9}
import { defineConfig } from 'astro/config';
-import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+import { unified, rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';
export default defineConfig({
markdown: {
- rehypePlugins: [
- rehypeHeadingIds,
- otherPluginThatReliesOnHeadingIDs,
- ],
+ processor: unified({
+ rehypePlugins: [
+ rehypeHeadingIds,
+ otherPluginThatReliesOnHeadingIDs,
+ ],
+ }),
},
});
```
## Markdown Plugins
-Markdown support in Astro is powered by [remark](https://remark.js.org/), a powerful parsing and processing tool with an active ecosystem. Other Markdown parsers like Pandoc and markdown-it are not currently supported.
+Astro renders Markdown using a configurable **Markdown processor**. By default, this is the [unified](https://unifiedjs.com/) pipeline of [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype), with an active plugin ecosystem.
+
+Astro applies [GitHub-Flavored Markdown](https://github.github.com/gfm/) and [SmartyPants](https://daringfireball.net/projects/smartypants/) automatically. This brings some niceties like generating clickable links from text, and formatting for quotations and em-dashes.
-Astro applies the [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) and [SmartyPants](https://github.com/silvenon/remark-smartypants) plugins by default. This brings some niceties like generating clickable links from text, and formatting for [quotations and em-dashes](https://daringfireball.net/projects/smartypants/).
+You can extend Markdown processing with plugins, enable additional parser features, or [switch to a different processor entirely](#switching-to-the-sätteri-processor). See the full list of [Markdown configuration options](/en/reference/configuration-reference/#markdown-options).
-You can customize how remark parses your Markdown in `astro.config.mjs`. See the full list of [Markdown configuration options](/en/reference/configuration-reference/#markdown-options).
+### Choosing a Markdown processor
-### Adding remark and rehype plugins
+The [`markdown.processor` option](/en/reference/configuration-reference/#markdownprocessor) controls which engine renders your `.md` and `.mdx` files. Astro provides two built-in processors:
-Astro supports adding third-party [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugins for Markdown. These plugins allow you to extend your Markdown with new capabilities, like [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and [styling your Markdown](/en/guides/styling/#markdown-styling).
+- **`unified()`** (default): the [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype) pipeline, with its large plugin ecosystem. Provided by `@astrojs/markdown-remark`, which ships with Astro.
+- **`satteri()`**: the native [Sätteri](https://satteri.bruits.org/) pipeline — a faster Markdown and MDX compiler with its own plugin model.
+
+### Using remark and rehype plugins
+
+The default `unified()` processor accepts third-party [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugins. These plugins allow you to extend your Markdown with new capabilities, like [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and [styling your Markdown](/en/guides/styling/#markdown-styling).
We encourage you to browse [awesome-remark](https://github.com/remarkjs/awesome-remark) and [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for popular plugins! See each plugin's own README for specific installation instructions.
-This example applies [`remark-toc`](https://github.com/remarkjs/remark-toc) and [`rehype-accessible-emojis`](https://www.npmjs.com/package/rehype-accessible-emojis) to Markdown files:
+Import `unified` from `@astrojs/markdown-remark` and pass your plugins to it through `markdown.processor`. This example applies [`remark-toc`](https://github.com/remarkjs/remark-toc) and [`rehype-accessible-emojis`](https://www.npmjs.com/package/rehype-accessible-emojis) to Markdown files:
```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
export default defineConfig({
markdown: {
- remarkPlugins: [ [remarkToc, { heading: 'toc', maxDepth: 3 } ] ],
- rehypePlugins: [rehypeAccessibleEmojis],
+ processor: unified({
+ remarkPlugins: [[remarkToc, { heading: 'toc', maxDepth: 3 }]],
+ rehypePlugins: [rehypeAccessibleEmojis],
+ }),
},
});
```
-### Customizing a plugin
+### Customizing a remark or rehype plugin
In order to customize a plugin, provide an options object after it in a nested array.
The example below adds the [heading option to the `remarkToc` plugin](https://github.com/remarkjs/remark-toc#options) to change where the table of contents is placed, and the [`behavior` option to the `rehype-autolink-headings` plugin](https://github.com/rehypejs/rehype-autolink-headings#options) in order to add the anchor tag after the headline text.
```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
-export default {
+export default defineConfig({
markdown: {
- remarkPlugins: [ [remarkToc, { heading: "contents"} ] ],
- rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
+ processor: unified({
+ remarkPlugins: [[remarkToc, { heading: 'contents' }]],
+ rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
+ }),
},
-}
+});
```
+### Switching to the Sätteri processor
+
+To use [Sätteri](https://satteri.bruits.org/) instead of remark and rehype, import `satteri` from `astro/config` and pass it to `markdown.processor`:
+
+```js title="astro.config.mjs"
+import { defineConfig, satteri } from 'astro/config';
+
+export default defineConfig({
+ markdown: {
+ processor: satteri({
+ features: { directive: true, definitionList: true },
+ }),
+ },
+});
+```
+
+The Sätteri processor accepts its own plugins through `mdastPlugins` and `hastPlugins`, and toggles optional parser features through `features`. See the [Sätteri documentation](https://satteri.bruits.org/) for the available plugins and features.
+
+Switching processors replaces remark and rehype for both `.md` and `.mdx` files. Any remark or rehype plugins in your config will not apply. To use Sätteri only for `.mdx` files, set the [`processor` option on the MDX integration](/en/guides/integrations-guide/mdx/#processor) instead.
+
### Modifying frontmatter programmatically
-You can add frontmatter properties to all of your Markdown and MDX files by using a [remark or rehype plugin](#markdown-plugins).
+When using the [remark/rehype processor](#using-remark-and-rehype-plugins), you can add frontmatter properties to all of your Markdown and MDX files with a remark or rehype plugin.
1. Append a `customProperty` to the `data.astro.frontmatter` property from your plugin's `file` argument:
@@ -247,29 +283,32 @@ You can add frontmatter properties to all of your Markdown and MDX files by usin
`data.astro.frontmatter` contains all properties from a given Markdown or MDX document. This allows you to modify existing frontmatter properties, or compute new properties from this existing frontmatter.
:::
-2. Apply this plugin to your `markdown` or `mdx` integration config:
+2. Apply this plugin to your `markdown` or `mdx` integration config:
- ```js title="astro.config.mjs" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';" "remarkPlugins: [exampleRemarkPlugin],"
+ ```js title="astro.config.mjs" {2,3}
import { defineConfig } from 'astro/config';
+ import { unified } from '@astrojs/markdown-remark';
import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
export default defineConfig({
markdown: {
- remarkPlugins: [exampleRemarkPlugin]
+ processor: unified({ remarkPlugins: [exampleRemarkPlugin] }),
},
});
```
or
- ```js title="astro.config.mjs" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';" "remarkPlugins: [exampleRemarkPlugin],"
+ ```js title="astro.config.mjs" {2,3}
import { defineConfig } from 'astro/config';
+ import mdx from '@astrojs/mdx';
+ import { unified } from '@astrojs/markdown-remark';
import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
export default defineConfig({
integrations: [
mdx({
- remarkPlugins: [exampleRemarkPlugin],
+ processor: unified({ remarkPlugins: [exampleRemarkPlugin] }),
}),
],
});
@@ -282,29 +321,27 @@ Now, every Markdown or MDX file will have `customProperty` in its frontmatter, m
### Extending Markdown config from MDX
-Astro's MDX integration 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.
+Astro's MDX integration will extend [your project's existing Markdown configuration](/en/reference/configuration-reference/#markdown-options) by default, including the [Markdown processor](#choosing-a-markdown-processor). To override individual options, you can specify their equivalent in your MDX configuration.
-The following example disables GitHub-Flavored Markdown and applies a different set of remark plugins for MDX files:
+The following example uses a different syntax highlighter and a different set of plugins for `.mdx` files than for `.md` files:
```ts 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,
+ syntaxHighlight: 'shiki',
+ processor: unified({ remarkPlugins: [remarkPlugin1] }),
},
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: unified({ remarkPlugins: [remarkPlugin2] }),
})
]
});
@@ -314,42 +351,23 @@ To avoid extending your Markdown config from MDX, set [the `extendMarkdownConfig
```ts 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: [remarkPlugin],
+ processor: unified({ remarkPlugins: [remarkPlugin] }),
},
integrations: [
mdx({
// Markdown config now ignored
extendMarkdownConfig: false,
- // No `remarkPlugins` applied
+ // Default `unified()` processor used
})
]
});
```
-## Using the Sätteri processor
-
-By default, Astro renders Markdown with [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype). You can opt in to [Sätteri](https://satteri.bruits.org/), a native Markdown and MDX compiler, with the [`markdown.processor`](/en/reference/configuration-reference/#markdownprocessor) option:
-
-```js title="astro.config.mjs"
-import { defineConfig, satteri } from 'astro/config';
-
-export default defineConfig({
- markdown: {
- processor: satteri({
- features: { directive: true, definitionList: true },
- }),
- },
-});
-```
-
-The Sätteri processor accepts its own plugins through `mdastPlugins` and `hastPlugins`, and toggles optional parser features through `features`. See the [Sätteri documentation](https://satteri.bruits.org/) for the available plugins and features.
-
-Switching processors replaces remark and rehype for both `.md` and `.mdx` files. Any `remarkPlugins`/`rehypePlugins` set in your config will not apply. To use Sätteri only for `.mdx` files, set the [`processor` option on the MDX integration](/en/guides/integrations-guide/mdx/#processor) instead.
-
## Individual Markdown pages
:::tip
diff --git a/src/content/docs/en/guides/migrate-to-astro/index.mdx b/src/content/docs/en/guides/migrate-to-astro/index.mdx
index 2705cb30b852e..389b3a6b5b849 100644
--- a/src/content/docs/en/guides/migrate-to-astro/index.mdx
+++ b/src/content/docs/en/guides/migrate-to-astro/index.mdx
@@ -27,7 +27,7 @@ Depending on your existing project, you may be able to use your existing:
- [CSS stylesheets or libraries](/en/guides/styling/) including Tailwind.
-- [Markdown/MDX files](/en/guides/markdown-content/), configured using your existing [remark and rehype plugins](/en/guides/markdown-content/#markdown-plugins).
+- [Markdown/MDX files](/en/guides/markdown-content/), with a [configurable Markdown processor](/en/guides/markdown-content/#markdown-plugins) and support for remark and rehype plugins.
- [Content from a CMS](/en/guides/cms/) through an integration or API.
diff --git a/src/content/docs/en/reference/content-loader-reference.mdx b/src/content/docs/en/reference/content-loader-reference.mdx
index e7a93a1bb0efd..b04f13944c847 100644
--- a/src/content/docs/en/reference/content-loader-reference.mdx
+++ b/src/content/docs/en/reference/content-loader-reference.mdx
@@ -1305,7 +1305,7 @@ Specifies the list of headings present in this file. Each heading is described b
**Type:** `Record`
-Describes the raw frontmatter, parsed from the file. This may include [programmatically injected data from remark plugins](/en/guides/markdown-content/#modifying-frontmatter-programmatically).
+Describes the raw frontmatter, parsed from the file. This may include [programmatically injected data from Markdown plugins](/en/guides/markdown-content/#modifying-frontmatter-programmatically).
## Live loader API
diff --git a/src/content/docs/en/reference/modules/astro-content.mdx b/src/content/docs/en/reference/modules/astro-content.mdx
index 3d604a783c191..3ef4bb60bf3e4 100644
--- a/src/content/docs/en/reference/modules/astro-content.mdx
+++ b/src/content/docs/en/reference/modules/astro-content.mdx
@@ -328,7 +328,7 @@ A function to compile a given entry for rendering. This returns the following pr
- `` - A component used to render the document's contents in an Astro file.
- `headings` - A generated list of headings, [mirroring Astro's `getHeadings()` utility](/en/guides/markdown-content/#available-properties) on Markdown and MDX imports.
-- `remarkPluginFrontmatter ` - The modified frontmatter object after any [remark or rehype plugins have been applied](/en/guides/markdown-content/#modifying-frontmatter-programmatically). Set to type `any`.
+- `remarkPluginFrontmatter ` - The modified frontmatter object after any [Markdown plugins have been applied](/en/guides/markdown-content/#modifying-frontmatter-programmatically). Set to type `any`.
```astro title="src/pages/blog/entry-1.astro"
---
diff --git a/src/content/docs/en/reference/programmatic-reference.mdx b/src/content/docs/en/reference/programmatic-reference.mdx
index c088a11b9ee89..51bb2b9f98405 100644
--- a/src/content/docs/en/reference/programmatic-reference.mdx
+++ b/src/content/docs/en/reference/programmatic-reference.mdx
@@ -190,7 +190,7 @@ The following utilities can be [imported from `astro/config`](/en/reference/modu
Takes an Astro configuration object and a partial object containing any set of valid Astro configuration options, and returns a valid Astro configuration combining the two values such that:
-- Arrays are concatenated (including integrations and remark plugins).
+- Arrays are concatenated (including integrations).
- Objects are merged recursively.
- Vite options are merged using [Vite's own `mergeConfig()` function](https://vite.dev/guide/api-javascript#mergeconfig) with the default `isRoot` flag.
- Options that can be provided as functions are wrapped into new functions that recursively merge the return values from both configurations with these same rules.
From 03fd7e77f9977cd5877d6fece04b4b571f2e3046 Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Sat, 23 May 2026 05:09:35 +0200
Subject: [PATCH 08/18] Apply suggestion from @Princesseuh
---
src/content/docs/en/guides/integrations-guide/mdx.mdx | 1 +
1 file changed, 1 insertion(+)
diff --git a/src/content/docs/en/guides/integrations-guide/mdx.mdx b/src/content/docs/en/guides/integrations-guide/mdx.mdx
index ab97eb085ef45..17f9c41781f88 100644
--- a/src/content/docs/en/guides/integrations-guide/mdx.mdx
+++ b/src/content/docs/en/guides/integrations-guide/mdx.mdx
@@ -281,6 +281,7 @@ export default defineConfig({
remarkPlugins: [remarkToc],
rehypePlugins: [rehypePresetMinify],
remarkRehype: { footnoteLabel: 'Footnotes' },
+ gfm: false
}),
}),
],
From b49243c83791d42675851d62dfd27b3b397744c7 Mon Sep 17 00:00:00 2001
From: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
Date: Wed, 27 May 2026 12:46:16 +0200
Subject: [PATCH 09/18] fix: innacuracies
---
.../docs/en/guides/integrations-guide/mdx.mdx | 18 ++++++++++--------
.../docs/en/guides/markdown-content.mdx | 7 +++----
2 files changed, 13 insertions(+), 12 deletions(-)
diff --git a/src/content/docs/en/guides/integrations-guide/mdx.mdx b/src/content/docs/en/guides/integrations-guide/mdx.mdx
index 17f9c41781f88..4fcf573a7e966 100644
--- a/src/content/docs/en/guides/integrations-guide/mdx.mdx
+++ b/src/content/docs/en/guides/integrations-guide/mdx.mdx
@@ -294,17 +294,18 @@ export default defineConfig({
-**Type:** `MarkdownProcessorEntry`
+**Type:** `MarkdownProcessor`
**Default:** inherited from [`markdown.processor`](/en/reference/configuration-reference/#markdownprocessor)
-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.
+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/):
+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, satteri } from 'astro/config';
+import { defineConfig } from 'astro/config';
+import { satteri } from '@astrojs/markdown-satteri';
import mdx from '@astrojs/mdx';
export default defineConfig({
@@ -335,15 +336,16 @@ import mdx from '@astrojs/mdx';
export default defineConfig({
// ...
markdown: {
- syntaxHighlight: 'shiki',
+ syntaxHighlight: 'prism',
processor: unified({ remarkPlugins: [remarkPlugin1] }),
},
integrations: [
mdx({
- // `syntaxHighlight` inherited from Markdown
+ // Markdown `syntaxHighlight` overridden,
+ // `.mdx` files use Shiki instead.
+ syntaxHighlight: 'shiki',
- // Markdown `processor` ignored,
- // `.mdx` files use this processor instead.
+ // `markdown.processor` gets overridden for `.mdx` files by this option
processor: unified({ remarkPlugins: [remarkPlugin2] }),
}),
],
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index 8e3cbc0b72746..52c25dda023b9 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -332,15 +332,14 @@ import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
- syntaxHighlight: 'shiki',
+ syntaxHighlight: 'prism',
processor: unified({ remarkPlugins: [remarkPlugin1] }),
},
integrations: [
mdx({
- // `syntaxHighlight` inherited from Markdown
+ // `markdown.syntaxHighlight` gets overridden for `.mdx` files by this option
+ syntaxHighlight: 'shiki',
- // Markdown `processor` ignored,
- // `.mdx` files use this processor instead.
processor: unified({ remarkPlugins: [remarkPlugin2] }),
})
]
From 244d57044cbdb1d7ecf9f4b0a5fec0db04595fab Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Wed, 27 May 2026 12:48:36 +0200
Subject: [PATCH 10/18] Apply suggestion from @Princesseuh
---
src/content/docs/en/guides/migrate-to-astro/index.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/content/docs/en/guides/migrate-to-astro/index.mdx b/src/content/docs/en/guides/migrate-to-astro/index.mdx
index 389b3a6b5b849..65519f84a0cf7 100644
--- a/src/content/docs/en/guides/migrate-to-astro/index.mdx
+++ b/src/content/docs/en/guides/migrate-to-astro/index.mdx
@@ -27,7 +27,7 @@ Depending on your existing project, you may be able to use your existing:
- [CSS stylesheets or libraries](/en/guides/styling/) including Tailwind.
-- [Markdown/MDX files](/en/guides/markdown-content/), with a [configurable Markdown processor](/en/guides/markdown-content/#markdown-plugins) and support for remark and rehype plugins.
+- [Markdown/MDX files](/en/guides/markdown-content/), with a [configurable Markdown processor](/en/guides/markdown-content/#markdown-plugins) with support for plugins.
- [Content from a CMS](/en/guides/cms/) through an integration or API.
From a5fed26da315e8110005fee5addb17016a696c8f Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Wed, 27 May 2026 12:50:50 +0200
Subject: [PATCH 11/18] Apply suggestion from @Princesseuh
---
src/content/docs/en/guides/markdown-content.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index 52c25dda023b9..2fe6aa9269f3e 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -361,7 +361,7 @@ export default defineConfig({
mdx({
// Markdown config now ignored
extendMarkdownConfig: false,
- // Default `unified()` processor used
+ // Default `unified()` processor used with no plugins
})
]
});
From 911e56c977fdd3b67e6bbb15bb7fd2785fb2bdca Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Wed, 27 May 2026 12:52:02 +0200
Subject: [PATCH 12/18] Apply suggestion from @Princesseuh
---
src/content/docs/en/guides/markdown-content.mdx | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index 2fe6aa9269f3e..4a88cb2dbd586 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -246,7 +246,8 @@ export default defineConfig({
To use [Sätteri](https://satteri.bruits.org/) instead of remark and rehype, import `satteri` from `astro/config` and pass it to `markdown.processor`:
```js title="astro.config.mjs"
-import { defineConfig, satteri } from 'astro/config';
+import { defineConfig } from 'astro/config';
+import { satteri } from '@astrojs/markdown-satteri';
export default defineConfig({
markdown: {
From 1697382585f8b9ec1627a800bbbfdb214e1b0191 Mon Sep 17 00:00:00 2001
From: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
Date: Wed, 27 May 2026 12:58:37 +0200
Subject: [PATCH 13/18] fix: some tweaks
---
src/content/docs/en/guides/markdown-content.mdx | 12 +++++++-----
1 file changed, 7 insertions(+), 5 deletions(-)
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index 4a88cb2dbd586..a7cd9c90b1f52 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -189,10 +189,10 @@ You can extend Markdown processing with plugins, enable additional parser featur
### Choosing a Markdown processor
-The [`markdown.processor` option](/en/reference/configuration-reference/#markdownprocessor) controls which engine renders your `.md` and `.mdx` files. Astro provides two built-in processors:
+The [`markdown.processor` option](/en/reference/configuration-reference/#markdownprocessor) controls which engine renders your `.md` and `.mdx` files. Astro provides two official options:
-- **`unified()`** (default): the [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype) pipeline, with its large plugin ecosystem. Provided by `@astrojs/markdown-remark`, which ships with Astro.
-- **`satteri()`**: the native [Sätteri](https://satteri.bruits.org/) pipeline — a faster Markdown and MDX compiler with its own plugin model.
+- **`unified()`** (default): the [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype) pipeline, with its large plugin ecosystem.
+- **`satteri()`**: the native [Sätteri](https://satteri.bruits.org/) pipeline, a faster Markdown and MDX compiler with its own plugin model. Provided by `@astrojs/markdown-satteri`, which you install separately.
### Using remark and rehype plugins
@@ -243,22 +243,24 @@ export default defineConfig({
### Switching to the Sätteri processor
-To use [Sätteri](https://satteri.bruits.org/) instead of remark and rehype, import `satteri` from `astro/config` and pass it to `markdown.processor`:
+To use [Sätteri](https://satteri.bruits.org/) instead of remark and rehype, install `@astrojs/markdown-satteri`, then import `satteri` and pass it to `markdown.processor`:
```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';
+import { myMdastPlugin } from './my-satteri-plugin.mjs';
export default defineConfig({
markdown: {
processor: satteri({
+ mdastPlugins: [myMdastPlugin()],
features: { directive: true, definitionList: true },
}),
},
});
```
-The Sätteri processor accepts its own plugins through `mdastPlugins` and `hastPlugins`, and toggles optional parser features through `features`. See the [Sätteri documentation](https://satteri.bruits.org/) for the available plugins and features.
+The Sätteri processor accepts its own plugins through `mdastPlugins` and `hastPlugins`, and toggles optional parser features through `features`. See the [Sätteri documentation](https://satteri.bruits.org/docs/) for the available plugins and features.
Switching processors replaces remark and rehype for both `.md` and `.mdx` files. Any remark or rehype plugins in your config will not apply. To use Sätteri only for `.mdx` files, set the [`processor` option on the MDX integration](/en/guides/integrations-guide/mdx/#processor) instead.
From 4f0537749cec9036140383719194a930af45fe6e Mon Sep 17 00:00:00 2001
From: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
Date: Wed, 27 May 2026 13:40:44 +0200
Subject: [PATCH 14/18] feat: adjust for plugin ordering
---
.../docs/en/guides/markdown-content.mdx | 56 +++++++++++++------
1 file changed, 39 insertions(+), 17 deletions(-)
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index a7cd9c90b1f52..fc1db8b719189 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -9,7 +9,7 @@ import Since from '~/components/Since.astro';
import { FileTree } from '@astrojs/starlight/components';
import RecipeLinks from "~/components/RecipeLinks.astro";
import ReadMore from '~/components/ReadMore.astro';
-import { Steps } from '@astrojs/starlight/components';
+import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
[Markdown](https://daringfireball.net/projects/markdown/) is commonly used to author text-heavy content like blog posts and documentation. Astro includes built-in support for Markdown files that can also include [frontmatter YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) (or [TOML](https://toml.io)) to define custom properties such as a title, description, and tags.
@@ -160,24 +160,46 @@ Astro injects an `id` attribute into all heading elements (`` to ``) in
You can customize these heading IDs with a [Markdown processor](#choosing-a-markdown-processor) plugin that injects `id` attributes (e.g. `rehype-slug`). Your custom IDs, instead of Astro's defaults, will be reflected in the HTML output and the items returned by `getHeadings()`.
-When using the default [remark/rehype processor](#using-remark-and-rehype-plugins), Astro injects `id` attributes after your rehype plugins have run. If one of your custom rehype plugins needs to access the IDs injected by Astro, you can import and use Astro’s `rehypeHeadingIds` plugin directly. Be sure to add `rehypeHeadingIds` before any plugins that rely on it:
+Astro injects `id` attributes after your custom plugins have run, so any ID set by a plugin is preserved. If one of your custom plugins needs to access the IDs injected by Astro, you can import Astro's heading-ids plugin and place it before any plugins that rely on it:
-```js title="astro.config.mjs" ins={2-3, 9}
-import { defineConfig } from 'astro/config';
-import { unified, rehypeHeadingIds } from '@astrojs/markdown-remark';
-import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';
+
+
+ ```js title="astro.config.mjs" ins={2-3, 9}
+ import { defineConfig } from 'astro/config';
+ import { unified, rehypeHeadingIds } from '@astrojs/markdown-remark';
+ import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';
-export default defineConfig({
- markdown: {
- processor: unified({
- rehypePlugins: [
- rehypeHeadingIds,
- otherPluginThatReliesOnHeadingIDs,
- ],
- }),
- },
-});
-```
+ export default defineConfig({
+ markdown: {
+ processor: unified({
+ rehypePlugins: [
+ rehypeHeadingIds,
+ otherPluginThatReliesOnHeadingIDs,
+ ],
+ }),
+ },
+ });
+ ```
+
+
+ ```js title="astro.config.mjs" ins={2-3, 9}
+ import { defineConfig } from 'astro/config';
+ import { satteri, satteriHeadingIdsPlugin } from '@astrojs/markdown-satteri';
+ import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';
+
+ export default defineConfig({
+ markdown: {
+ processor: satteri({
+ hastPlugins: [
+ satteriHeadingIdsPlugin(),
+ otherPluginThatReliesOnHeadingIDs,
+ ],
+ }),
+ },
+ });
+ ```
+
+
## Markdown Plugins
From b4ad1c1b1594dfd3c728e4f24e0aacd267017cba Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Wed, 27 May 2026 15:48:53 +0200
Subject: [PATCH 15/18] Apply suggestions from code review
Co-authored-by: Armand Philippot
---
src/content/docs/en/guides/markdown-content.mdx | 7 ++++---
src/content/docs/en/guides/migrate-to-astro/index.mdx | 2 +-
2 files changed, 5 insertions(+), 4 deletions(-)
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index fc1db8b719189..9f6c065891e86 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -160,7 +160,7 @@ Astro injects an `id` attribute into all heading elements (`` to ``) in
You can customize these heading IDs with a [Markdown processor](#choosing-a-markdown-processor) plugin that injects `id` attributes (e.g. `rehype-slug`). Your custom IDs, instead of Astro's defaults, will be reflected in the HTML output and the items returned by `getHeadings()`.
-Astro injects `id` attributes after your custom plugins have run, so any ID set by a plugin is preserved. If one of your custom plugins needs to access the IDs injected by Astro, you can import Astro's heading-ids plugin and place it before any plugins that rely on it:
+Astro injects `id` attributes after your custom plugins have run, so any ID set by a plugin is preserved. If one of your custom plugins needs to access the IDs injected by Astro, you can import Astro's heading ids plugin and place it before any plugins that rely on it:
@@ -310,7 +310,7 @@ When using the [remark/rehype processor](#using-remark-and-rehype-plugins), you
2. Apply this plugin to your `markdown` or `mdx` integration config:
- ```js title="astro.config.mjs" {2,3}
+
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
@@ -324,7 +324,7 @@ When using the [remark/rehype processor](#using-remark-and-rehype-plugins), you
or
- ```js title="astro.config.mjs" {2,3}
+
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { unified } from '@astrojs/markdown-remark';
@@ -365,6 +365,7 @@ export default defineConfig({
// `markdown.syntaxHighlight` gets overridden for `.mdx` files by this option
syntaxHighlight: 'shiki',
+ // `markdown.processor` gets overridden for `.mdx` files with a different remark plugin
processor: unified({ remarkPlugins: [remarkPlugin2] }),
})
]
diff --git a/src/content/docs/en/guides/migrate-to-astro/index.mdx b/src/content/docs/en/guides/migrate-to-astro/index.mdx
index 65519f84a0cf7..c9f967302057c 100644
--- a/src/content/docs/en/guides/migrate-to-astro/index.mdx
+++ b/src/content/docs/en/guides/migrate-to-astro/index.mdx
@@ -27,7 +27,7 @@ Depending on your existing project, you may be able to use your existing:
- [CSS stylesheets or libraries](/en/guides/styling/) including Tailwind.
-- [Markdown/MDX files](/en/guides/markdown-content/), with a [configurable Markdown processor](/en/guides/markdown-content/#markdown-plugins) with support for plugins.
+- [Markdown/MDX files](/en/guides/markdown-content/), with a [configurable Markdown processor](/en/guides/markdown-content/#markdown-plugins) that supports plugins.
- [Content from a CMS](/en/guides/cms/) through an integration or API.
From bd8b401154b150d01321680fa2d9a4ed7bc6a516 Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Wed, 27 May 2026 16:02:23 +0200
Subject: [PATCH 16/18] Apply suggestions from code review
Co-authored-by: Armand Philippot
From b513e28934dbea0da9de45f97c0b3d842981b0c2 Mon Sep 17 00:00:00 2001
From: Armand Philippot
Date: Wed, 27 May 2026 16:06:50 +0200
Subject: [PATCH 17/18] bad GitHub
---
src/content/docs/en/guides/markdown-content.mdx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index 9f6c065891e86..7d24153e7a75c 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -310,7 +310,7 @@ When using the [remark/rehype processor](#using-remark-and-rehype-plugins), you
2. Apply this plugin to your `markdown` or `mdx` integration config:
-
+ ```js title="astro.config.mjs" {2,3,7}
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
@@ -324,7 +324,7 @@ When using the [remark/rehype processor](#using-remark-and-rehype-plugins), you
or
-
+ ```js title="astro.config.mjs" {3,4,9}
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { unified } from '@astrojs/markdown-remark';
From d71f973b177eb1160e256b6f6ceb16a85d0b3371 Mon Sep 17 00:00:00 2001
From: "Houston (Bot)" <108291165+astrobot-houston@users.noreply.github.com>
Date: Wed, 27 May 2026 07:12:56 -0700
Subject: [PATCH 18/18] ci: update configuration reference docs (#13943)
Co-authored-by: delucis <357379+delucis@users.noreply.github.com>
Co-authored-by: Armand Philippot
---
.../en/reference/configuration-reference.mdx | 51 +++++++++++++++++++
1 file changed, 51 insertions(+)
diff --git a/src/content/docs/en/reference/configuration-reference.mdx b/src/content/docs/en/reference/configuration-reference.mdx
index 11ff08f42bc3d..8a710c7e08a6c 100644
--- a/src/content/docs/en/reference/configuration-reference.mdx
+++ b/src/content/docs/en/reference/configuration-reference.mdx
@@ -1876,6 +1876,11 @@ export default defineConfig({
### markdown.remarkPlugins
+
+:::caution[Deprecated]
+Pass `remarkPlugins` to `unified({ remarkPlugins })` from `@astrojs/markdown-remark` and set it as `markdown.processor` instead. Will be removed in a future major.
+:::
+
**Type:** `RemarkPlugins`
@@ -1894,6 +1899,11 @@ import remarkToc from 'remark-toc';
### markdown.rehypePlugins
+
+:::caution[Deprecated]
+Pass `rehypePlugins` to `unified({ rehypePlugins })` from `@astrojs/markdown-remark` and set it as `markdown.processor` instead. Will be removed in a future major.
+:::
+
**Type:** `RehypePlugins`
@@ -1912,6 +1922,11 @@ import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
### markdown.gfm
+
+:::caution[Deprecated]
+Pass `gfm` to your processor instead (e.g. `unified({ gfm: false })`). Will be removed in a future major.
+:::
+
**Type:** `boolean`
@@ -1931,6 +1946,11 @@ Astro uses [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) by
### markdown.smartypants
+
+:::caution[Deprecated]
+Pass `smartypants` to your processor instead (e.g. `unified({ smartypants: false })`). Will be removed in a future major.
+:::
+
**Type:** `boolean | Smartypants`
@@ -1946,6 +1966,11 @@ For more control over typography, you can instead specify a configuration object
### markdown.remarkRehype
+
+:::caution[Deprecated]
+Pass `remarkRehype` to `unified({ remarkRehype })` from `@astrojs/markdown-remark` and set it as `markdown.processor` instead. Will be removed in a future major.
+:::
+
**Type:** `RemarkRehype`
@@ -1962,6 +1987,32 @@ Pass options to [remark-rehype](https://github.com/remarkjs/remark-rehype#api).
};
```
+### markdown.processor
+
+
+
+**Type:** `MarkdownProcessor`
+
+
+
+Configures the Markdown processor used to render `.md` files. Defaults to `unified()` from
+`@astrojs/markdown-remark` (the remark/rehype pipeline).
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
+import remarkToc from 'remark-toc';
+
+export default defineConfig({
+ markdown: {
+ processor: unified({
+ remarkPlugins: [remarkToc],
+ }),
+ },
+});
+```
+
## i18n