Add built-in heading anchor link support

[delucis]

Description

• Closes Anchor Links for Headings #1239
• This PR adds built-in support for rendering clickable anchor links alongside headings.

Where does this apply?

1. For Markdown and MDX files, anchor links are added using rehype plugins. This can be disabled with markdown: { headingLinks: false } in Starlight config.
2. For Markdoc files, anchor links are added with a custom renderer for the heading node. This can be disabled by passing { headingLinks: false } to the Starlight Markdoc preset.
3. In Astro components, anchor links can be added with a new <AnchorHeading> component.

The anchor link approach

The HTML mark-up approach the anchor links follow is based on Amber Wilson’s Are your Anchor Links Accessible? blog post. (Thank you for sharing your research, Amber!)

The output looks a little like this:

<div>
  <h2 id="a-heading">A heading</h2>
  <a href="#a-heading">
    <span class="sr-only">Section titled “A heading”</span>
    <svg>...</svg>
  </a>
</div>

• The <a> link is placed after the heading element rather than inside it or even wrapping it as some sites do. This ensures that the heading doesn’t contain any additional text (for screenreaders listing headings for example) and also avoids the potentially confusing situation of a link which links to itself.
• The accessible “Section titled…” label uses Starlight’s internationalization APIs so it can be localized.
• The heading and link are wrapped in a <div> so that we can position the icon link inline at the end of the heading as desired.
• There are more notes about the actual styles for the layout in anchor-links.css in this PR.

To-do

• Write tests for the rehype plugins.
• Write tests to assert that component and plugin markup matches.
• Fix the use of rehypeSlug and use Astro’s built-in heading slugger instead.
• Add changesets

[changeset-bot]

🦋 Changeset detected

Latest commit: 9af5fae

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@astrojs/starlight	Minor
@astrojs/starlight-markdoc	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	9af5fae
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/67ff79297f4e020008c68bb2
😎 Deploy Preview	https://deploy-preview-3033--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 98 (🔴 down 2 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	guides/authoring-content.mdx	Source changed, localizations will be marked as outdated.
en	guides/pages.mdx	Source changed, localizations will be marked as outdated.
en	reference/configuration.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[astrobot-houston]

size-limit report 📦

Path	Size
/index.html	7.2 KB (+3.5% 🔺)
/_astro/*.js	25.76 KB (0%)
/_astro/*.css	14.21 KB (+1.7% 🔺)

[Arhell]

@delucis thanks for your work, and will it be possible to change the icon to another one, for example this one #
in the config, or already in the component?

[delucis]

will it be possible to change the icon to another one, for example this one # in the config

Probably not in this initial version. I will wait for #3024 first as that will make supporting configurable icons much easier.

[delucis]

One question I asked myself while playing with the PR is if any special considerations should be made for pages using the splash template? I personally don't think so after thinking about it more.

Ah yeah, I think it should behave the same (fortunately so, as I’m not sure how to do it if they shouldn’t 😅). Not documented currently (maybe it should be?), but anchor links by definition are only added to headings that have an id — either an auto-generated one for Markdown headings or an explicitly added custom one (e.g. someone authors <h2 id="important">This heading is important</h2>). This also means you can opt out of headings being linked like this by authoring, e.g. <h2>This heading has no anchor link</h2>. This is what is unintentionally, but to good effect, happening on the Starlight landing page for example.

[delucis]

Got a failing size limit check when updating branch. Looks like the Expressive Code update in #3109 bumped CSS size by ~600 bytes taking the additions in this PR over the edge, so I bumped our budget up by 250 bytes.

[delucis]

@HiDeoo based on your experience in #2322 can you see anything obvious that needs doing to these styles other than wrapping them in @layer starlight.content?

[HiDeoo]

I would not think so. The import 'virtual:starlight/optional-css'; import in Page.astro should still be near the end after import '../style/util.css'; so no change required here.

Altho, we should definitely confirm that before merging the last one of the two.

[HiDeoo]

Just tested locally merging this branch into #2322 for sanity and indeed, I only had to wrap the styles in the starlight.content layer, couldn't spot any issue.

[delucis]

Awesome, thank you for testing! Pushed that change up so it’s ready to merge.

[delucis]

Merged in the cascade layer changes and tested the deploy preview and all looking good 👍