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!

[sarah11918]

I believe recent work on this section on the layouts page now makes it clear that all the special layout property can do is pass frontmatter data and headings. Importing and using a layout component directly should be used for all other situations, including passing any other data and using named slots. This was also never an option in Markdown itself, so the recent work separating Markdown from MDX content should not lead people to assume anything other than basic markdown content is supported.

I am also adding a PR to close this issue that will remove mentioning the frontmatter layout property from the MDX page, so I think it's less likely people will try to use it without seeing the description on the Layouts page itself, which emphasizes using imports for more functionality.

While there may be no specific example right now showing using named slots in MDX, there is also no mention of using the frontmatter property where other component imports etc. are described.