Incomplete or unclear guide for custom MDX components

[aureliendossantos]

📚 Subject area/topic

MDX custom components

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/markdown-content/

📋 Description of content that is out-of-date or incorrect

I’ve been trying to figure out how to use custom MDX components, and I think a few points in the docs need clarification, especially as a user of content collections:

1. There is a simple example of how to make a custom > blockquote using <slot />. However, neither the Astro docs nor the linked MDX page explain how to write the custom component for a more complex syntax like [title](http://link).

2. This example seems useful if you directly import a .mdx file, but is confusing if you use a content collection, because the components variable doesn’t exist, so you don’t know if you still have to import and pass back your custom components, as said in the “Note”.

3. The same example shows that you can replace a set of keywords h1, a, etc. with a custom component. However, it wasn’t clear to me that you can simply pass a component like this: <Content components={{ MyComponent }} />. I just randomly tried it and it worked. I think it should be more clear because it’s precisely what I was looking for: I didn't need to replace a keyword like h1, but my own custom component depending on the page rendering the <Content />, ie by doing <Content components={{ MyComponent: AlternativeComponent }} />.

I hope this feedback can be useful!

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response