Add TableOfContentsList to Module Exports / Allow Overrides

[jumpingpxl]

What version of starlight are you using?

0.24.4

What is your idea?

My Idea is to add TableOfContentsList to the module exports of starlight. Also adding TableOfContentsList to the components supporting overrides would be good

Why is this feature necessary?

Adding the TableOfContentsList component to the module exports would make it possible to override the TableOfContents component without having to import the TableOfContentsList component by its relative path (f.e. ../../../node_modules/@astrojs/starlight/components/TableOfContents/TableOfContentsList.astro). Overwriting the TableOfContents would allow us to add extra links, etc below the TableOfContents.

Adding the ability to overwrite TableOfContentsList would allow us to change the general structure of the component. f.e. to remove the nesting

Do you have examples of this feature in other projects?

No response

Participation

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

[delucis]

Thanks for the suggestion @jumpingpxl! The main reason this isn’t available to override is that our overridden components all share the same props interface, but the TableOfContentsList subcomponent needs a different props shape — it’s internal and only a separate component from TableOfContents so it can render recursively with Astro.self.

It should already be possible to render extra links etc. below the table of contents. Here’s an example of overriding the table of contents and adding a custom link below.

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

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

<a href="mailto:[email protected]">Send us an e-mail</a>

For people who do want to reimplement TableOfContents and therefore import TableOfContentsList, I think we could consider exporting it directly. On the one hand, it feels a bit like an internal implementation detail, but on the other it’s also a slightly annoying component to have to reimplement if needed.

[jrollio]

Howdy,

My requirement could also benefit from this or similar functionality.

How do my use cases relate to this thread?
As the functionality I need does not exist, one might simply override and replace TableOfContents and MobileTableOfContents with the requested i18n functionality. But this will not work because replacing these would require importing TableOfContents/TableOfContentsList.astro into the overrides which fails because TableOfContentsList.astro is not exposed / exported.

However, in this case, there is another, perhaps better, way to provide this functionality. That is, by leveraging:

• i18n, which is already supported
• an override of TableOfContents, already supported
• a modification to TableOfContents and MobileTableOfContents, not yet supported

Details

Use Cases

1. Requested functionality   —   Provide a more descriptive, less repetitive, right sidebar page toc heading that, in this case, mirrors the page title. When coupled with i18n en.json {{feature}} translation would be dynamic, so technically could support any other value too.

Example

Change...

<h2 id="starlight__on-this-page">{Astro.locals.t('tableOfContents.onThisPage')}</h2>

...to

<h2 id="starlight__on-this-page">{Astro.locals.t('tableOfContents.onThisPage', {{ feature: title }} )}</h2>

2. Additional nice to have functionality   —   Directly under the 'On this page' right sidebar, the toc header is defaulted to Overview. To make this more descriptive, I have overridden the TableOfContents component to: {Astro.props.entry.title}.

Example

I overrode MobileTableOfContents.astro as follows (note: I also overrode TableOfContents.astro, but for sake of brevity, I'm showing just the Mobile version here):

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

const { title } = Astro.props.entry.data;
const { toc } = Astro.props;

[ ...toc?.items][0].text = title;
---
<Default {...Astro.props}><slot /></Default>

Now if, instead of setting [ ...toc?.items][0].text to title, I were to set it to null:

[ ...toc?.items][0].text = null; 

...and then add:

{
    "tableOfContents.onThisPage": "{{feature}}"
}

...to /src/content/i18n/en.json

...and then implement the changes to TableOfContents.astro and MobileTableOfContents.astro as requested above, in Use Case 1,

...then we would have a page toc with an h2 heading that links to '#_top' and whose text value can be the page title, or page heading text, or whatever the user provides to {{ feature: ?userinput }}.

But why would we need to assign null to [ ...toc?.items][0].text?
We don't. We do not actually need to assign null to this, but doing so avoids stacking the same two hyperlinks on top of each other such that the end user / reader is confronted two identical links stacked atop each other, the only difference being the top one formatted as an h2 and the bottom as an a.

So, building on the request above, in Use Case 1, the ask here is to allow for the hyperlink to #_top to be removed from Astro.props.toc.items[0] and placed in the i18n {{feature}} parameter, enabling 'On this page' to become the hyperlink to the top of the page and be relabeled using the contents of title or PageTitle or whatever dynamic value desired by the user in i18n {{ feature: ??? }}

Could this be improved?
Probably. For example, instead of "faking out" the toc list by setting toc[0] to null, one approach might be to build the toc by starting with whatever heading immediately follows the heading that was used in place of 'On this page'.

Workaround

As the requested functionality does not exist, how can one meet this need in the interim?
To emulate the requested functionality In the meantime, I made the following changes:

1. Replaced the default label 'Overview' with the page title from Astro.props by overriding TableOfContents.astro and MobileTableOfContents.astro
2. "Removed" the 'On this page' toc header disappear by setting its value to an empty string in i18n.json

Why is this not suitable for the long term?
It is suitable for the long term, but it is not desirable because this workaround requires eliminating the toc header, which could have been put to helpful use as an h2-formatted title or pageTitle, conveniently hyperlinked to #_top.

Benefits

1. Conserves and improves valuable screen real estate, especially on the MobileTableOfContents
2. Leverages and builds upon existing features and functionality Page structure that already exists, link already exists (i.e., "#_top"), props data already exists (title, pageTitle, etc) and functionality of i18n already exists ( {{ feature }} )
3. Less waste - No need to have not just one, but TWO, generic heading descriptions occupying the top two positions of the page toc.
4. More accurate, descriptive, personalized - Allows for toc header to match what's actually on the page-- if I require an "Overview" section, then I'll create one with a markdown header. If I don't create one, then page toc should not list one.
5. Practical, more functional, cleaner, more efficient- Relocating and allowing for dynamic naming (i.e., to page title, or another page-specific value from Astro.props) means every entry line of text displayed on the right sidebar toc is clickable and more descriptive. Moreover, the top line of text, displayed as the page title (or whatever), when clicked, takes the reader to the top of the page where they will find the page title!