Clarify that named slots are not supported in md/mdx is layout is expressed in frontmatter

[jrencz]

📚 Subject area/topic

Layout

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

• https://docs.astro.build/en/guides/markdown-content/
• https://docs.astro.build/en/basics/layouts/
• https://docs.astro.build/en/basics/astro-components/#named-slots

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

There are at least those 2 issues

• Named slots are not rendered when using mdx layout prop astro#6051
• Named Slots in MDX with Layout via Frontmatter astro#7547

where it was reported as a bug that named slot doesn't work on md(x) page if layout is attached to the page via the frontmatter.

In withastro/roadmap#285 (comment) I found the following quote:

With the new Content Collections feature, Astro is moving away from the magic layout pattern.

If I understand correctly "magic layout pattern" is what I named "layout is expressed in frontmatter"

But: neither of the pages I listed mentions that the named slots are not supported if layout is attached that way, nor does the https://docs.astro.build/en/guides/markdown-content/ mention a workaround for that.

I think it should be documented how to use layouts with named slots for MDX pages (i.e. use layout as component) and that it's impossible to achieve (nor planned - if I got the quoted response right?) for md.

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

No response

[sarah11918]

Hi @jrencz ! Thanks for bringing this to our attention as a docs issue!

I did recently just publish updates to all those pages, mostly to separate out MDX content from the Markdown page. I wanted to make the Markdown page cleaner, and JUST about Markdown. That would give us more "breathing room" to go into detail about MDX on the MDX guide page in particular. https://docs.astro.build/en/guides/integrations-guide/mdx/

In fact, we've been talking about whether to deprecate that frontmatter layout property entirely, but since it's there now and exists, I agree it should be properly documented!

The new location for this info on the Markdown page is here: https://docs.astro.build/en/guides/markdown-content/#individual-markdown-pages and at the link you're prompted to for more info in the Read more here: https://docs.astro.build/en/basics/layouts/#markdown-layouts

Would be happy if anyone wants to revisit those links I mentioned, and I suspect this is now strictly an MDX issue, not Markdown, so maybe there's a good place to work this in to existing content there!