From 6c9736cbc90162f1de3ebccd7cfe98332749b639 Mon Sep 17 00:00:00 2001
From: Ben Holmes <hey@bholmes.dev>
Date: Mon, 8 Aug 2022 16:16:06 -0500
Subject: [PATCH] [MDX] Add frontmatter injection to README (#4205)

* docs: remove `remark-mdx-frontmatter` from README

* docs: remove remark-mdx-frontmatter link

* docs: MDX frontmatter injection

* chore: changeset
---
 .changeset/honest-bottles-drum.md   |  5 ++++
 packages/integrations/mdx/README.md | 42 +++++++++++++++++++++++++----
 2 files changed, 42 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/honest-bottles-drum.md

diff --git a/.changeset/honest-bottles-drum.md b/.changeset/honest-bottles-drum.md
new file mode 100644
index 000000000000..18da3e2c4a55
--- /dev/null
+++ b/.changeset/honest-bottles-drum.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/mdx': patch
+---
+
+Add frontmatter injection instructions to README
diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md
index 8291a3fae073..d4ad1f39d382 100644
--- a/packages/integrations/mdx/README.md
+++ b/packages/integrations/mdx/README.md
@@ -121,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. See the `frontmatterOptions` configuration to customize this behavior.
 
 For example, we can add a `title` and `publishDate` to an MDX page or component like so:
 
@@ -150,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:
@@ -310,9 +344,9 @@ export default {
 
 ### frontmatterOptions
 
-**Default:** `{ name: 'frontmatter' }`
+**Default:** `'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.
+We parse all [YAML](https://yaml.org/) frontmatter found in code fences `---` to a named export. This is `frontmatter` by default, but can be customized using `frontmatterOptions.name`.
 
 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:
 
@@ -335,8 +369,6 @@ 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.
-
 ## 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.