@astrojs/mdx 0.11.4 → 0.11.6

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 788a04a94f8adf80
+@astrojs/mdx:build: 
+@astrojs/mdx:build: > @astrojs/mdx@0.11.6 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,17 @@
 # @astrojs/mdx
 
+## 0.11.6
+
+### Patch Changes
+
+- [#5335](https://github.com/withastro/astro/pull/5335) [`dca762cf7`](https://github.com/withastro/astro/commit/dca762cf734a657d8f126fd6958892b6163a4f67) Thanks [@bluwy](https://github.com/bluwy)! - Preserve code element node `data.meta` in `properties.metastring` for rehype syntax highlighters, like `rehype-pretty-code``
+
+## 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:
 
@@ -193,8 +194,7 @@ export default {
 …every MDX file will have `customProperty` in its frontmatter! See [our Markdown documentation](https://docs.astro.build/en/guides/markdown-content/#injecting-frontmatter) for more usage instructions and a [reading time plugin example](https://docs.astro.build/en/guides/markdown-content/#example-calculate-reading-time).
 
 ### Layouts
-
-Layouts can be applied [in the same way as standard Astro Markdown](https://docs.astro.build/en/guides/markdown-content/#markdown-layouts). You can add a `layout` to [your frontmatter](#frontmatter) like so:
+Layouts can be applied [in the same way as standard Astro Markdown](https://docs.astro.build/en/guides/markdown-content/#frontmatter-layout). You can add a `layout` to [your frontmatter](#frontmatter) like so:
 
 ```yaml
 ---
@@ -260,6 +260,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 +287,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 +321,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 +340,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 +414,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 +433,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 +454,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 +512,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/dist/plugins.js

@@ -5,6 +5,7 @@ import rehypeRaw from "rehype-raw";
 import remarkGfm from "remark-gfm";
 import remarkSmartypants from "remark-smartypants";
 import rehypeCollectHeadings from "./rehype-collect-headings.js";
+import rehypeMetaString from "./rehype-meta-string.js";
 import remarkPrism from "./remark-prism.js";
 import remarkShiki from "./remark-shiki.js";
 import { jsToTreeNode } from "./utils.js";
@@ -119,6 +120,7 @@ async function getRemarkPlugins(mdxOptions, config) {
 function getRehypePlugins(mdxOptions, config) {
   let rehypePlugins = [
     rehypeCollectHeadings,
+    rehypeMetaString,
     [rehypeRaw, { passThrough: nodeTypes }]
   ];
   switch (mdxOptions.extendPlugins) {

package/dist/rehype-meta-string.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Moves `data.meta` to `properties.metastring` for the `code` element node
+ * as `rehype-raw` strips `data` from all nodes, which may contain useful information.
+ * e.g. ```js {1:3} => metastring: "{1:3}"
+ */
+export default function rehypeMetaString(): (tree: any) => void;

package/dist/rehype-meta-string.js

@@ -0,0 +1,15 @@
+import { visit } from "unist-util-visit";
+function rehypeMetaString() {
+  return function(tree) {
+    visit(tree, (node) => {
+      var _a;
+      if (node.type === "element" && node.tagName === "code" && ((_a = node.data) == null ? void 0 : _a.meta)) {
+        node.properties ?? (node.properties = {});
+        node.properties.metastring = node.data.meta;
+      }
+    });
+  };
+}
+export {
+  rehypeMetaString as default
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrojs/mdx",
   "description": "Use MDX within Astro",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "type": "module",
   "types": "./dist/index.d.ts",
   "author": "withastro",
@@ -23,7 +23,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@astrojs/prism": "^1.0.1",
+    "@astrojs/prism": "^1.0.2",
     "@mdx-js/mdx": "^2.1.2",
     "@mdx-js/rollup": "^2.1.1",
     "acorn": "^8.8.0",
@@ -46,8 +46,8 @@
     "@types/github-slugger": "^1.3.0",
     "@types/mocha": "^9.1.1",
     "@types/yargs-parser": "^21.0.0",
-    "astro": "1.4.3",
-    "astro-scripts": "0.0.8",
+    "astro": "1.6.6",
+    "astro-scripts": "0.0.9",
     "chai": "^4.3.6",
     "cheerio": "^1.0.0-rc.11",
     "linkedom": "^0.14.12",
@@ -55,6 +55,7 @@
     "mdast-util-to-string": "^3.1.0",
     "mocha": "^9.2.2",
     "reading-time": "^1.5.0",
+    "rehype-pretty-code": "^0.4.0",
     "remark-shiki-twoslash": "^3.1.0",
     "remark-toc": "^8.0.1",
     "vite": "^3.0.0"
@@ -66,6 +67,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,9 +65,10 @@ 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
+					// Note: disable `.md` (and other alternative extensions for markdown files like `.markdown`) support
 					format: 'mdx',
 					mdExtensions: [],
 				};
@@ -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/src/plugins.ts

@@ -11,6 +11,7 @@ import remarkSmartypants from 'remark-smartypants';
 import type { Data, VFile } from 'vfile';
 import { MdxOptions } from './index.js';
 import rehypeCollectHeadings from './rehype-collect-headings.js';
+import rehypeMetaString from './rehype-meta-string.js';
 import remarkPrism from './remark-prism.js';
 import remarkShiki from './remark-shiki.js';
 import { jsToTreeNode } from './utils.js';
@@ -150,6 +151,8 @@ export function getRehypePlugins(
 	let rehypePlugins: PluggableList = [
 		// getHeadings() is guaranteed by TS, so we can't allow user to override
 		rehypeCollectHeadings,
+		// ensure `data.meta` is preserved in `properties.metastring` for rehype syntax highlighters
+		rehypeMetaString,
 		// rehypeRaw allows custom syntax highlighters to work without added config
 		[rehypeRaw, { passThrough: nodeTypes }] as any,
 	];

package/src/rehype-meta-string.ts

@@ -0,0 +1,17 @@
+import { visit } from 'unist-util-visit';
+
+/**
+ * Moves `data.meta` to `properties.metastring` for the `code` element node
+ * as `rehype-raw` strips `data` from all nodes, which may contain useful information.
+ * e.g. ```js {1:3} => metastring: "{1:3}"
+ */
+export default function rehypeMetaString() {
+	return function (tree: any) {
+		visit(tree, (node) => {
+			if (node.type === 'element' && node.tagName === 'code' && node.data?.meta) {
+				node.properties ??= {};
+				node.properties.metastring = node.data.meta;
+			}
+		});
+	};
+}

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/fixtures/mdx-syntax-hightlighting/src/pages/index.mdx

@@ -1,6 +1,6 @@
 # Syntax highlighting
 
-```astro
+```astro {2}
 ---
 const handlesAstroSyntax = true
 ---

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]');
+}

package/test/mdx-syntax-highlighting.test.js

@@ -4,6 +4,7 @@ import { expect } from 'chai';
 import { parseHTML } from 'linkedom';
 import { loadFixture } from '../../../astro/test/test-utils.js';
 import shikiTwoslash from 'remark-shiki-twoslash';
+import rehypePrettyCode from 'rehype-pretty-code';
 
 const FIXTURE_ROOT = new URL('./fixtures/mdx-syntax-hightlighting/', import.meta.url);
 
@@ -88,4 +89,31 @@ describe('MDX syntax highlighting', () => {
 		const twoslashCodeBlock = document.querySelector('pre.shiki');
 		expect(twoslashCodeBlock).to.not.be.null;
 	});
+
+	it('supports custom highlighter - rehype-pretty-code', async () => {
+		const fixture = await loadFixture({
+			root: FIXTURE_ROOT,
+			markdown: {
+				syntaxHighlight: false,
+			},
+			integrations: [
+				mdx({
+					rehypePlugins: [
+						[
+							rehypePrettyCode,
+							{
+								onVisitHighlightedLine(node) {
+									node.properties.style = 'background-color:#000000';
+								},
+							},
+						],
+					],
+				}),
+			],
+		});
+		await fixture.build();
+
+		const html = await fixture.readFile('/index.html');
+		expect(html).to.include('style="background-color:#000000"');
+	});
 });