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 <[email protected]> * Update packages/integrations/mdx/README.md Co-authored-by: Ben Holmes <[email protected]> * Update packages/integrations/mdx/README.md Co-authored-by: Ben Holmes <[email protected]> * Update packages/integrations/mdx/README.md Co-authored-by: Ben Holmes <[email protected]> * 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 <[email protected]> Co-authored-by: Sarah Rainsberger <[email protected]>
withastro · Aug 30, 2022 · 8504cd7 · 8504cd7
1 parent 65cc3f6
commit 8504cd7
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 0 deletions.
diff --git a/.changeset/kind-lobsters-leave.md 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
@@ -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).