@astrojs/mdx 0.11.4 → 0.11.5

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
-@astrojs/mdx:build: cache hit, replaying output f5624f774ddb4884
-@astrojs/mdx:build: 
-@astrojs/mdx:build: > @astrojs/mdx@0.11.4 build /home/runner/work/astro/astro/packages/integrations/mdx
-@astrojs/mdx:build: > astro-scripts build "src/**/*.ts" && tsc
-@astrojs/mdx:build: 
+@astrojs/mdx:build: cache hit, replaying output 2b17bb94a2cdc3f6
+@astrojs/mdx:build: 
+@astrojs/mdx:build: > @astrojs/mdx@0.11.5 build /home/runner/work/astro/astro/packages/integrations/mdx
+@astrojs/mdx:build: > astro-scripts build "src/**/*.ts" && tsc
+@astrojs/mdx:build: 

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @astrojs/mdx
 
+## 0.11.5
+
+### Patch Changes
+
+- [#5146](https://github.com/withastro/astro/pull/5146) [`308e565ad`](https://github.com/withastro/astro/commit/308e565ad39957e3353d72ca5d3bbce1a1b45008) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Support recmaPlugins config option
+
 ## 0.11.4
 
 ### Patch Changes

package/README.md

@@ -71,11 +71,12 @@ Finally, restart the dev server.
 
 ## Usage
 
-You can [add MDX pages to your project](https://docs.astro.build/en/guides/markdown-content/#markdown-and-mdx-pages) by adding `.mdx` files within your `src/pages/` directory. 
+You can [add MDX pages to your project](https://docs.astro.build/en/guides/markdown-content/#markdown-and-mdx-pages) by adding `.mdx` files within your `src/pages/` directory.
 
 ### Components
 
 To use components in your MDX pages in Astro, head to our [UI framework documentation][astro-ui-frameworks]. You'll explore:
+
 - 📦 how framework components are loaded,
 - 💧 client-side hydration options, and
 - 🤝 opportunities to mix and nest frameworks together
@@ -160,7 +161,7 @@ const posts = await Astro.glob('./*.mdx');
 
 ### Inject frontmatter via remark or rehype plugins
 
-You may want to inject frontmatter properties across all of your MDX files. By using a [remark](#remarkPlugins) or [rehype](#remarkplugins) plugin, you can generate these properties based on a file’s contents.
+You may want to inject frontmatter properties across all of your MDX files. By using a [remark](#remarkplugins) or [rehype](#rehypeplugins) plugin, you can generate these properties based on a file’s contents.
 
 You can append to the `data.astro.frontmatter` property from your plugin’s `file` argument like so:
 
@@ -260,6 +261,7 @@ const { frontmatter, url } = Astro.props;
 #### Layout props
 
 All [exported properties](#exported-properties) are available from `Astro.props` in your layout, **with two key differences:**
+
 - Heading information (i.e. `h1 -> h6` elements) is available via the `headings` array, rather than a `getHeadings()` function.
 - `file` and `url` are _also_ available as nested `frontmatter` properties (i.e. `frontmatter.url` and `frontmatter.file`). This is consistent with Astro's Markdown layout properties.
 
@@ -286,6 +288,7 @@ function fancyJsHelper() {
   Welcome to my new Astro blog, using MDX!
 </BaseLayout>
 ```
+
 Then, your values are available to you through `Astro.props` in your layout, and your MDX content will be injected into the page where your `<slot />` component is written:
 
 ```astro
@@ -319,13 +322,17 @@ will be converted into this HTML:
 But what if you want to specify your own markup for these blockquotes? In the above example, you could create a custom `<Blockquote />` component (in any language) that either has a `<slot />` component or accepts a `children` prop.
 
 ```astro title="src/components/Blockquote.astro"
-<blockquote class="bg-blue-50 p-4">
+---
+const props = Astro.props;
+---
+
+<blockquote {...props} class="bg-blue-50 p-4">
   <span class="text-4xl text-blue-600 mb-2">“</span>
   <slot />
 </blockquote>
 ```
 
-Then in the MDX file you import the component and export it to the `components` export. 
+Then in the MDX file you import the component and export it to the `components` export.
 
 ```mdx title="src/pages/posts/post-1.mdx" {2}
 import Blockquote from '../components/Blockquote.astro';
@@ -334,18 +341,19 @@ export const components = { blockquote: Blockquote };
 
 Now, writing the standard Markdown blockquote syntax (`>`) will use your custom `<Blockquote />` component instead. No need to use a component in Markdown, or write a remark/rehype plugin! Visit the [MDX website](https://mdxjs.com/table-of-components/) for a full list of HTML elements that can be overwritten as custom components.
 
-
 #### Custom components with imported `mdx`
 
-When rendering imported MDX content, custom components can also be passed via the `components` prop:
+When rendering imported MDX content, custom components can be passed via the `components` prop.
+
+Note: An MDX file's exported components will _not_ be used unless you manually import and pass them via the `components` property. See the example below:
 
-```astro title="src/pages/page.astro" "components={{ h1: Heading }}"
+```astro title="src/pages/page.astro" "components={{...components, h1: Heading }}"
 ---
-import Content from '../content.mdx';
+import { Content, components } from '../content.mdx';
 import Heading from '../Heading.astro';
 ---
 
-<Content components={{ h1: Heading }} />
+<Content components={{...components, h1: Heading }} />
 ```
 
 ### Syntax highlighting
@@ -407,7 +415,7 @@ export default {
 
 [Remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md) allow you to extend your Markdown with new capabilities. This includes [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and more. We encourage you to browse [awesome-remark](https://github.com/remarkjs/awesome-remark) for a full curated list!
 
-This example applies the [`remark-toc`](https://github.com/remarkjs/remark-toc) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendPlugins).
+This example applies the [`remark-toc`](https://github.com/remarkjs/remark-toc) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendplugins).
 
 ```js
 // astro.config.mjs
@@ -426,7 +434,7 @@ export default {
 
 We apply our own (non-removable) [`collect-headings`](https://github.com/withastro/astro/blob/main/packages/integrations/mdx/src/rehype-collect-headings.ts) plugin. This applies IDs to all headings (i.e. `h1 -> h6`) in your MDX files to [link to headings via anchor tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#linking_to_an_element_on_the_same_page).
 
-This example applies the [`rehype-minify`](https://github.com/rehypejs/rehype-minify) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendPlugins).
+This example applies the [`rehype-minify`](https://github.com/rehypejs/rehype-minify) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendplugins).
 
 ```js
 // astro.config.mjs
@@ -447,7 +455,7 @@ export default {
 
 #### `markdown` (default)
 
-By default, Astro inherits all [remark](#remarkPlugins) and [rehype](#rehypePlugins) plugins from [the `markdown` option in your Astro config](https://docs.astro.build/en/guides/markdown-content/#markdown-plugins). This also respects the [`markdown.extendDefaultPlugins`](https://docs.astro.build/en/reference/configuration-reference/#markdownextenddefaultplugins) option to extend Astro's defaults. Any additional plugins you apply in your MDX config will be applied _after_ your configured Markdown plugins.
+By default, Astro inherits all [remark](#remarkplugins) and [rehype](#rehypeplugins) plugins from [the `markdown` option in your Astro config](https://docs.astro.build/en/guides/markdown-content/#markdown-plugins). This also respects the [`markdown.extendDefaultPlugins`](https://docs.astro.build/en/reference/configuration-reference/#markdownextenddefaultplugins) option to extend Astro's defaults. Any additional plugins you apply in your MDX config will be applied _after_ your configured Markdown plugins.
 
 This example applies [`remark-toc`](https://github.com/remarkjs/remark-toc) to Markdown _and_ MDX, and [`rehype-minify`](https://github.com/rehypejs/rehype-minify) to MDX alone:
 
@@ -505,6 +513,12 @@ export default {
 }
 ```
 
+### recmaPlugins
+
+These are plugins that modify the output [estree](https://github.com/estree/estree) directly. This is useful for modifying or injecting JavaScript variables in your MDX files.
+
+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.
+
 ## Examples
 
 - The [Astro MDX example](https://github.com/withastro/astro/tree/latest/examples/with-mdx) shows how to use MDX files in your Astro project.

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import type { AstroIntegration } from 'astro';
 export declare type MdxOptions = {
     remarkPlugins?: PluggableList;
     rehypePlugins?: PluggableList;
+    recmaPlugins?: PluggableList;
     /**
      * Choose which remark and rehype plugins to inherit, if any.
      *

package/dist/index.js

@@ -37,6 +37,7 @@ function mdx(mdxOptions = {}) {
         const mdxPluginOpts = {
           remarkPlugins: await getRemarkPlugins(mdxOptions, config),
           rehypePlugins: getRehypePlugins(mdxOptions, config),
+          recmaPlugins: mdxOptions.recmaPlugins,
           jsx: true,
           jsxImportSource: "astro",
           format: "mdx",
@@ -66,7 +67,10 @@ function mdx(mdxOptions = {}) {
                       ...mdxPluginOpts.rehypePlugins ?? [],
                       () => rehypeApplyFrontmatterExport(frontmatter)
                     ],
-                    recmaPlugins: [() => recmaInjectImportMetaEnvPlugin({ importMetaEnv })]
+                    recmaPlugins: [
+                      ...mdxPluginOpts.recmaPlugins ?? [],
+                      () => recmaInjectImportMetaEnvPlugin({ importMetaEnv })
+                    ]
                   });
                   return {
                     code: escapeViteEnvReferences(String(compiled.value)),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrojs/mdx",
   "description": "Use MDX within Astro",
-  "version": "0.11.4",
+  "version": "0.11.5",
   "type": "module",
   "types": "./dist/index.d.ts",
   "author": "withastro",
@@ -46,7 +46,7 @@
     "@types/github-slugger": "^1.3.0",
     "@types/mocha": "^9.1.1",
     "@types/yargs-parser": "^21.0.0",
-    "astro": "1.4.3",
+    "astro": "1.5.3",
     "astro-scripts": "0.0.8",
     "chai": "^4.3.6",
     "cheerio": "^1.0.0-rc.11",
@@ -66,6 +66,7 @@
     "build": "astro-scripts build \"src/**/*.ts\" && tsc",
     "build:ci": "astro-scripts build \"src/**/*.ts\"",
     "dev": "astro-scripts dev \"src/**/*.ts\"",
-    "test": "mocha --exit --timeout 20000"
+    "test": "mocha --exit --timeout 20000",
+    "test:match": "mocha --timeout 20000 -g"
   }
 }

package/src/index.ts

@@ -24,6 +24,7 @@ const COMPILED_CONTENT_ERROR =
 export type MdxOptions = {
 	remarkPlugins?: PluggableList;
 	rehypePlugins?: PluggableList;
+	recmaPlugins?: PluggableList;
 	/**
 	 * Choose which remark and rehype plugins to inherit, if any.
 	 *
@@ -64,6 +65,7 @@ export default function mdx(mdxOptions: MdxOptions = {}): AstroIntegration {
 				const mdxPluginOpts: MdxRollupPluginOptions = {
 					remarkPlugins: await getRemarkPlugins(mdxOptions, config),
 					rehypePlugins: getRehypePlugins(mdxOptions, config),
+					recmaPlugins: mdxOptions.recmaPlugins,
 					jsx: true,
 					jsxImportSource: 'astro',
 					// Note: disable `.md` support
@@ -100,7 +102,10 @@ export default function mdx(mdxOptions: MdxOptions = {}): AstroIntegration {
 											...(mdxPluginOpts.rehypePlugins ?? []),
 											() => rehypeApplyFrontmatterExport(frontmatter),
 										],
-										recmaPlugins: [() => recmaInjectImportMetaEnvPlugin({ importMetaEnv })],
+										recmaPlugins: [
+											...(mdxPluginOpts.recmaPlugins ?? []),
+											() => recmaInjectImportMetaEnvPlugin({ importMetaEnv }),
+										],
 									});
 
 									return {

package/test/fixtures/mdx-plugins/src/pages/with-plugins.mdx

@@ -1,3 +1,5 @@
+export let recmaPluginWorking = false
+
 # TOC test
 
 ## Table of contents
@@ -17,3 +19,5 @@ Oh cool, more text!
 ## Section 2
 
 And section 2, with a hyperlink to check GFM is preserved: https://handle-me-gfm.com
+
+<div data-recma-plugin-works={recmaPluginWorking}></div>

package/test/mdx-plugins.test.js

@@ -4,6 +4,7 @@ import { expect } from 'chai';
 import { parseHTML } from 'linkedom';
 import { loadFixture } from '../../../astro/test/test-utils.js';
 import remarkToc from 'remark-toc';
+import { visit as estreeVisit } from 'estree-util-visit';
 
 const FIXTURE_ROOT = new URL('./fixtures/mdx-plugins/', import.meta.url);
 const FILE = '/with-plugins/index.html';
@@ -164,6 +165,21 @@ describe('MDX plugins', () => {
 		expect(selectGfmLink(document)).to.be.null;
 		expect(selectRemarkExample(document)).to.be.null;
 	});
+
+	it('supports custom recma plugins', async () => {
+		const fixture = await buildFixture({
+			integrations: [
+				mdx({
+					recmaPlugins: [recmaExamplePlugin],
+				}),
+			],
+		});
+
+		const html = await fixture.readFile(FILE);
+		const { document } = parseHTML(html);
+
+		expect(selectRecmaExample(document)).to.not.be.null;
+	});
 });
 
 async function buildFixture(config) {
@@ -194,6 +210,24 @@ function rehypeExamplePlugin() {
 	};
 }
 
+function recmaExamplePlugin() {
+	return (tree) => {
+		estreeVisit(tree, (node) => {
+			if (
+				node.type === 'VariableDeclarator' &&
+				node.id.name === 'recmaPluginWorking' &&
+				node.init?.type === 'Literal'
+			) {
+				node.init = {
+					...(node.init ?? {}),
+					value: true,
+					raw: 'true',
+				};
+			}
+		});
+	};
+}
+
 function selectTocLink(document) {
 	return document.querySelector('ul a[href="#section-1"]');
 }
@@ -209,3 +243,7 @@ function selectRemarkExample(document) {
 function selectRehypeExample(document) {
 	return document.querySelector('div[data-rehype-plugin-works]');
 }
+
+function selectRecmaExample(document) {
+	return document.querySelector('div[data-recma-plugin-works]');
+}