From 582c0eeeedb4cf811ec41e23769f27cadee0ede5 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 7 Sep 2024 19:38:14 -0300 Subject: [PATCH] [mdx] Adds usage information, taken out of the Markdown guide (#9337) Co-authored-by: Armand Philippot --- .../docs/en/guides/integrations-guide/mdx.mdx | 125 +++++++++++++++++- .../docs/en/guides/troubleshooting.mdx | 6 + 2 files changed, 126 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/mdx.mdx b/src/content/docs/en/guides/integrations-guide/mdx.mdx index d9f67d2035f8b..4314e339b8a46 100644 --- a/src/content/docs/en/guides/integrations-guide/mdx.mdx +++ b/src/content/docs/en/guides/integrations-guide/mdx.mdx @@ -14,7 +14,7 @@ This **[Astro integration][astro-integration]** enables the usage of [MDX](https ## Why MDX? -MDX allows you to [use variables, JSX expressions and components within Markdown content](/en/guides/markdown-content/#mdx-only-features) in Astro. If you have existing content authored in MDX, this integration allows you to bring those files to your Astro project. +MDX allows you to use variables, JSX expressions and components within Markdown content in Astro. If you have existing content authored in MDX, this integration allows you to bring those files to your Astro project. ## Installation @@ -84,13 +84,128 @@ For other editors, use the [MDX language server](https://github.com/mdx-js/mdx-a ## Usage -With the Astro MDX integration, you can [add MDX pages to your project](/en/guides/markdown-content/#markdown-and-mdx-pages) by adding `.mdx` files within your `src/pages/` directory. You can also [import `.mdx` files](/en/guides/markdown-content/#importing-markdown) into `.astro` files. +Visit the [MDX docs](https://mdxjs.com/docs/what-is-mdx/) to learn about using standard MDX features. -Astro's MDX integration adds extra features to standard MDX, including Markdown-style frontmatter. This allows you to use most of Astro's built-in Markdown features like a [special frontmatter `layout` property](/en/guides/markdown-content/#frontmatter-layout). +## MDX in Astro -See how MDX works in Astro with examples in our [Markdown & MDX guide](/en/guides/markdown-content/). +Adding the MDX integration enhances your Markdown authoring with JSX variables, expressions and components. -Visit the [MDX docs](https://mdxjs.com/docs/what-is-mdx/) to learn about using standard MDX features. +It also adds extra features to standard MDX, including support for Markdown-style frontmatter in MDX. This allows you to use most of [Astro's built-in Markdown features](/en/guides/markdown-content/). + +`.mdx` files must be written in [MDX syntax](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax) rather than Astro’s HTML-like syntax. + +### Using Exported Variables in MDX + +MDX supports using `export` statements to add variables to your MDX content or to export data to a component that imports it. + +For example, you can export a `title` field from an MDX page or component to use as a heading with `{JSX expressions}`: + +```mdx title="/src/pages/posts/post-1.mdx" +export const title = 'My first MDX post' + +# {title} +``` + +Or you can use that exported `title` in your page using `import` and `import.meta.glob()` statements: + +```astro title="src/pages/index.astro" +--- +const matches = await import.meta.glob('./posts/*.mdx', { eager: true }); +const posts = Object.values(posts); +--- + +{posts.map(post =>

{post.title}

)} +``` + +#### Exported Properties + +The following properties are available to a `.astro` component when using an `import` statement or `import.meta.glob()`: + +- **`file`** - The absolute file path (e.g. `/home/user/projects/.../file.mdx`). +- **`url`** - The URL of the page (e.g. `/en/guides/markdown-content`). +- **`frontmatter`** - Contains any data specified in the file’s YAML frontmatter. +- **`getHeadings()`** - An async function that returns an array of all headings (`

` to `

`) in the file with the type: `{ depth: number; slug: string; text: string }[]`. Each heading’s `slug` corresponds to the generated ID for a given heading and can be used for anchor links. +- **``** - A component that returns the full, rendered contents of the file. +- **(any `export` value)** - MDX files can also export data with an `export` statement. + +### Using Frontmatter Variables in MDX + +The Astro MDX integration includes support for using frontmatter in MDX by default. Add frontmatter properties just as you would in Markdown files, and these variables are available to use in the template, and as named properties when importing the file somewhere else. + +```mdx title="/src/pages/posts/post-1.mdx" +--- +layout: '../../layouts/BlogPostLayout.astro' +title: 'My first MDX post' +--- + +# {frontmatter.title} +``` + +### Using Components in MDX + +After installing the MDX integration, you can import and use both [Astro components](/en/basics/astro-components/) and [UI framework components](/en/guides/framework-components/#using-framework-components) in MDX (`.mdx`) files just as you would use them in any other Astro component. + +Don't forget to include a `client:directive` on your UI framework components, if necessary! + +See more examples of using import and export statements in the [MDX docs](https://mdxjs.com/docs/what-is-mdx/#esm). + +```mdx title="src/pages/about.mdx" {5-6} /<.+\/>/ +--- +layout: ../layouts/BaseLayout.astro +title: About me +--- +import Button from '../components/Button.astro'; +import ReactCounter from '../components/ReactCounter.jsx'; + +I live on **Mars** but feel free to