docs: add MDXLayoutProps to README (#4700)

* docs: add MDXLayoutProps to README * chore: changeset * nit: remove "if you understand this diff" * nit: AdD tYpE sAfEtY Co-authored-by: Chris Swithinbank <swithinbank@gmail.com> * Update packages/integrations/mdx/README.md Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> Co-authored-by: Chris Swithinbank <swithinbank@gmail.com> Co-authored-by: Matthew Phillips <matthew@skypack.dev> Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
withastro · Sep 22, 2022 · e5f7114 · e5f7114
1 parent 17dbc67
commit e5f7114
Show file tree

Hide file tree

Showing 2 changed files with 50 additions and 2 deletions.
diff --git a/.changeset/metal-bees-pretend.md b/.changeset/metal-bees-pretend.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/mdx': patch
+---
+
+Document MDXLayoutProps utility type
diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md
@@ -203,15 +203,16 @@ title: 'My Blog Post'
 ---
 ```
 
-Then, you can retrieve all other frontmatter properties from your layout via the `frontmatter` property, and render your MDX using the default [`<slot />`](https://docs.astro.build/en/core-concepts/astro-components/#slots):
+Then, you can retrieve all other frontmatter properties from your layout via the `frontmatter` property, and render your MDX using the default [`<slot />`](https://docs.astro.build/en/core-concepts/astro-components/#slots). See [layout props](#layout-props) for a complete list of props available.
 
 ```astro
 ---
 // src/layouts/BaseLayout.astro
-const { frontmatter } = Astro.props;
+const { frontmatter, url } = Astro.props;
 ---
 <html>
   <head>
+    <meta rel="canonical" href={new URL(url, Astro.site).pathname}>
     <title>{frontmatter.title}</title>
   </head>
   <body>
@@ -222,6 +223,48 @@ const { frontmatter } = Astro.props;
 </html>
 ```
 
+You can set a layout’s [`Props` type](/en/guides/typescript/#component-props) with the `MDXLayoutProps` helper.
+
+:::note
+`MDXLayoutProps` is the same as the `MarkdownLayoutProps` utility type with `rawContent()` and `compiledContent()` removed (since these are not available for `.mdx` files). Feel free to **use `MarkdownLayoutProps` instead** when sharing a layout across `.md` and `.mdx` files.
+:::
+
+```astro ins={2,4-9}
+---
+// src/layouts/BaseLayout.astro
+import type { MDXLayoutProps } from 'astro';
+
+type Props = MDXLayoutProps<{
+  // Define frontmatter props here
+  title: string;
+  author: string;
+  date: string;
+}>;
+
+// Now, `frontmatter`, `url`, and other MDX layout properties
+// are accessible with type safety
+const { frontmatter, url } = Astro.props;
+---
+<html>
+  <head>
+    <meta rel="canonical" href={new URL(url, Astro.site).pathname}>
+    <title>{frontmatter.title}</title>
+  </head>
+  <body>
+    <h1>{frontmatter.title}</h1>
+    <slot />
+  </body>
+</html>
+```
+
+#### 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.
+
+Astro recommends using the `MDXLayoutProps` type (see previous section) to explore all available properties.
+
 #### Importing layouts manually
 
 You may need to pass information to your layouts that does not (or cannot) exist in your frontmatter. In this case, you can import and use a [`<Layout />` component](https://docs.astro.build/en/core-concepts/layouts/) like any other component: