diff --git a/src/content/docs/en/guides/integrations-guide/mdx.mdx b/src/content/docs/en/guides/integrations-guide/mdx.mdx
index 4c22f7f412575..ef8ef9e936b3e 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="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.
+
+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