Improved footnote support

[delucis]

What version of starlight are you using?

0.37.0

What is your idea?

Starlight currently supports footnotes via Astro’s default Markdown processing but it is mostly an afterthought and not something we’ve spent time looking at. This means there are a fair number of rough edges:

• The visually hidden “Footnotes” subheading injected by remark-rehype is added by Astro to a page’s headings, so shows up in the table of contents. I’m unsure if that’s desirable or not, but it is a bit confusing given this heading is visually hidden by default.
• The various labels used by remark-rehype are the English defaults and don’t support our i18n features.
• Footnotes have no dedicated styling.
  • In particular, footnote links and the “back” link on references are tiny by default, failing touch target requirements for accessibility.

Examples of the current behaviour

• Small, hard to see/click superscript footnote in text:
  

• Bottom-of-page references, which has no visible heading, but the heading labelled “Footnotes” still shows in Starlight’s table of contents in the right sidebar. Additionally, the “back” link is an emoji that is small and fails touch target sizing requirements.
  

Why is this feature necessary?

Some users have already expressed interest in footnotes (#2622, #3575) and although we support it “by default”, it would be good to polish up any rough edges, especially to fix accessibility issues for anyone deciding to use this.

On the flipside, footnotes still remain a relatively rare requirement for docs (and maybe not a great choice in terms of UX), so this is maybe not high priority.

Do you have examples of this feature in other projects?

• Docusaurus and Fumadocs use the same remark-rehype support we do, although I couldn’t find an example of the output styling
• VitePress does not support footnotes AFAICT

Participation

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

[jglev]

Thank you for writing this up! And for all of your work on Starlight!

I was confused about Starlight visually hiding the "Footnotes" heading just now in a site that I maintain. As of this writing, this discussion thread is one of the first that comes up on Google when searching "astro starlight footnotes heading." With that in mind, while this discussion progresses, I thought it might be of use to other readers to note that, as a stopgap, I successfully got the "Footnotes" header to display by editing the site's src/styles/custom.css file with the following snippet:

/* Show footnotes heading */
h2#footnote-label {
  width: unset;
  height: unset;
  position: unset;
}

And, similarly as a stopgap, added some styling to footnote links with this snippet:

/* Style footnote links */
a[data-footnote-ref] {
  text-decoration: none;
  font-weight: bold;
  border: 2px solid var(--sl-color-accent);
  padding: 0;
  margin: 0;
  height: 1.4em;
  min-width: 1.4em;
  border-radius: 50%;
  text-align: center;
  display: inline-flex;
  align-items: center;
  justify-content: center;
}

[The-LukeZ]

Thanks for your idea and thank you for all your work as well ^^

I would imagine it like this:

• not show in the TOC
• now show up as a clickable heading (see below)

It would also be cool if one could style this through the astro config maybe or by a file in the config directory.
Maybe even turn off the TOC in general via a config setting.

[delucis]

Maybe even turn off the TOC in general via a config setting.

This one is already supported if you want it! Setting tableOfContents: false in the Starlight config disables it globally (and can then be reenabled on a per-page basis via frontmatter if needed).

[The-LukeZ]

Yeah but that's globally - on the whole page. I still want my toc just without the "Footnotes".

With "Maybe even turn off the TOC in general via a config setting." I meant "turn off the footnotes in the toc globally via config setting."

[delucis]

Ah, right, gotcha. Pending proper support in Starlight, that’s probably fixable today using route data middleware:

import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware((context) => {
  // Get the table of contents data for this page.
  const { toc } = context.locals.starlightRoute;
  // Filter out the footnotes heading
  toc.items = toc.items.filter((item) => item.slug !== 'footnote-label');
});

[The-LukeZ]

interesting... 👀