How to add headings injected from a layout component

[KonnorRogers]

What version of starlight are you using?

0.15.1

What is your idea?

If I'm writing a markdown layout, I would like any additional <h*> tags to be added to the TOC. (not sure if this is a discussion or an issue)

Why is this feature necessary?

It allows dynamically injecting markup without needing to write .mdx files directly and wrapping in a component.

Do you have examples of this feature in other projects?

Markdown file:

---
title: Alert
description: Alerts are used to display important messages inline or as toast notifications.
layout: ../../../layouts/ComponentLayout.astro
---

Component Layout File:

---
const hasSlots = Boolean(getComponentMetadata("alert").slots?.length)
---

<slot />

{/* Slots */}
{!hasSlots ? "" :
  <>
    <h2 id="slots">Slots</h2>
    
    {/* More slot data */}
  </>
}

I would expect <h2 id="slots"> to be added to the TOC in Starlight

Participation

• I am willing to submit a pull request for this feature.

[delucis]

Thanks for the post @KonnorRogers! This is currently not supported using layout. The table of contents is generated from Astro’s headings array, which is based on a remark plugin, so only detects headings in the initial content, before layouts are applied.

Theoretically, one way you could work around it for your use case though would be to override Starlight’s PageSidebar component to add your custom headings before the ToC renders. I don’t know how easy it would be for you to know there whether the “Slots” heading should be there or not, but assuming you have a way to check that, it might look something like:

---
import type { Props } from '@astrojs/starlight/props';
import Default from '@astrojs/starlight/components/PageSidebar.astro';

if (shouldAddSlotsHeading) {
	Astro.props.toc.items = [
		...Astro.props.toc.items,
		{ depth: 2, slug: 'slots', text: 'Slots', children: [] },
	];
}
---

<Default {...Astro.props}><slot /></Default>

Gets trickier if you need to splice it somewhere in the middle or have actual page headings as children though, so I guess YMMV.

Otherwise, the pattern I tend to use in cases like this is to avoid a layout and use a component in MDX instead to wrap the extra stuff when needed and include the ## Slots heading directly in each page. Of course that might defeat the purpose of what you’re trying to automate potentially!

[KonnorRogers]

@delucis Worked like a charm. Thanks!