From 12f64596e60cf625cdb81c7ee98a89da20f7d2e2 Mon Sep 17 00:00:00 2001
From: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
Date: Fri, 28 Aug 2026 14:38:13 +0200
Subject: [PATCH 1/2] feat: document recma plugins new spot

---
 .../docs/en/guides/integrations-guide/mdx.mdx | 31 +++++++++++++++++++
 .../docs/en/guides/markdown-content.mdx       |  2 +-
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/src/content/docs/en/guides/integrations-guide/mdx.mdx b/src/content/docs/en/guides/integrations-guide/mdx.mdx
index 4c22f7f412575..6d9140fcddd89 100644
--- a/src/content/docs/en/guides/integrations-guide/mdx.mdx
+++ b/src/content/docs/en/guides/integrations-guide/mdx.mdx
@@ -318,6 +318,31 @@ export default defineConfig({
 });
 ```
 
+#### Using recma plugins
+
+<p><Since v="7.3.0" pkg="@astrojs/markdown-remark" /></p>
+
+Recma plugins modify the output [estree](https://github.com/estree/estree) directly. This is useful for modifying or injecting JavaScript variables in your MDX files, and has no effect on `.md` files.
+
+Recma plugins are only supported by the [Unified processor](/en/guides/markdown-content/#when-to-use-unified). Pass them to `unified()` from `@astrojs/markdown-remark` using the `recmaPlugins` option:
+
+```js title="astro.config.mjs" {3-4,8}
+import { defineConfig } from 'astro/config';
+import mdx from '@astrojs/mdx';
+import { unified } from '@astrojs/markdown-remark';
+import myRecmaPlugin from './my-recma-plugin.mjs';
+
+export default defineConfig({
+  integrations: [
+    mdx({ processor: unified({ recmaPlugins: [myRecmaPlugin] }) }),
+  ],
+});
+```
+
+You can also set these plugins on [`markdown.processor`](/en/reference/configuration-reference/#markdownprocessor) instead. Your `.mdx` files will still run them, because MDX [extends your Markdown configuration](#extendmarkdownconfig) by default.
+
+We suggest [using AST Explorer](https://astexplorer.net/) to play with estree outputs, and trying [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/) for searching across JavaScript nodes.
+
 ### `extendMarkdownConfig`
 
 <p>
@@ -379,6 +404,12 @@ export default defineConfig({
 
 ### `recmaPlugins`
 
+:::caution[Deprecated]
+This option is deprecated and will be removed in a future major version. Pass `recmaPlugins` to the configured [`processor`](#processor) instead.
+
+Learn more about [using recma plugins](#using-recma-plugins).
+:::
+
 <p>
 
 **Type:** `PluggableList`<br />
diff --git a/src/content/docs/en/guides/markdown-content.mdx b/src/content/docs/en/guides/markdown-content.mdx
index f827adb837804..990d131d72acf 100644
--- a/src/content/docs/en/guides/markdown-content.mdx
+++ b/src/content/docs/en/guides/markdown-content.mdx
@@ -232,7 +232,7 @@ Sätteri is the default Markdown processor since Astro v7. Use it when:
 #### When to use Unified
 
 Unified is the processor used by older versions of Astro. Use it when:
-- You want to take advantage of its large ecosystem of [remark](https://remark.js.org/) or [rehype](https://github.com/rehypejs/rehype) plugins, or you need [recma plugins in your MDX files](/en/guides/integrations-guide/mdx/#recmaplugins).
+- You want to take advantage of its large ecosystem of [remark](https://remark.js.org/) or [rehype](https://github.com/rehypejs/rehype) plugins, or you need [recma plugins in your MDX files](/en/guides/integrations-guide/mdx/#using-recma-plugins).
 - You are not ready to port your existing Unified plugins to Sätteri.
 
 ### Setting up a Markdown processor

From 693eeda712b754e8fef6b0cb2e6d6db7b5ac9913 Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Fri, 28 Aug 2026 15:10:04 +0200
Subject: [PATCH 2/2] Update
 src/content/docs/en/guides/integrations-guide/mdx.mdx

Co-authored-by: Armand Philippot <git@armand.philippot.eu>
---
 src/content/docs/en/guides/integrations-guide/mdx.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/en/guides/integrations-guide/mdx.mdx b/src/content/docs/en/guides/integrations-guide/mdx.mdx
index 6d9140fcddd89..ef8ef9e936b3e 100644
--- a/src/content/docs/en/guides/integrations-guide/mdx.mdx
+++ b/src/content/docs/en/guides/integrations-guide/mdx.mdx
@@ -320,7 +320,7 @@ export default defineConfig({
 
 #### Using recma plugins
 
-<p><Since v="7.3.0" pkg="@astrojs/markdown-remark" /></p>
+<p><Since v="8.0.0" pkg="@astrojs/mdx" /></p>
 
 Recma plugins modify the output [estree](https://github.com/estree/estree) directly. This is useful for modifying or injecting JavaScript variables in your MDX files, and has no effect on `.md` files.