diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index efb5f3b19..7b2662281 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -71,11 +71,12 @@ Finally, restart the dev server. ## Usage -You can [add MDX pages to your project](https://docs.astro.build/en/guides/markdown-content/#markdown-and-mdx-pages) by adding `.mdx` files within your `src/pages/` directory. +You can [add MDX pages to your project](https://docs.astro.build/en/guides/markdown-content/#markdown-and-mdx-pages) by adding `.mdx` files within your `src/pages/` directory. ### Components To use components in your MDX pages in Astro, head to our [UI framework documentation][astro-ui-frameworks]. You'll explore: + - 📦 how framework components are loaded, - 💧 client-side hydration options, and - 🤝 opportunities to mix and nest frameworks together @@ -160,7 +161,7 @@ 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 may want to inject frontmatter properties across all of your MDX files. By using a [remark](#remarkplugins) or [rehype](#rehypeplugins) 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: @@ -260,6 +261,7 @@ const { frontmatter, url } = Astro.props; #### Layout props All [exported properties](#exported-properties) are available from `Astro.props` in your layout, **with two key differences:** + - Heading information (i.e. `h1 -> h6` elements) is available via the `headings` array, rather than a `getHeadings()` function. - `file` and `url` are _also_ available as nested `frontmatter` properties (i.e. `frontmatter.url` and `frontmatter.file`). This is consistent with Astro's Markdown layout properties. @@ -286,6 +288,7 @@ function fancyJsHelper() { Welcome to my new Astro blog, using MDX! ``` + Then, your values are available to you through `Astro.props` in your layout, and your MDX content will be injected into the page where your `` component is written: ```astro @@ -329,7 +332,7 @@ const props = Astro.props; ``` -Then in the MDX file you import the component and export it to the `components` export. +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'; @@ -338,18 +341,19 @@ export const components = { blockquote: Blockquote }; 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: +When rendering imported MDX content, custom components can be passed via the `components` prop. -```astro title="src/pages/page.astro" "components={{ h1: Heading }}" +Note: An MDX file's exported components will _not_ be used unless you manually import and pass them via the `components` property. See the example below: + +```astro title="src/pages/page.astro" "components={{...components, h1: Heading }}" --- -import Content from '../content.mdx'; +import { Content, components } from '../content.mdx'; import Heading from '../Heading.astro'; --- - + ``` ### Syntax highlighting @@ -411,7 +415,7 @@ export default { [Remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md) allow you to extend your Markdown with new capabilities. This includes [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and more. We encourage you to browse [awesome-remark](https://github.com/remarkjs/awesome-remark) for a full curated list! -This example applies the [`remark-toc`](https://github.com/remarkjs/remark-toc) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendPlugins). +This example applies the [`remark-toc`](https://github.com/remarkjs/remark-toc) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendplugins). ```js // astro.config.mjs @@ -430,7 +434,7 @@ export default { We apply our own (non-removable) [`collect-headings`](https://github.com/withastro/astro/blob/main/packages/integrations/mdx/src/rehype-collect-headings.ts) plugin. This applies IDs to all headings (i.e. `h1 -> h6`) in your MDX files to [link to headings via anchor tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#linking_to_an_element_on_the_same_page). -This example applies the [`rehype-minify`](https://github.com/rehypejs/rehype-minify) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendPlugins). +This example applies the [`rehype-minify`](https://github.com/rehypejs/rehype-minify) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendplugins). ```js // astro.config.mjs @@ -451,7 +455,7 @@ export default { #### `markdown` (default) -By default, Astro inherits all [remark](#remarkPlugins) and [rehype](#rehypePlugins) plugins from [the `markdown` option in your Astro config](https://docs.astro.build/en/guides/markdown-content/#markdown-plugins). This also respects the [`markdown.extendDefaultPlugins`](https://docs.astro.build/en/reference/configuration-reference/#markdownextenddefaultplugins) option to extend Astro's defaults. Any additional plugins you apply in your MDX config will be applied _after_ your configured Markdown plugins. +By default, Astro inherits all [remark](#remarkplugins) and [rehype](#rehypeplugins) plugins from [the `markdown` option in your Astro config](https://docs.astro.build/en/guides/markdown-content/#markdown-plugins). This also respects the [`markdown.extendDefaultPlugins`](https://docs.astro.build/en/reference/configuration-reference/#markdownextenddefaultplugins) option to extend Astro's defaults. Any additional plugins you apply in your MDX config will be applied _after_ your configured Markdown plugins. This example applies [`remark-toc`](https://github.com/remarkjs/remark-toc) to Markdown _and_ MDX, and [`rehype-minify`](https://github.com/rehypejs/rehype-minify) to MDX alone: