@astrojs/mdx 0.6.0 → 0.8.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
-@astrojs/mdx:build: cache hit, replaying output db9da5c9ed100942
-@astrojs/mdx:build: 
-@astrojs/mdx:build: > @astrojs/mdx@0.6.0 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 628f5c9b87587320
+@astrojs/mdx:build: 
+@astrojs/mdx:build: > @astrojs/mdx@0.8.1 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,36 @@
 # @astrojs/mdx
 
+## 0.8.1
+
+### Patch Changes
+
+- Updated dependencies [[`04ad44563`](https://github.com/withastro/astro/commit/04ad445632c67bdd60c1704e1e0dcbcaa27b9308)]:
+  - @astrojs/prism@1.0.0
+
+## 0.8.0
+
+### Minor Changes
+
+- [#4204](https://github.com/withastro/astro/pull/4204) [`4c2ca5352`](https://github.com/withastro/astro/commit/4c2ca5352d0c4119ed2a9e5e0b78ce71eb1b414a) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Remove `frontmatterOptions` from MDX config
+
+### Patch Changes
+
+- [#4205](https://github.com/withastro/astro/pull/4205) [`6c9736cbc`](https://github.com/withastro/astro/commit/6c9736cbc90162f1de3ebccd7cfe98332749b639) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Add frontmatter injection instructions to README
+
+## 0.7.0
+
+### Minor Changes
+
+- [#4176](https://github.com/withastro/astro/pull/4176) [`2675b8633`](https://github.com/withastro/astro/commit/2675b8633c5d5c45b237ec87940d5eaf1bfb1b4b) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Support frontmatter injection for MD and MDX using remark and rehype plugins
+
+### Patch Changes
+
+- [#4181](https://github.com/withastro/astro/pull/4181) [`77cede720`](https://github.com/withastro/astro/commit/77cede720b09bce34f29c3d2d8b505311ce876b1) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Make collect-headings rehype plugin non-overridable
+
+* [#4174](https://github.com/withastro/astro/pull/4174) [`8eb3a8c6d`](https://github.com/withastro/astro/commit/8eb3a8c6d9554707963c3a3bc36ed8b68d3cf0fb) Thanks [@matthewp](https://github.com/matthewp)! - Allows using React with automatic imports alongside MDX
+
+- [#4145](https://github.com/withastro/astro/pull/4145) [`c7efcf57e`](https://github.com/withastro/astro/commit/c7efcf57e00a0fcde3bc9f813e3cc59902bd484c) Thanks [@FredKSchott](https://github.com/FredKSchott)! - Fix a missing newline bug when `layout` was set.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -20,33 +20,30 @@ Check out [“What is MDX?”](https://mdxjs.com/docs/what-is-mdx/), a deep-dive
 
 ## Installation
 
-<details>
-  <summary>Quick Install</summary>
+### Quick Install
 
 The `astro add` command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren't sure which package manager you're using, run the first command.) Then, follow the prompts, and type "y" in the terminal (meaning "yes") for each one.
 
-  ```sh
-  # Using NPM
-  npx astro add mdx
-  # Using Yarn
-  yarn astro add mdx
-  # Using PNPM
-  pnpx astro add mdx
-  ```
+```sh
+# Using NPM
+npx astro add mdx
+# Using Yarn
+yarn astro add mdx
+# Using PNPM
+pnpx astro add mdx
+```
 
 Then, restart the dev server by typing `CTRL-C` and then `npm run astro dev` in the terminal window that was running Astro.
 
 Because this command is new, it might not properly set things up. If that happens, [feel free to log an issue on our GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.
-</details>
 
-<details>
-  <summary>Manual Install</summary>
+### Manual Install
 
 First, install the `@astrojs/mdx` package using your package manager. If you're using npm or aren't sure, run this in the terminal:
 
-  ```sh
-  npm install @astrojs/mdx
-  ```
+```sh
+npm install @astrojs/mdx
+```
 
 Then, apply this integration to your `astro.config.*` file using the `integrations` property:
 
@@ -63,11 +60,14 @@ export default defineConfig({
 ```
 
 Finally, restart the dev server.
-</details>
 
 ## Usage
 
-To write your first MDX page in Astro, head to our [UI framework documentation][astro-ui-frameworks]. You'll explore:
+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
@@ -76,8 +76,6 @@ To write your first MDX page in Astro, head to our [UI framework documentation][
 
 > **Note**: `.mdx` files adhere to strict JSX syntax rather than Astro's HTML-like syntax.
 
-Also check our [Astro Integration Documentation][astro-integration] for more on integrations.
-
 ### Variables
 
 MDX supports `export` statements to add variables to your templates. These variables are accessible both from the template itself _and_ as named properties when importing the template somewhere else.
@@ -123,7 +121,7 @@ A function that returns an array of all headings (i.e. `h1 -> h6` elements) in t
 
 ### Frontmatter
 
-Astro also supports YAML-based frontmatter out-of-the-box using the [remark-mdx-frontmatter](https://github.com/remcohaszing/remark-mdx-frontmatter) plugin. By default, all variables declared in a frontmatter fence (`---`) will be accessible via the `frontmatter` export. See the `frontmatterOptions` configuration to customize this behavior.
+Astro also supports YAML-based frontmatter out-of-the-box. By default, all variables declared in a frontmatter fence (`---`) will be accessible via the `frontmatter` export.
 
 For example, we can add a `title` and `publishDate` to an MDX page or component like so:
 
@@ -152,6 +150,40 @@ 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 can append to the `data.astro.frontmatter` property from your plugin’s `file` argument like so:
+
+```js
+// example-remark-plugin.mjs
+export function exampleRemarkPlugin() {
+  // All remark and rehype plugins return a separate function
+  return function (tree, file) {
+    file.data.astro.frontmatter.customProperty = 'Generated property';
+  }
+}
+```
+
+After applying this plugin to your MDX integration config:
+
+```js
+// astro.config.mjs
+import mdx from '@astrojs/mdx';
+import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
+
+export default {
+  integrations: [
+    mdx({
+      remarkPlugins: [exampleRemarkPlugin],
+    }),
+  ],
+};
+```
+
+…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:
@@ -255,8 +287,7 @@ This applies a minimal Prism renderer with added support for `astro` code blocks
 
 ## Configuration
 
-<details>
-  <summary><strong>remarkPlugins</strong></summary>
+### remarkPlugins
 
 **Default plugins:** [remark-gfm](https://github.com/remarkjs/remark-gfm), [remark-smartypants](https://github.com/silvenon/remark-smartypants)
 
@@ -292,31 +323,13 @@ export default {
 }
 ```
 
-</details>
-
-<details>
-  <summary><strong>rehypePlugins</strong></summary>
-
-**Default plugins:** [`collect-headings`](https://github.com/withastro/astro/blob/main/packages/integrations/mdx/src/rehype-collect-headings.ts)
+### rehypePlugins
 
 [Rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md) allow you to transform the HTML that your Markdown generates. We recommend checking the [Remark plugin](https://github.com/remarkjs/remark/blob/main/doc/plugins.md) catalog first _before_ considering rehype plugins, since most users want to transform their Markdown syntax instead. If HTML transforms are what you need, we encourage you to browse [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for a full curated list of plugins!
 
-We apply our own [`collect-headings`](https://github.com/withastro/astro/blob/main/packages/integrations/mdx/src/rehype-collect-headings.ts) plugin by default. 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).
+We apply our own (non-overridable) [`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).
 
-To apply rehype plugins _while preserving_ Astro's default plugins, use a nested `extends` object like so:
-
-```js
-// astro.config.mjs
-import rehypeMinifyHtml from 'rehype-minify';
-
-export default {
-  integrations: [mdx({
-    rehypePlugins: { extends: [rehypeMinifyHtml] },
-  })],
-}
-```
-
-To apply plugins _without_ Astro's defaults, you can apply a plain array:
+To apply additional rehype plugins, pass an array to the `rehypePlugins` option like so:
 
 ```js
 // astro.config.mjs
@@ -328,38 +341,6 @@ export default {
   })],
 }
 ```
-</details>
-
-<details>
-  <summary><strong>frontmatterOptions</strong></summary>
-
-**Default:** `{ name: 'frontmatter' }`
-
-We use [remark-mdx-frontmatter](https://github.com/remcohaszing/remark-mdx-frontmatter) to parse YAML-based frontmatter in your MDX files. If you want to override our default configuration or extend remark-mdx-frontmatter (ex. to [apply a custom frontmatter parser](https://github.com/remcohaszing/remark-mdx-frontmatter#parsers)), you can supply a `frontmatterOptions` configuration.
-
-For example, say you want to access frontmatter as root-level variables without a nested `frontmatter` object. You can override the [`name` configuration option](https://github.com/remcohaszing/remark-mdx-frontmatter#name) like so:
-
-```js
-// astro.config.mjs
-export default {
-  integrations: [mdx({
-    frontmatterOptions: {
-      name: '',
-    }
-  })],
-}
-```
-
-```mdx
----
-title: I'm just a variable now!
----
-
-# {title}
-```
-
-See the [remark-mdx-frontmatter README](https://github.com/remcohaszing/remark-mdx-frontmatter#options) for a complete list of options.
-</details>
 
 ## Examples
 

package/dist/astro-data-utils.d.ts

@@ -0,0 +1,9 @@
+import type { MarkdownAstroData } from 'astro';
+import type { Data, VFile } from 'vfile';
+export declare function remarkInitializeAstroData(): (tree: any, vfile: VFile) => void;
+export declare function rehypeApplyFrontmatterExport(pageFrontmatter: Record<string, any>): (tree: any, vfile: VFile) => void;
+/**
+ * Copied from markdown utils
+ * @see "vite-plugin-utils"
+ */
+export declare function safelyGetAstroData(vfileData: Data): MarkdownAstroData;

package/dist/astro-data-utils.js

@@ -0,0 +1,47 @@
+import { jsToTreeNode } from "./utils.js";
+function remarkInitializeAstroData() {
+  return function(tree, vfile) {
+    if (!vfile.data.astro) {
+      vfile.data.astro = { frontmatter: {} };
+    }
+  };
+}
+const EXPORT_NAME = "frontmatter";
+function rehypeApplyFrontmatterExport(pageFrontmatter) {
+  return function(tree, vfile) {
+    const { frontmatter: injectedFrontmatter } = safelyGetAstroData(vfile.data);
+    const frontmatter = { ...injectedFrontmatter, ...pageFrontmatter };
+    const exportNodes = [
+      jsToTreeNode(`export const ${EXPORT_NAME} = ${JSON.stringify(frontmatter)};`)
+    ];
+    tree.children = exportNodes.concat(tree.children);
+  };
+}
+function isValidAstroData(obj) {
+  if (typeof obj === "object" && obj !== null && obj.hasOwnProperty("frontmatter")) {
+    const { frontmatter } = obj;
+    try {
+      JSON.stringify(frontmatter);
+    } catch {
+      return false;
+    }
+    return typeof frontmatter === "object" && frontmatter !== null;
+  }
+  return false;
+}
+function safelyGetAstroData(vfileData) {
+  const { astro } = vfileData;
+  if (!astro)
+    return { frontmatter: {} };
+  if (!isValidAstroData(astro)) {
+    throw Error(
+      `[MDX] A remark or rehype plugin tried to add invalid frontmatter. Ensure "astro.frontmatter" is a JSON object!`
+    );
+  }
+  return astro;
+}
+export {
+  rehypeApplyFrontmatterExport,
+  remarkInitializeAstroData,
+  safelyGetAstroData
+};

package/dist/index.d.ts

@@ -1,18 +1,11 @@
 import { Options as MdxRollupPluginOptions } from '@mdx-js/rollup';
 import type { AstroIntegration } from 'astro';
-import type { RemarkMdxFrontmatterOptions } from 'remark-mdx-frontmatter';
 declare type WithExtends<T> = T | {
     extends: T;
 };
 declare type MdxOptions = {
     remarkPlugins?: WithExtends<MdxRollupPluginOptions['remarkPlugins']>;
     rehypePlugins?: WithExtends<MdxRollupPluginOptions['rehypePlugins']>;
-    /**
-     * Configure the remark-mdx-frontmatter plugin
-     * @see https://github.com/remcohaszing/remark-mdx-frontmatter#options for a full list of options
-     * @default {{ name: 'frontmatter' }}
-     */
-    frontmatterOptions?: RemarkMdxFrontmatterOptions;
 };
 export default function mdx(mdxOptions?: MdxOptions): AstroIntegration;
 export {};

package/dist/index.js

@@ -2,52 +2,55 @@ import { compile as mdxCompile, nodeTypes } from "@mdx-js/mdx";
 import mdxPlugin from "@mdx-js/rollup";
 import { parse as parseESM } from "es-module-lexer";
 import rehypeRaw from "rehype-raw";
-import remarkFrontmatter from "remark-frontmatter";
 import remarkGfm from "remark-gfm";
-import remarkMdxFrontmatter from "remark-mdx-frontmatter";
 import remarkShikiTwoslash from "remark-shiki-twoslash";
 import remarkSmartypants from "remark-smartypants";
 import { VFile } from "vfile";
+import { rehypeApplyFrontmatterExport, remarkInitializeAstroData } from "./astro-data-utils.js";
 import rehypeCollectHeadings from "./rehype-collect-headings.js";
 import remarkPrism from "./remark-prism.js";
-import { getFileInfo, getFrontmatter } from "./utils.js";
-const DEFAULT_REMARK_PLUGINS = [remarkGfm, remarkSmartypants];
-const DEFAULT_REHYPE_PLUGINS = [rehypeCollectHeadings];
+import { getFileInfo, parseFrontmatter } from "./utils.js";
+const DEFAULT_REMARK_PLUGINS = [
+  remarkGfm,
+  remarkSmartypants
+];
+const DEFAULT_REHYPE_PLUGINS = [];
 function handleExtends(config, defaults = []) {
   if (Array.isArray(config))
     return config;
   return [...defaults, ...(config == null ? void 0 : config.extends) ?? []];
 }
+function getRemarkPlugins(mdxOptions, config) {
+  let remarkPlugins = [
+    remarkInitializeAstroData,
+    ...handleExtends(mdxOptions.remarkPlugins, DEFAULT_REMARK_PLUGINS)
+  ];
+  if (config.markdown.syntaxHighlight === "shiki") {
+    const shikiTwoslash = remarkShikiTwoslash.default ?? remarkShikiTwoslash;
+    remarkPlugins.push([shikiTwoslash, config.markdown.shikiConfig]);
+  }
+  if (config.markdown.syntaxHighlight === "prism") {
+    remarkPlugins.push(remarkPrism);
+  }
+  return remarkPlugins;
+}
+function getRehypePlugins(mdxOptions, config) {
+  let rehypePlugins = handleExtends(mdxOptions.rehypePlugins, DEFAULT_REHYPE_PLUGINS);
+  if (config.markdown.syntaxHighlight === "shiki" || config.markdown.syntaxHighlight === "prism") {
+    rehypePlugins.push([rehypeRaw, { passThrough: nodeTypes }]);
+  }
+  rehypePlugins.push(rehypeCollectHeadings);
+  return rehypePlugins;
+}
 function mdx(mdxOptions = {}) {
   return {
     name: "@astrojs/mdx",
     hooks: {
       "astro:config:setup": ({ updateConfig, config, addPageExtension, command }) => {
         addPageExtension(".mdx");
-        let remarkPlugins = handleExtends(mdxOptions.remarkPlugins, DEFAULT_REMARK_PLUGINS);
-        let rehypePlugins = handleExtends(mdxOptions.rehypePlugins, DEFAULT_REHYPE_PLUGINS);
-        if (config.markdown.syntaxHighlight === "shiki") {
-          remarkPlugins.push([
-            remarkShikiTwoslash.default ?? remarkShikiTwoslash,
-            config.markdown.shikiConfig
-          ]);
-          rehypePlugins.push([rehypeRaw, { passThrough: nodeTypes }]);
-        }
-        if (config.markdown.syntaxHighlight === "prism") {
-          remarkPlugins.push(remarkPrism);
-          rehypePlugins.push([rehypeRaw, { passThrough: nodeTypes }]);
-        }
-        remarkPlugins.push(remarkFrontmatter);
-        remarkPlugins.push([
-          remarkMdxFrontmatter,
-          {
-            name: "frontmatter",
-            ...mdxOptions.frontmatterOptions
-          }
-        ]);
         const mdxPluginOpts = {
-          remarkPlugins,
-          rehypePlugins,
+          remarkPlugins: getRemarkPlugins(mdxOptions, config),
+          rehypePlugins: getRehypePlugins(mdxOptions, config),
           jsx: true,
           jsxImportSource: "astro",
           format: "mdx",
@@ -60,28 +63,29 @@ function mdx(mdxOptions = {}) {
                 enforce: "pre",
                 ...mdxPlugin(mdxPluginOpts),
                 async transform(code, id) {
-                  var _a;
                   if (!id.endsWith("mdx"))
                     return;
-                  if (!((_a = mdxOptions.frontmatterOptions) == null ? void 0 : _a.parsers)) {
-                    const frontmatter = getFrontmatter(code, id);
-                    if (frontmatter.layout) {
-                      const { layout, ...content } = frontmatter;
-                      code += `
+                  let { data: frontmatter, content: pageContent } = parseFrontmatter(code, id);
+                  if (frontmatter.layout) {
+                    const { layout, ...contentProp } = frontmatter;
+                    pageContent += `
+
 export default async function({ children }) {
 const Layout = (await import(${JSON.stringify(
-                        frontmatter.layout
-                      )})).default;
+                      frontmatter.layout
+                    )})).default;
 const frontmatter=${JSON.stringify(
-                        content
-                      )};
+                      contentProp
+                    )};
 return <Layout frontmatter={frontmatter} content={frontmatter} headings={getHeadings()}>{children}</Layout> }`;
-                    }
                   }
-                  const compiled = await mdxCompile(
-                    new VFile({ value: code, path: id }),
-                    mdxPluginOpts
-                  );
+                  const compiled = await mdxCompile(new VFile({ value: pageContent, path: id }), {
+                    ...mdxPluginOpts,
+                    rehypePlugins: [
+                      ...mdxPluginOpts.rehypePlugins ?? [],
+                      () => rehypeApplyFrontmatterExport(frontmatter)
+                    ]
+                  });
                   return {
                     code: String(compiled.value),
                     map: compiled.map

package/dist/utils.d.ts

@@ -1,6 +1,7 @@
 import type { Options as AcornOpts } from 'acorn';
 import type { AstroConfig } from 'astro';
 import type { MdxjsEsm } from 'mdast-util-mdx';
+import matter from 'gray-matter';
 interface FileInfo {
     fileId: string;
     fileUrl: string;
@@ -11,8 +12,6 @@ export declare function getFileInfo(id: string, config: AstroConfig): FileInfo;
  * Match YAML exception handling from Astro core errors
  * @see 'astro/src/core/errors.ts'
  */
-export declare function getFrontmatter(code: string, id: string): {
-    [key: string]: any;
-};
+export declare function parseFrontmatter(code: string, id: string): matter.GrayMatterFile<string>;
 export declare function jsToTreeNode(jsString: string, acornOpts?: AcornOpts): MdxjsEsm;
 export {};

package/dist/utils.js

@@ -27,9 +27,9 @@ function getFileInfo(id, config) {
   }
   return { fileId, fileUrl };
 }
-function getFrontmatter(code, id) {
+function parseFrontmatter(code, id) {
   try {
-    return matter(code).data;
+    return matter(code);
   } catch (e) {
     if (e.name === "YAMLException") {
       const err = e;
@@ -61,6 +61,6 @@ function jsToTreeNode(jsString, acornOpts = {
 }
 export {
   getFileInfo,
-  getFrontmatter,
-  jsToTreeNode
+  jsToTreeNode,
+  parseFrontmatter
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrojs/mdx",
   "description": "Use MDX within Astro",
-  "version": "0.6.0",
+  "version": "0.8.1",
   "type": "module",
   "types": "./dist/index.d.ts",
   "author": "withastro",
@@ -23,7 +23,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@astrojs/prism": "^0.7.0",
+    "@astrojs/prism": "^1.0.0",
     "@mdx-js/mdx": "^2.1.2",
     "@mdx-js/rollup": "^2.1.1",
     "acorn": "^8.8.0",
@@ -33,18 +33,18 @@
     "rehype-raw": "^6.1.1",
     "remark-frontmatter": "^4.0.1",
     "remark-gfm": "^3.0.1",
-    "remark-mdx-frontmatter": "^2.0.2",
     "remark-shiki-twoslash": "^3.1.0",
     "remark-smartypants": "^2.0.0",
     "shiki": "^0.10.1",
-    "unist-util-visit": "^4.1.0"
+    "unist-util-visit": "^4.1.0",
+    "vfile": "^5.3.2"
   },
   "devDependencies": {
     "@types/chai": "^4.3.1",
     "@types/mocha": "^9.1.1",
     "@types/yargs-parser": "^21.0.0",
-    "astro": "1.0.0-rc.5",
-    "astro-scripts": "0.0.6",
+    "astro": "1.0.0",
+    "astro-scripts": "0.0.7",
     "chai": "^4.3.6",
     "linkedom": "^0.14.12",
     "mdast-util-to-string": "^3.1.0",

package/src/astro-data-utils.ts

@@ -0,0 +1,59 @@
+import type { MarkdownAstroData } from 'astro';
+import type { Data, VFile } from 'vfile';
+import { jsToTreeNode } from './utils.js';
+
+export function remarkInitializeAstroData() {
+	return function (tree: any, vfile: VFile) {
+		if (!vfile.data.astro) {
+			vfile.data.astro = { frontmatter: {} };
+		}
+	};
+}
+
+const EXPORT_NAME = 'frontmatter';
+
+export function rehypeApplyFrontmatterExport(pageFrontmatter: Record<string, any>) {
+	return function (tree: any, vfile: VFile) {
+		const { frontmatter: injectedFrontmatter } = safelyGetAstroData(vfile.data);
+		const frontmatter = { ...injectedFrontmatter, ...pageFrontmatter };
+		const exportNodes = [
+			jsToTreeNode(`export const ${EXPORT_NAME} = ${JSON.stringify(frontmatter)};`),
+		];
+		tree.children = exportNodes.concat(tree.children);
+	};
+}
+
+/**
+ * Copied from markdown utils
+ * @see "vite-plugin-utils"
+ */
+function isValidAstroData(obj: unknown): obj is MarkdownAstroData {
+	if (typeof obj === 'object' && obj !== null && obj.hasOwnProperty('frontmatter')) {
+		const { frontmatter } = obj as any;
+		try {
+			// ensure frontmatter is JSON-serializable
+			JSON.stringify(frontmatter);
+		} catch {
+			return false;
+		}
+		return typeof frontmatter === 'object' && frontmatter !== null;
+	}
+	return false;
+}
+
+/**
+ * Copied from markdown utils
+ * @see "vite-plugin-utils"
+ */
+export function safelyGetAstroData(vfileData: Data): MarkdownAstroData {
+	const { astro } = vfileData;
+
+	if (!astro) return { frontmatter: {} };
+	if (!isValidAstroData(astro)) {
+		throw Error(
+			`[MDX] A remark or rehype plugin tried to add invalid frontmatter. Ensure "astro.frontmatter" is a JSON object!`
+		);
+	}
+
+	return astro;
+}

package/src/index.ts

@@ -1,35 +1,30 @@
 import { compile as mdxCompile, nodeTypes } from '@mdx-js/mdx';
 import mdxPlugin, { Options as MdxRollupPluginOptions } from '@mdx-js/rollup';
-import type { AstroIntegration } from 'astro';
+import type { AstroConfig, AstroIntegration } from 'astro';
 import { parse as parseESM } from 'es-module-lexer';
 import rehypeRaw from 'rehype-raw';
-import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
-import type { RemarkMdxFrontmatterOptions } from 'remark-mdx-frontmatter';
-import remarkMdxFrontmatter from 'remark-mdx-frontmatter';
 import remarkShikiTwoslash from 'remark-shiki-twoslash';
 import remarkSmartypants from 'remark-smartypants';
 import { VFile } from 'vfile';
 import type { Plugin as VitePlugin } from 'vite';
+import { rehypeApplyFrontmatterExport, remarkInitializeAstroData } from './astro-data-utils.js';
 import rehypeCollectHeadings from './rehype-collect-headings.js';
 import remarkPrism from './remark-prism.js';
-import { getFileInfo, getFrontmatter } from './utils.js';
+import { getFileInfo, parseFrontmatter } from './utils.js';
 
 type WithExtends<T> = T | { extends: T };
 
 type MdxOptions = {
 	remarkPlugins?: WithExtends<MdxRollupPluginOptions['remarkPlugins']>;
 	rehypePlugins?: WithExtends<MdxRollupPluginOptions['rehypePlugins']>;
-	/**
-	 * Configure the remark-mdx-frontmatter plugin
-	 * @see https://github.com/remcohaszing/remark-mdx-frontmatter#options for a full list of options
-	 * @default {{ name: 'frontmatter' }}
-	 */
-	frontmatterOptions?: RemarkMdxFrontmatterOptions;
 };
 
-const DEFAULT_REMARK_PLUGINS = [remarkGfm, remarkSmartypants];
-const DEFAULT_REHYPE_PLUGINS = [rehypeCollectHeadings];
+const DEFAULT_REMARK_PLUGINS: MdxRollupPluginOptions['remarkPlugins'] = [
+	remarkGfm,
+	remarkSmartypants,
+];
+const DEFAULT_REHYPE_PLUGINS: MdxRollupPluginOptions['rehypePlugins'] = [];
 
 function handleExtends<T>(config: WithExtends<T[] | undefined>, defaults: T[] = []): T[] {
 	if (Array.isArray(config)) return config;
@@ -37,44 +32,54 @@ function handleExtends<T>(config: WithExtends<T[] | undefined>, defaults: T[] =
 	return [...defaults, ...(config?.extends ?? [])];
 }
 
+function getRemarkPlugins(
+	mdxOptions: MdxOptions,
+	config: AstroConfig
+): MdxRollupPluginOptions['remarkPlugins'] {
+	let remarkPlugins = [
+		// Initialize vfile.data.astroExports before all plugins are run
+		remarkInitializeAstroData,
+		...handleExtends(mdxOptions.remarkPlugins, DEFAULT_REMARK_PLUGINS),
+	];
+	if (config.markdown.syntaxHighlight === 'shiki') {
+		// Default export still requires ".default" chaining for some reason
+		// Workarounds tried:
+		// - "import * as remarkShikiTwoslash"
+		// - "import { default as remarkShikiTwoslash }"
+		const shikiTwoslash = (remarkShikiTwoslash as any).default ?? remarkShikiTwoslash;
+		remarkPlugins.push([shikiTwoslash, config.markdown.shikiConfig]);
+	}
+	if (config.markdown.syntaxHighlight === 'prism') {
+		remarkPlugins.push(remarkPrism);
+	}
+	return remarkPlugins;
+}
+
+function getRehypePlugins(
+	mdxOptions: MdxOptions,
+	config: AstroConfig
+): MdxRollupPluginOptions['rehypePlugins'] {
+	let rehypePlugins = handleExtends(mdxOptions.rehypePlugins, DEFAULT_REHYPE_PLUGINS);
+
+	if (config.markdown.syntaxHighlight === 'shiki' || config.markdown.syntaxHighlight === 'prism') {
+		rehypePlugins.push([rehypeRaw, { passThrough: nodeTypes }]);
+	}
+	// getHeadings() is guaranteed by TS, so we can't allow user to override
+	rehypePlugins.push(rehypeCollectHeadings);
+
+	return rehypePlugins;
+}
+
 export default function mdx(mdxOptions: MdxOptions = {}): AstroIntegration {
 	return {
 		name: '@astrojs/mdx',
 		hooks: {
 			'astro:config:setup': ({ updateConfig, config, addPageExtension, command }: any) => {
 				addPageExtension('.mdx');
-				let remarkPlugins = handleExtends(mdxOptions.remarkPlugins, DEFAULT_REMARK_PLUGINS);
-				let rehypePlugins = handleExtends(mdxOptions.rehypePlugins, DEFAULT_REHYPE_PLUGINS);
-
-				if (config.markdown.syntaxHighlight === 'shiki') {
-					remarkPlugins.push([
-						// Default export still requires ".default" chaining for some reason
-						// Workarounds tried:
-						// - "import * as remarkShikiTwoslash"
-						// - "import { default as remarkShikiTwoslash }"
-						(remarkShikiTwoslash as any).default ?? remarkShikiTwoslash,
-						config.markdown.shikiConfig,
-					]);
-					rehypePlugins.push([rehypeRaw, { passThrough: nodeTypes }]);
-				}
-
-				if (config.markdown.syntaxHighlight === 'prism') {
-					remarkPlugins.push(remarkPrism);
-					rehypePlugins.push([rehypeRaw, { passThrough: nodeTypes }]);
-				}
-
-				remarkPlugins.push(remarkFrontmatter);
-				remarkPlugins.push([
-					remarkMdxFrontmatter,
-					{
-						name: 'frontmatter',
-						...mdxOptions.frontmatterOptions,
-					},
-				]);
 
 				const mdxPluginOpts: MdxRollupPluginOptions = {
-					remarkPlugins,
-					rehypePlugins,
+					remarkPlugins: getRemarkPlugins(mdxOptions, config),
+					rehypePlugins: getRehypePlugins(mdxOptions, config),
 					jsx: true,
 					jsxImportSource: 'astro',
 					// Note: disable `.md` support
@@ -93,24 +98,23 @@ export default function mdx(mdxOptions: MdxOptions = {}): AstroIntegration {
 								async transform(code, id) {
 									if (!id.endsWith('mdx')) return;
 
-									// If user overrides our default YAML parser,
-									// do not attempt to parse the `layout` via gray-matter
-									if (!mdxOptions.frontmatterOptions?.parsers) {
-										const frontmatter = getFrontmatter(code, id);
-										if (frontmatter.layout) {
-											const { layout, ...content } = frontmatter;
-											code += `\nexport default async function({ children }) {\nconst Layout = (await import(${JSON.stringify(
-												frontmatter.layout
-											)})).default;\nconst frontmatter=${JSON.stringify(
-												content
-											)};\nreturn <Layout frontmatter={frontmatter} content={frontmatter} headings={getHeadings()}>{children}</Layout> }`;
-										}
+									let { data: frontmatter, content: pageContent } = parseFrontmatter(code, id);
+									if (frontmatter.layout) {
+										const { layout, ...contentProp } = frontmatter;
+										pageContent += `\n\nexport default async function({ children }) {\nconst Layout = (await import(${JSON.stringify(
+											frontmatter.layout
+										)})).default;\nconst frontmatter=${JSON.stringify(
+											contentProp
+										)};\nreturn <Layout frontmatter={frontmatter} content={frontmatter} headings={getHeadings()}>{children}</Layout> }`;
 									}
 
-									const compiled = await mdxCompile(
-										new VFile({ value: code, path: id }),
-										mdxPluginOpts
-									);
+									const compiled = await mdxCompile(new VFile({ value: pageContent, path: id }), {
+										...mdxPluginOpts,
+										rehypePlugins: [
+											...(mdxPluginOpts.rehypePlugins ?? []),
+											() => rehypeApplyFrontmatterExport(frontmatter),
+										],
+									});
 
 									return {
 										code: String(compiled.value),

package/src/utils.ts

@@ -47,9 +47,9 @@ export function getFileInfo(id: string, config: AstroConfig): FileInfo {
  * Match YAML exception handling from Astro core errors
  * @see 'astro/src/core/errors.ts'
  */
-export function getFrontmatter(code: string, id: string) {
+export function parseFrontmatter(code: string, id: string) {
 	try {
-		return matter(code).data;
+		return matter(code);
 	} catch (e: any) {
 		if (e.name === 'YAMLException') {
 			const err: SSRError = e;

package/test/fixtures/mdx-escape/src/components/Em.astro

@@ -0,0 +1,7 @@
+<em><slot/></em>
+
+<style>
+  em {
+    color: red;
+  }
+</style>

package/test/fixtures/mdx-escape/src/components/P.astro

@@ -0,0 +1 @@
+<p><slot /></p>

package/test/fixtures/mdx-escape/src/components/Title.astro

@@ -0,0 +1 @@
+<h1><slot/></h1>

package/test/fixtures/mdx-escape/src/pages/html-tag.mdx

@@ -0,0 +1,5 @@
+import P from '../components/P.astro';
+import Em from '../components/Em.astro';
+
+<P>Render <Em>Me</Em></P>
+<P><Em>Me</Em></P>

package/test/fixtures/mdx-escape/src/pages/index.mdx

@@ -0,0 +1,13 @@
+import P from '../components/P.astro';
+import Em from '../components/Em.astro';
+import Title from '../components/Title.astro';
+
+export const components = { p: P, em: Em, h1: Title };
+
+# Hello _there_
+
+# _there_
+
+Hello _there_
+
+_there_

package/test/fixtures/mdx-frontmatter/src/pages/index.mdx

@@ -5,3 +5,6 @@ illThrowIfIDontExist: "Oh no, that's scary!"
 ---
 
 {frontmatter.illThrowIfIDontExist}
+
+> Note: newline intentionally missing from the end of this file.
+> Useful since that can be the source of bugs in our compile step.

package/test/fixtures/mdx-frontmatter-injection/astro.config.mjs

@@ -0,0 +1,12 @@
+import { defineConfig } from 'astro/config';
+import mdx from '@astrojs/mdx';
+import { rehypeReadingTime, remarkTitle } from './src/markdown-plugins.mjs';
+
+// https://astro.build/config
+export default defineConfig({
+  site: 'https://astro.build/',
+	integrations: [mdx({
+		remarkPlugins: [remarkTitle],
+		rehypePlugins: [rehypeReadingTime],
+	})],
+});

package/test/fixtures/mdx-frontmatter-injection/node_modules/.bin/astro

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/astro/astro/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="$NODE_PATH:/home/runner/work/astro/astro/node_modules/.pnpm/node_modules"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../../../../../../../astro/astro.js" "$@"
+else
+  exec node  "$basedir/../../../../../../../astro/astro.js" "$@"
+fi

package/test/fixtures/mdx-frontmatter-injection/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@test/mdx-frontmatter-injection",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "astro": "workspace:*",
+    "@astrojs/mdx": "workspace:*",
+    "mdast-util-to-string": "^3.1.0",
+    "reading-time": "^1.5.0",
+    "unist-util-visit": "^4.1.0"
+  }
+}

package/test/fixtures/mdx-frontmatter-injection/src/markdown-plugins.mjs

@@ -0,0 +1,20 @@
+import getReadingTime from 'reading-time';
+import { toString } from 'mdast-util-to-string';
+import { visit } from 'unist-util-visit';
+
+export function rehypeReadingTime() {
+	return function (tree, { data }) {
+		const readingTime = getReadingTime(toString(tree));
+		data.astro.frontmatter.injectedReadingTime = readingTime;
+	};
+}
+
+export function remarkTitle() {
+	return function (tree, { data }) {
+		visit(tree, ['heading'], (node) => {
+			if (node.depth === 1) {
+				data.astro.frontmatter.title = toString(node.children);
+			}
+		});
+	};
+}

package/test/fixtures/mdx-frontmatter-injection/src/pages/glob.json.js

@@ -0,0 +1,6 @@
+export async function get() {
+	const docs = await import.meta.glob('./*.mdx', { eager: true });
+	return {
+		body: JSON.stringify(Object.values(docs).map(doc => doc.frontmatter)),
+	}
+}

package/test/fixtures/mdx-frontmatter-injection/src/pages/page-1.mdx

@@ -0,0 +1,3 @@
+# Page 1
+
+Look at that!

package/test/fixtures/mdx-frontmatter-injection/src/pages/page-2.mdx

@@ -0,0 +1,19 @@
+# Page 2
+
+## Table of contents
+
+## Section 1
+
+Some text!
+
+### Subsection 1
+
+Some subsection test!
+
+### Subsection 2
+
+Oh cool, more text!
+
+## Section 2
+
+More content

package/test/fixtures/mdx-frontmatter-injection/src/pages/with-overrides.mdx

@@ -0,0 +1,7 @@
+---
+title: 'Overridden title'
+injectedReadingTime: 
+  text: '1000 min read'
+---
+
+# Working!

package/test/fixtures/mdx-plus-react/astro.config.mjs

@@ -0,0 +1,6 @@
+import mdx from '@astrojs/mdx';
+import react from '@astrojs/react';
+
+export default {
+	integrations: [react(), mdx()]
+}

package/test/fixtures/mdx-plus-react/node_modules/.bin/astro

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/astro/astro/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="$NODE_PATH:/home/runner/work/astro/astro/node_modules/.pnpm/node_modules"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../../../../../../../astro/astro.js" "$@"
+else
+  exec node  "$basedir/../../../../../../../astro/astro.js" "$@"
+fi

package/test/fixtures/mdx-plus-react/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@test/mdx-plus-react",
+  "dependencies": {
+    "astro": "workspace:*",
+    "@astrojs/mdx": "workspace:*",
+    "@astrojs/react": "workspace:*"
+  }
+}

package/test/fixtures/mdx-plus-react/src/components/Component.jsx

@@ -0,0 +1,5 @@
+const Component = () => {
+  return <p>Hello world</p>;
+};
+
+export default Component;

package/test/fixtures/mdx-plus-react/src/pages/index.astro

@@ -0,0 +1,11 @@
+---
+import Component from "../components/Component.jsx";
+---
+<html>
+	<head>
+		<title>Testing</title>
+	</head>
+	<body>
+		<Component />
+	</body>
+</html>

package/test/fixtures/mdx-rehype-plugins/src/pages/reading-time.json.js

@@ -1,7 +1,7 @@
-import { readingTime } from './space-ipsum.mdx';
+import * as exps from './space-ipsum.mdx';
 
 export function get() {
 	return {
-		body: JSON.stringify(readingTime),
+		body: JSON.stringify(exps),
 	}
 }

package/test/fixtures/mdx-remark-plugins/src/pages/headings-glob.json.js

@@ -0,0 +1,6 @@
+export async function get() {
+	const docs = await import.meta.glob('./*.mdx', { eager: true });
+	return {
+		body: JSON.stringify(Object.values(docs).map(doc => doc.frontmatter)),
+	}
+}

package/test/mdx-escape.test.js

@@ -0,0 +1,32 @@
+import mdx from '@astrojs/mdx';
+
+import { expect } from 'chai';
+import { parseHTML } from 'linkedom';
+import { loadFixture } from '../../../astro/test/test-utils.js';
+
+const FIXTURE_ROOT = new URL('./fixtures/mdx-escape/', import.meta.url);
+
+describe('MDX frontmatter', () => {
+	let fixture;
+	before(async () => {
+		fixture = await loadFixture({
+			root: FIXTURE_ROOT,
+			integrations: [mdx()],
+		});
+		await fixture.build();
+	});
+
+	it('does not have unescaped HTML at top-level', async () => {
+		const html = await fixture.readFile('/index.html');
+		const { document } = parseHTML(html);
+
+		expect(document.body.textContent).to.not.include('<em');
+	});
+
+	it('does not have unescaped HTML inside html tags', async () => {
+		const html = await fixture.readFile('/html-tag/index.html');
+		const { document } = parseHTML(html);
+
+		expect(document.body.textContent).to.not.include('<em');
+	});
+});

package/test/mdx-frontmatter-injection.test.js

@@ -0,0 +1,44 @@
+import { expect } from 'chai';
+import { loadFixture } from '../../../astro/test/test-utils.js';
+
+const FIXTURE_ROOT = new URL('./fixtures/mdx-frontmatter-injection/', import.meta.url);
+
+describe('MDX frontmatter injection', () => {
+	let fixture;
+
+	before(async () => {
+		fixture = await loadFixture({
+			root: FIXTURE_ROOT,
+		});
+		await fixture.build();
+	});
+
+	it('remark supports custom vfile data - get title', async () => {
+		const frontmatterByPage = JSON.parse(await fixture.readFile('/glob.json'));
+		const titles = frontmatterByPage.map((frontmatter = {}) => frontmatter.title);
+		expect(titles).to.contain('Page 1');
+		expect(titles).to.contain('Page 2');
+	});
+
+	it('rehype supports custom vfile data - reading time', async () => {
+		const frontmatterByPage = JSON.parse(await fixture.readFile('/glob.json'));
+		const readingTimes = frontmatterByPage.map(
+			(frontmatter = {}) => frontmatter.injectedReadingTime
+		);
+		expect(readingTimes.length).to.be.greaterThan(0);
+		for (let readingTime of readingTimes) {
+			expect(readingTime).to.not.be.null;
+			expect(readingTime.text).match(/^\d+ min read/);
+		}
+	});
+
+	it('overrides injected frontmatter with user frontmatter', async () => {
+		const frontmatterByPage = JSON.parse(await fixture.readFile('/glob.json'));
+		const readingTimes = frontmatterByPage.map(
+			(frontmatter = {}) => frontmatter.injectedReadingTime?.text
+		);
+		const titles = frontmatterByPage.map((frontmatter = {}) => frontmatter.title);
+		expect(titles).to.contain('Overridden title');
+		expect(readingTimes).to.contain('1000 min read');
+	});
+});

package/test/mdx-frontmatter.test.js

@@ -56,21 +56,4 @@ describe('MDX frontmatter', () => {
 		expect(headingSlugs).to.contain('section-1');
 		expect(headingSlugs).to.contain('section-2');
 	});
-
-	it('extracts frontmatter to "customFrontmatter" export when configured', async () => {
-		const customFixture = await loadFixture({
-			root: new URL('./fixtures/mdx-custom-frontmatter-name/', import.meta.url),
-			integrations: [
-				mdx({
-					frontmatterOptions: {
-						name: 'customFrontmatter',
-					},
-				}),
-			],
-		});
-		await customFixture.build();
-
-		const { titles } = JSON.parse(await customFixture.readFile('/glob.json'));
-		expect(titles).to.include('Using YAML frontmatter');
-	});
 });

package/test/mdx-plus-react.test.js

@@ -0,0 +1,25 @@
+import mdx from '@astrojs/mdx';
+
+import { expect } from 'chai';
+import { parseHTML } from 'linkedom';
+import { loadFixture } from '../../../astro/test/test-utils.js';
+
+describe('MDX and React', () => {
+	let fixture;
+
+	before(async () => {
+		fixture = await loadFixture({
+			root: new URL('./fixtures/mdx-plus-react/', import.meta.url),
+		});
+		await fixture.build();
+	});
+
+	it('can be used in the same project', async () => {
+		const html = await fixture.readFile('/index.html');
+		const { document } = parseHTML(html);
+
+		const p = document.querySelector('p');
+
+		expect(p.textContent).to.equal('Hello world');
+	});
+});

package/test/mdx-rehype-plugins.test.js

@@ -1,15 +1,15 @@
 import mdx from '@astrojs/mdx';
-import { jsToTreeNode } from '../dist/utils.js';
 
-import { expect } from 'chai';
-import { parseHTML } from 'linkedom';
 import getReadingTime from 'reading-time';
 import { toString } from 'mdast-util-to-string';
+import { expect } from 'chai';
+import { parseHTML } from 'linkedom';
+import { jsToTreeNode } from '../dist/utils.js';
 
 import { loadFixture } from '../../../astro/test/test-utils.js';
 
-export function rehypeReadingTime() {
-	return function (tree) {
+function rehypeReadingTime() {
+	return function (tree, { data }) {
 		const readingTime = getReadingTime(toString(tree));
 		tree.children.unshift(
 			jsToTreeNode(`export const readingTime = ${JSON.stringify(readingTime)}`)
@@ -34,19 +34,8 @@ describe('MDX rehype plugins', () => {
 			await fixture.build();
 		});
 
-		it('removes default getHeadings', async () => {
-			const html = await fixture.readFile('/space-ipsum/index.html');
-			const { document } = parseHTML(html);
-
-			const headings = [...document.querySelectorAll('h1, h2')];
-			expect(headings.length).to.be.greaterThan(0);
-			for (const heading of headings) {
-				expect(heading.id).to.be.empty;
-			}
-		});
-
 		it('supports custom rehype plugins - reading time', async () => {
-			const readingTime = JSON.parse(await fixture.readFile('/reading-time.json'));
+			const { readingTime } = JSON.parse(await fixture.readFile('/reading-time.json'));
 
 			expect(readingTime).to.not.be.null;
 			expect(readingTime.text).to.match(/^\d+ min read/);

package/test/fixtures/mdx-custom-frontmatter-name/src/pages/glob.json.js

@@ -1,9 +0,0 @@
-export async function get() {
-	const mdxPages = await import.meta.glob('./*.mdx', { eager: true });
-
-	return {
-		body: JSON.stringify({
-			titles: Object.values(mdxPages ?? {}).map(v => v?.customFrontmatter?.title),
-		})
-	}
-}

package/test/fixtures/mdx-custom-frontmatter-name/src/pages/index.mdx

@@ -1,6 +0,0 @@
----
-title: 'Using YAML frontmatter'
-illThrowIfIDontExist: "Oh no, that's scary!"
----
-
-# {customFrontmatter.illThrowIfIDontExist}