From 9495a118bbbff4c34c0dc273ef8f415d02987828 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 1/3] 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 +-
src/content/docs/en/guides/upgrade-to/v7.mdx | 53 +++++++
.../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 +-
10 files changed, 235 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/guides/upgrade-to/v7.mdx b/src/content/docs/en/guides/upgrade-to/v7.mdx
index d4c9be4c68375..55c28b73364aa 100644
--- a/src/content/docs/en/guides/upgrade-to/v7.mdx
+++ b/src/content/docs/en/guides/upgrade-to/v7.mdx
@@ -99,3 +99,56 @@ export default defineConfig({
```
If you encounter any issues with the Rust compiler, please report them on [GitHub](https://github.com/withastro/astro/issues).
+
+### Default Markdown processor
+
+Astro v7.0 replaces [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype) as the default Markdown and MDX engine with [Sätteri](https://satteri.bruits.org/), a native (Rust) Markdown / MDX compiler. Both `.md` and `.mdx` files now render through Sätteri by default.
+
+Because of this, `@astrojs/markdown-remark` is no longer included with `astro`. Projects that depend on remark or rehype plugins must install it and opt back in to the remark/rehype pipeline through the new [`markdown.processor` option](/en/reference/configuration-reference/#markdownprocessor).
+
+The top-level `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` options are deprecated, as are `markdown.gfm` and `markdown.smartypants`.
+
+##### What should I do?
+
+If your project does not configure any remark or rehype plugins, no action is required. Your content renders through Sätteri, and the output should be unchanged.
+
+If your project sets `markdown.remarkPlugins`, `markdown.rehypePlugins`, or `markdown.remarkRehype`, install `@astrojs/markdown-remark`:
+
+
+
+ ```shell
+ npm install @astrojs/markdown-remark
+ ```
+
+
+ ```shell
+ pnpm add @astrojs/markdown-remark
+ ```
+
+
+ ```shell
+ yarn add @astrojs/markdown-remark
+ ```
+
+
+
+Then, move your plugins into the `unified()` processor:
+
+```js title="astro.config.mjs" ins={2,8} del={7}
+import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
+import remarkToc from 'remark-toc';
+
+export default defineConfig({
+ markdown: {
+ remarkPlugins: [remarkToc],
+ processor: unified({ remarkPlugins: [remarkToc] }),
+ },
+});
+```
+
+Your existing top-level options continue to work for now as long as `@astrojs/markdown-remark` is installed, but they print a deprecation warning and will be removed in a future major version. Setting them without the package installed throws an error.
+
+To replace the deprecated `markdown.gfm` and `markdown.smartypants` options, configure the equivalent features on your processor instead. For example, use `satteri({ features: { gfm: false } })` for the default processor.
+
+See [Markdown plugins](/en/guides/markdown-content/#markdown-plugins) for more about configuring the Markdown processor.
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 f9468a2e19215f109983dc2b96e35c2be989dabe Mon Sep 17 00:00:00 2001
From: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
Date: Thu, 21 May 2026 02:09:19 +0200
Subject: [PATCH 2/3] feat: update upgrade guide
---
src/content/docs/en/guides/upgrade-to/v7.mdx | 112 +++++++++++--------
1 file changed, 68 insertions(+), 44 deletions(-)
diff --git a/src/content/docs/en/guides/upgrade-to/v7.mdx b/src/content/docs/en/guides/upgrade-to/v7.mdx
index 55c28b73364aa..178995e237cf8 100644
--- a/src/content/docs/en/guides/upgrade-to/v7.mdx
+++ b/src/content/docs/en/guides/upgrade-to/v7.mdx
@@ -64,55 +64,23 @@ If your project doesn't work as expected after upgrading to v7.0, check this gui
See [the Astro changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) for full release notes.
-## Breaking Changes
-
-### Dependency Upgrades
+## Deprecated
-#### Vite 8
-
-Astro v7.0 upgrades to [Vite 8](https://vite.dev/blog/announcing-vite-8) as the development server and production bundler.
+The following deprecated features are no longer supported and are no longer documented. Please update your project accordingly.
-##### What should I do?
-
-If you are using Vite-specific plugins, configuration, or APIs, check the [Vite 8 migration guide](https://vite.dev/guide/migration) for their breaking changes and upgrade your project as needed.
-
-Most Astro users should be able to upgrade without any changes to their project code. This is primarily a breaking change for Astro integrations and plugins that depend on Vite internals.
+Some deprecated features may temporarily continue to function until they are completely removed. Others may silently have no effect, or throw an error prompting you to update your code.
-### Rust Compiler
+### Deprecated: top-level `markdown` plugin options
-The Rust-based Astro compiler, previously available as an experimental flag (`experimental.rustCompiler`), is now the default and only compiler in Astro 7. The Rust compiler delivers significantly faster build times compared to the previous Go-based compiler.
+
-##### What should I do?
+With the [new default Markdown processor](#changed-default-markdown-processor), the top-level `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` options are deprecated, as are `markdown.gfm` and `markdown.smartypants`. These are now configured through the [`markdown.processor`](/en/reference/configuration-reference/#markdownprocessor) option instead.
-No action is required for most projects. The Rust compiler is a drop-in replacement for the Go-based compiler.
+The remark / rehype top-level options continue to work for now as long as `@astrojs/markdown-remark` is installed. They will be removed in a future major version.
-If you had previously opted in to the Rust compiler via the experimental flag, you can now remove it from your configuration:
+#### What should I do?
-```js title="astro.config.mjs" del={4-6}
-import { defineConfig } from 'astro/config';
-
-export default defineConfig({
- experimental: {
- rustCompiler: true,
- },
-});
-```
-
-If you encounter any issues with the Rust compiler, please report them on [GitHub](https://github.com/withastro/astro/issues).
-
-### Default Markdown processor
-
-Astro v7.0 replaces [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype) as the default Markdown and MDX engine with [Sätteri](https://satteri.bruits.org/), a native (Rust) Markdown / MDX compiler. Both `.md` and `.mdx` files now render through Sätteri by default.
-
-Because of this, `@astrojs/markdown-remark` is no longer included with `astro`. Projects that depend on remark or rehype plugins must install it and opt back in to the remark/rehype pipeline through the new [`markdown.processor` option](/en/reference/configuration-reference/#markdownprocessor).
-
-The top-level `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` options are deprecated, as are `markdown.gfm` and `markdown.smartypants`.
-
-##### What should I do?
-
-If your project does not configure any remark or rehype plugins, no action is required. Your content renders through Sätteri, and the output should be unchanged.
-
-If your project sets `markdown.remarkPlugins`, `markdown.rehypePlugins`, or `markdown.remarkRehype`, install `@astrojs/markdown-remark`:
+If your project sets `markdown.remarkPlugins`, `markdown.rehypePlugins`, or `markdown.remarkRehype`, install `@astrojs/markdown-remark`, which is no longer included with `astro`:
@@ -132,7 +100,7 @@ If your project sets `markdown.remarkPlugins`, `markdown.rehypePlugins`, or `mar
-Then, move your plugins into the `unified()` processor:
+Then, move your plugins into the `unified()` processor passed to `markdown.processor`:
```js title="astro.config.mjs" ins={2,8} del={7}
import { defineConfig } from 'astro/config';
@@ -147,8 +115,64 @@ export default defineConfig({
});
```
-Your existing top-level options continue to work for now as long as `@astrojs/markdown-remark` is installed, but they print a deprecation warning and will be removed in a future major version. Setting them without the package installed throws an error.
-
To replace the deprecated `markdown.gfm` and `markdown.smartypants` options, configure the equivalent features on your processor instead. For example, use `satteri({ features: { gfm: false } })` for the default processor.
See [Markdown plugins](/en/guides/markdown-content/#markdown-plugins) for more about configuring the Markdown processor.
+
+## Changed Defaults
+
+Some default behavior has changed in Astro v7.0 and your project code may need updating to account for these changes.
+
+In most cases, the only action needed is to review your existing project's deployment and ensure that it continues to function as you expect, making updates to your code as necessary. In some cases, there may be a configuration setting to allow you to continue to use the previous default behavior.
+
+### Changed: default Markdown processor
+
+
+
+In Astro v6.x, `.md` and `.mdx` files were processed with [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype), and `@astrojs/markdown-remark` was included with `astro`.
+
+Astro v7.0 replaces remark and rehype as the default Markdown and MDX engine with [Sätteri](https://satteri.bruits.org/), a performant Markdown / MDX compiler. Both `.md` and `.mdx` files now render through Sätteri by default, and `@astrojs/markdown-remark` is no longer included with `astro`. The new [`markdown.processor` option](/en/reference/configuration-reference/#markdownprocessor) controls which processor renders your content.
+
+#### What should I do?
+
+If your project does not configure any remark or rehype plugins, no action is required. Your content renders through Sätteri, and the output should be unchanged.
+
+If your project depends on the remark / rehype ecosystem, follow the steps for the [deprecated top-level `markdown` plugin options](#deprecated-top-level-markdown-plugin-options) to install `@astrojs/markdown-remark` and opt back in to the remark / rehype pipeline.
+
+See [Markdown plugins](/en/guides/markdown-content/#markdown-plugins) for more about configuring the Markdown processor.
+
+## Breaking Changes
+
+### Dependency Upgrades
+
+#### Vite 8
+
+Astro v7.0 upgrades to [Vite 8](https://vite.dev/blog/announcing-vite-8) as the development server and production bundler.
+
+##### What should I do?
+
+If you are using Vite-specific plugins, configuration, or APIs, check the [Vite 8 migration guide](https://vite.dev/guide/migration) for their breaking changes and upgrade your project as needed.
+
+Most Astro users should be able to upgrade without any changes to their project code. This is primarily a breaking change for Astro integrations and plugins that depend on Vite internals.
+
+### Rust Compiler
+
+The Rust-based Astro compiler, previously available as an experimental flag (`experimental.rustCompiler`), is now the default and only compiler in Astro 7. The Rust compiler delivers significantly faster build times compared to the previous Go-based compiler.
+
+##### What should I do?
+
+No action is required for most projects. The Rust compiler is a drop-in replacement for the Go-based compiler.
+
+If you had previously opted in to the Rust compiler via the experimental flag, you can now remove it from your configuration:
+
+```js title="astro.config.mjs" del={4-6}
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+ experimental: {
+ rustCompiler: true,
+ },
+});
+```
+
+If you encounter any issues with the Rust compiler, please report them on [GitHub](https://github.com/withastro/astro/issues).
From 2bf5bb039afa888a86e2afc0990f354b374b9926 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 3/3] 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.