Document how to use Astro components with slots inside MDX files

[hippotastic]

A recent question in our Discord support channel brought me to the realization that we currently don't document how you can fill slots to be used in Astro components from inside MDX files.

I think a good location to document this could be here: https://docs.astro.build/en/guides/markdown-content/#using-components-in-markdown (or to a specialized MDX page if we were to add one)

Here's what I would like us to mention:

• First of all: Yes, you can define slot content in MDX files. You can wrap an element around your desired slot content and add the slot="your-slot-name" attribute.
• By default, the wrapping element will become the outer element of your slot content. If you don't want this, you can use a Fragment instead, which will disappear from the resulting HTML output.
• Optionally, we can mention a common issue here as well, which can happen generally everywhere when interleaving Markdown and HTML/JSX: In case you encounter any MDX error messages while developing your page (e.g. Expected a closing tag for '<div>' (2:3-2:20) before the end of 'paragraph' end-tag-mismatch mdast-util-mdx-jsx), ensure that your HTML/JSX elements are opened and closed on their own lines and not mixed with text on the same line. MDX is a bit more strict than HTML in that regard.

Draft of code sample:

/* Example: src/pages/using-slots.mdx */

import MyComponent from '../components/MyComponent.astro'

<MyComponent>
  <div slot="main">
    # This is a Markdown heading inside a div!
    And a paragraph with *formatting*.
    Both go into the "main" slot of your component.
  </div>
  <Fragment slot="side">
    If you don't want a wrapping element like a `div` to be
    the outer wrapper of your slot content, you can use a Fragment
    like this to define in which slot this paragraph should go.
  </Fragment>
  This is a regular **Markdown** paragraph going into the default slot.

  And another one.
</MyComponent>

We could optionally also provide a MyComponent.astro sample component that makes use of the slot content, and include that sample component in the frontmatter of the code sample above.

[sarah11918]

Love this, @hippotastic ! And just to clarify, if we were to include a file name at the top to show where the code sample exists, it could be something like src/pages/posts/my-markdown-post.md ?

When I think slots, I think @Jutanium 😉 Dan, let me know if writing this up interests you, otherwise I'll only ping you for editing after something has been drafted.

[hippotastic]

Love this, @hippotastic ! And just to clarify, if we were to include a file name at the top to show where the code sample exists, it could be something like src/pages/posts/my-markdown-post.md ?

Yes, exactly. The code sample is supposed to be a regular markdown file. Your path is great. If we think that readers might assume that this only works in blog scenarios, we could also use src/pages/my-markdown-page.md.

[sarah11918]

As we are moving away from support for components in Markdown (legacy.astroFlavoredMarkdown), I don't think we should document this? It will be a legacy feature?

[hippotastic]

Nope, the use case is unchanged for MDX 😄

[sarah11918]

Thanks @hippotastic ! Shall we update the title to reflect .mdx then (so we don't confuse Sarah again), and consider this on the stack for .mdx documentation in the docs?

[hippotastic]

Yes, great point! I updated the title and issue text accordingly to target MDX.

[delucis]

This is likely on hold as Fragment seems to be breaking in MDX currently: https://github.com/withastro/astro/issues/4130

[delucis]

We think this works in MDX like it does in .astro now, so maybe no need to document explicitly? Going to close, but feel free to reopen or even PR if we think there are still specific edge cases that need documenting.