michael/astro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add custom components to mdx integration guide (#4530)

Browse source 
* 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>
This commit is contained in:
Kyle F Butts 2022-08-30 09:55:52 -06:00 committed by GitHub
parent 65cc3f64f6
commit 8504cd79b7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 53 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
.changeset/kind-lobsters-leave.md Normal file
View file

@ -0,0 +1,5 @@
---
'@astrojs/mdx': patch
---
Add custom components to README

48
packages/integrations/mdx/README.md
View file

@ -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).