From 8504cd79b708e0d3bf1a2bb4ff9b86936bdd692b Mon Sep 17 00:00:00 2001
From: Kyle F Butts <buttskyle96@gmail.com>
Date: Tue, 30 Aug 2022 09:55:52 -0600
Subject: [PATCH] Add custom components to mdx integration guide (#4530)

* Add custom components to mdx integration guide

* Update packages/integrations/mdx/README.md

Co-authored-by: Ben Holmes <hey@bholmes.dev>

* Update packages/integrations/mdx/README.md

Co-authored-by: Ben Holmes <hey@bholmes.dev>

* Update packages/integrations/mdx/README.md

Co-authored-by: Ben Holmes <hey@bholmes.dev>

* Update packages/integrations/mdx/README.md

Co-authored-by: Ben Holmes <hey@bholmes.dev>

* Incorporate Sarah and Ben's Feedback

* Fix what would be an ugly background lol

* Sarah taking liberty of removing double text

* Add changeset

Co-authored-by: Ben Holmes <hey@bholmes.dev>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
---
 .changeset/kind-lobsters-leave.md   |  5 +++
 packages/integrations/mdx/README.md | 48 +++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 .changeset/kind-lobsters-leave.md

diff --git a/.changeset/kind-lobsters-leave.md b/.changeset/kind-lobsters-leave.md
new file mode 100644
index 000000000000..c2c76e6076dc
--- /dev/null
+++ b/.changeset/kind-lobsters-leave.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/mdx': patch
+---
+
+Add custom components to README
diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md
index 69fe712690ed..93c8420e6b9b 100644
--- a/packages/integrations/mdx/README.md
+++ b/packages/integrations/mdx/README.md
@@ -249,6 +249,54 @@ const { title, fancyJsHelper } = Astro.props;
 <!-- -->
 ```
 
+### Custom components
+
+Under the hood, MDX will convert Markdown into HTML components. For example, this blockquote:
+
+```md
+> A blockquote with *some* emphasis.
+```
+
+will be converted into this HTML:
+
+```html
+<blockquote>
+  <p>A blockquote with <em>some</em> emphasis.</p>
+</blockquote>
+```
+
+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">
+  <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. 
+
+```mdx title="src/pages/posts/post-1.mdx" {2}
+import Blockquote from '../components/Blockquote.astro';
+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:
+
+```astro title="src/pages/page.astro" "components={{ h1: Heading }}"
+---
+import Content from '../content.mdx';
+import Heading from '../Heading.astro';
+---
+
+<Content components={{ h1: Heading }} />
+```
+
 ### Syntax highlighting
 
 The MDX integration respects [your project's `markdown.syntaxHighlight` configuration](https://docs.astro.build/en/guides/markdown-content/#syntax-highlighting).