From 5fbd9598f870c40f940fad9f32b5197127ed1646 Mon Sep 17 00:00:00 2001 From: Kyle F Butts Date: Mon, 29 Aug 2022 06:57:51 -0600 Subject: [PATCH 1/9] Add custom components to mdx integration guide --- packages/integrations/mdx/README.md | 38 +++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index 69fe712690ed..ae73289b705d 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -249,6 +249,44 @@ const { title, fancyJsHelper } = Astro.props; ``` +### Custom components + +Under the hood, MDX will convert markdown into html components. For example, + +```md +> A blockquote with *some* emphasis. +``` + +will be converted into + +```html +
+

A blockquote with some emphasis.

+
+``` + +MDX provides a way to tap into this rendering and use your own custom components. In the above example, you could create a custom Blockquote component (in any language) that has either a `` component or accepts a `children` prop. Then in the MDX file you import the component and export it to the `components` export. + +```mdx +import Blockquote from '../components/Blockquote.astro'; +export const components = { blockquote: Blockquote }; +``` + +The advantage of this is it allows for the simplicity of writing in markdown without having to write the custom component or writing a remark/rehype plugin. A full list of components that can have custom components is on the [MDX website](https://mdxjs.com/table-of-components/). + +#### Custom components with imported `mdx` + +Custom components can also be passed to the components prop when rending imported MDX content. + +```astro +--- +import Content from '../content.mdx'; +import Heading from '../Heading.astro'; +--- + + +``` + ### Syntax highlighting The MDX integration respects [your project's `markdown.syntaxHighlight` configuration](https://docs.astro.build/en/guides/markdown-content/#syntax-highlighting). From 79fdee8b5be7ecee719def5bde5660ae1e26bbb5 Mon Sep 17 00:00:00 2001 From: Kyle F Butts Date: Mon, 29 Aug 2022 10:20:41 -0600 Subject: [PATCH 2/9] Update packages/integrations/mdx/README.md Co-authored-by: Ben Holmes --- packages/integrations/mdx/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index ae73289b705d..2f1309b399c6 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -276,7 +276,7 @@ The advantage of this is it allows for the simplicity of writing in markdown wit #### Custom components with imported `mdx` -Custom components can also be passed to the components prop when rending imported MDX content. +When rendering imported MDX content, custom components can also be passed via the `components` prop: ```astro --- From 946119ed838c5d61a4a686db6f9ba374a334d66b Mon Sep 17 00:00:00 2001 From: Kyle F Butts Date: Mon, 29 Aug 2022 10:20:51 -0600 Subject: [PATCH 3/9] Update packages/integrations/mdx/README.md Co-authored-by: Ben Holmes --- packages/integrations/mdx/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index 2f1309b399c6..ed56bc519e67 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -272,7 +272,7 @@ import Blockquote from '../components/Blockquote.astro'; export const components = { blockquote: Blockquote }; ``` -The advantage of this is it allows for the simplicity of writing in markdown without having to write the custom component or writing a remark/rehype plugin. A full list of components that can have custom components is on the [MDX website](https://mdxjs.com/table-of-components/). +The advantage of this is it allows for the simplicity of writing in markdown without having to write the custom component or writing a remark/rehype plugin. Visit the [MDX website](https://mdxjs.com/table-of-components/) for a full list of HTML elements that support custom components. #### Custom components with imported `mdx` From 26fa3505419c6eef4d30c6efe6c340e6770b45d3 Mon Sep 17 00:00:00 2001 From: Kyle F Butts Date: Mon, 29 Aug 2022 10:20:56 -0600 Subject: [PATCH 4/9] Update packages/integrations/mdx/README.md Co-authored-by: Ben Holmes --- packages/integrations/mdx/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index ed56bc519e67..8ca59c126ff9 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -251,7 +251,7 @@ const { title, fancyJsHelper } = Astro.props; ### Custom components -Under the hood, MDX will convert markdown into html components. For example, +Under the hood, MDX will convert markdown into html components. For example, this blockquote: ```md > A blockquote with *some* emphasis. From 5dbc702a47bcefd16d30979c28f9f63d9c8c5fc1 Mon Sep 17 00:00:00 2001 From: Kyle F Butts Date: Mon, 29 Aug 2022 10:21:02 -0600 Subject: [PATCH 5/9] Update packages/integrations/mdx/README.md Co-authored-by: Ben Holmes --- packages/integrations/mdx/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index 8ca59c126ff9..154c0f1d12b6 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -257,7 +257,7 @@ Under the hood, MDX will convert markdown into html components. For example, thi > A blockquote with *some* emphasis. ``` -will be converted into +will be converted into this HTML: ```html
From 6958fddcab5bc8250b72b087ae0bfc2d1dba785f Mon Sep 17 00:00:00 2001 From: Kyle Butts Date: Tue, 30 Aug 2022 07:58:13 -0600 Subject: [PATCH 6/9] Incorporate Sarah and Ben's Feedback --- packages/integrations/mdx/README.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index 154c0f1d12b6..d153599efee8 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -251,7 +251,7 @@ const { title, fancyJsHelper } = Astro.props; ### Custom components -Under the hood, MDX will convert markdown into html components. For example, this blockquote: +Under the hood, MDX will convert Markdown into HTML components. For example, this blockquote: ```md > A blockquote with *some* emphasis. @@ -265,20 +265,30 @@ will be converted into this HTML:
``` -MDX provides a way to tap into this rendering and use your own custom components. In the above example, you could create a custom Blockquote component (in any language) that has either a `` component or accepts a `children` prop. Then in the MDX file you import the component and export it to the `components` export. +But what if you want to specify your own markup for these blockquotes? In the above example, you could create a custom `
` component (in any language) that has either a `` component or accepts a `children` prop. MDX provides a way to tap into this rendering and use your own custom components. In the above example, you could create a custom Blockquote component (in any language) that has either a `` component or accepts a `children` prop. -```mdx +```astro title="src/components/Blockquote.astro" +
+ “ + +
+``` + +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 }; ``` -The advantage of this is it allows for the simplicity of writing in markdown without having to write the custom component or writing a remark/rehype plugin. Visit the [MDX website](https://mdxjs.com/table-of-components/) for a full list of HTML elements that support custom components. +Now, writing the standard Markdown blockquote syntax (`>`) will use your custom `
` 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 +```astro title="src/pages/page.astro" "components={{ h1: Heading }}" --- import Content from '../content.mdx'; import Heading from '../Heading.astro'; From 6c8059115d135f31120ccf5414d641c377b20602 Mon Sep 17 00:00:00 2001 From: Kyle Butts Date: Tue, 30 Aug 2022 08:01:01 -0600 Subject: [PATCH 7/9] Fix what would be an ugly background lol --- packages/integrations/mdx/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index d153599efee8..1b9ecb93fafb 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -268,7 +268,7 @@ will be converted into this HTML: But what if you want to specify your own markup for these blockquotes? In the above example, you could create a custom `
` component (in any language) that has either a `` component or accepts a `children` prop. MDX provides a way to tap into this rendering and use your own custom components. In the above example, you could create a custom Blockquote component (in any language) that has either a `` component or accepts a `children` prop. ```astro title="src/components/Blockquote.astro" -
+
“
From 1ba4b3e7b6b40f778909d6dec181b19a1d61f98b Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 30 Aug 2022 12:08:48 -0300 Subject: [PATCH 8/9] Sarah taking liberty of removing double text --- packages/integrations/mdx/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index 1b9ecb93fafb..93c8420e6b9b 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -265,7 +265,7 @@ will be converted into this HTML:
``` -But what if you want to specify your own markup for these blockquotes? In the above example, you could create a custom `
` component (in any language) that has either a `` component or accepts a `children` prop. MDX provides a way to tap into this rendering and use your own custom components. In the above example, you could create a custom Blockquote component (in any language) that has either a `` component or accepts a `children` prop. +But what if you want to specify your own markup for these blockquotes? In the above example, you could create a custom `
` component (in any language) that either has a `` component or accepts a `children` prop. ```astro title="src/components/Blockquote.astro"
From 27c7a8411e9b4568cb674850ac28ac3121541058 Mon Sep 17 00:00:00 2001 From: Kyle Butts Date: Tue, 30 Aug 2022 09:47:48 -0600 Subject: [PATCH 9/9] Add changeset --- .changeset/kind-lobsters-leave.md | 5 +++++ 1 file changed, 5 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