[MDX] Improved docs for custom components (#5190)

* [MDX] Fixed minor formatting issues in README
- whitespace at line end
- blank lines around lists and code fences
- casing of internal references

* Detailed use of custom component with imported MDX

Incorporated all review comments from Sarah and Ben manually,
because the old branch would not pass the mergeability check.

1 files changed, 15 insertions, 11 deletions

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!
 </BaseLayout>
 ```
+
 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 `<slot />` component is written:
 
 ```astro
@@ -329,7 +332,7 @@ const props = Astro.props;
 </blockquote>
 ```
 
-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 `<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:
+When rendering imported MDX content, custom components can be passed via the `components` prop.
+
+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={{ h1: Heading }}"
+```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';
 ---
 
-<Content components={{ h1: Heading }} />
+<Content components={{...components, h1: Heading }} />
 ```
 
 ### 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: