Skip to content

Fix table of contents intersection observer#3656

Merged
delucis merged 9 commits intomainfrom
chris/toc-fix
Jan 22, 2026
Merged

Fix table of contents intersection observer#3656
delucis merged 9 commits intomainfrom
chris/toc-fix

Conversation

@delucis
Copy link
Member

@delucis delucis commented Jan 15, 2026

Description

This PR fixes an issue with Starlight’s intersection observer used for updating table of contents state, which we discovered while reviewing #3382 during Talking & Doc’ing today.

We found multiple issues:

  • After we added anchor link support, headings in sites with this enabled are wrapped in a <div> breaking an assumption in the table of contents logic.
  • After moving Markdown styles to an external CSS file, we renamed .content to .sl-markdown-content, but forgot to rename the same in a query selector here.

This caused some subtle issues that were not super obvious, but we noticed them while digging deeper.

This PR also adds some Playwright tests to make sure highlighting behaves as expected in the browser.

@changeset-bot
Copy link

changeset-bot bot commented Jan 15, 2026

🦋 Changeset detected

Latest commit: a878fc5

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

This PR includes changesets to release 1 package
Name Type
@astrojs/starlight Patch

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
Copy link

netlify bot commented Jan 15, 2026

Deploy Preview for astro-starlight ready!

Name Link
🔨 Latest commit a878fc5
🔍 Latest deploy log https://app.netlify.com/projects/astro-starlight/deploys/6970ff355b7e8f0008e8af78
😎 Deploy Preview https://deploy-preview-3656--astro-starlight.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 100 (no change 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 project configuration.

@github-actions github-actions bot added the 🌟 core Changes to Starlight’s main package label Jan 15, 2026
@astrobot-houston
Copy link
Contributor

astrobot-houston commented Jan 15, 2026

size-limit report 📦

Path Size
/index.html 7.28 KB (0%)
/_astro/*.js 25.86 KB (+0.4% 🔺)
/_astro/*.css 14.3 KB (0%)

- Correctly highlights “Overview” for content preceding first subheading (this was incorrectly being attributed *to* the first subheading in our updated code in the previous commit
- Correctly selects elements for observation to avoid excluding elements that include an `id`’d element which isn’t a heading (e.g. tabs)
- Fixes returning headings from `getHeadingElement()` that aren’t in the ToC, a bug introduced in the previous commit
@delucis delucis added the 🌟 patch Change that triggers a patch release label Jan 21, 2026
Copy link
Member

@florian-lefebvre florian-lefebvre left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know much about this stuff but it looks solid!

@trueberryless
Copy link
Contributor

trueberryless commented Jan 22, 2026

Awesome stuff here 🙌

Regarding the already amazing new test cases, I wonder if we also should add tests for changing the default heading levels, or is this already implicitly covered with test cases like this?

I will try to take a closer look and approve the changes in the next few days, but you don't need to wait as Florian just approved as well 😅

Copy link
Member

@ematipico ematipico left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately I don't much context, but if the tests pass, i'm good

@delucis
Copy link
Member Author

delucis commented Jan 22, 2026

Regarding the already amazing new test cases, I wonder if we also should add tests for changing the default heading levels, or is this already implicitly covered with test cases like this?

Yeah, I think we can be confident that the unit test there is making sure we use the right min/max levels when generating the ToC. And we just pass those down to the custom element. If we had more logic involved on the client to extract that data, then maybe it would be good to test, but the existing tests should cover any case where we break the data-min-h/data-max-h attributes.

@delucis delucis merged commit a0e6368 into main Jan 22, 2026
17 checks passed
@delucis delucis deleted the chris/toc-fix branch January 22, 2026 12:42
@astrobot-houston astrobot-houston mentioned this pull request Jan 21, 2026
dadezzz pushed a commit to dadezzz/ice-notes that referenced this pull request Jan 25, 2026
This PR contains the following updates:

| Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) |
|---|---|---|---|
| [@astrojs/starlight](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/starlight)) | [`0.37.3` → `0.37.4`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight/0.37.3/0.37.4) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fstarlight/0.37.4?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fstarlight/0.37.3/0.37.4?slim=true) |

---

### Release Notes

<details>
<summary>withastro/starlight (@&#8203;astrojs/starlight)</summary>

### [`v0.37.4`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0374)

[Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.37.3...@astrojs/starlight@0.37.4)

##### Patch Changes

- [#&#8203;3534](withastro/starlight#3534) [`703fab0`](withastro/starlight@703fab0) Thanks [@&#8203;HiDeoo](https://github.com/HiDeoo)! - Fixes support for running builds when `npx` is unavailable.

  Previously, Starlight would spawn a process to run the Pagefind search indexing binary using `npx`. On platforms where `npx` isn’t available, this could cause issues. Starlight now runs Pagefind using its Node.js API to avoid a separate process. As a side effect, you may notice that logging during builds is now less verbose.

- [#&#8203;3656](withastro/starlight#3656) [`a0e6368`](withastro/starlight@a0e6368) Thanks [@&#8203;delucis](https://github.com/delucis)! - Fixes several edge cases in highlighting the current page heading in Starlight’s table of contents

- [#&#8203;3663](withastro/starlight#3663) [`00cbf00`](withastro/starlight@00cbf00) Thanks [@&#8203;lines-of-codes](https://github.com/lines-of-codes)! - Adds Thai language support

- [#&#8203;3658](withastro/starlight#3658) [`ac79329`](withastro/starlight@ac79329) Thanks [@&#8203;delucis](https://github.com/delucis)! - Avoids adding redundant `aria-current="false"` attributes to sidebar entries

- [#&#8203;3382](withastro/starlight#3382) [`db295c2`](withastro/starlight@db295c2) Thanks [@&#8203;trueberryless](https://github.com/trueberryless)! - Fixes an issue where the mobile table of contents is unable to find the first heading when a page has a tall banner.

</details>

---

### Configuration

📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update again.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box

---

This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0Mi45Mi40IiwidXBkYXRlZEluVmVyIjoiNDIuOTIuNCIsInRhcmdldEJyYW5jaCI6Im1haW4iLCJsYWJlbHMiOltdfQ==-->

Co-authored-by: Renovate Bot <renovate@zarantonello.dev>
Co-committed-by: Renovate Bot <renovate@zarantonello.dev>
HiDeoo added a commit to HiDeoo/starlight that referenced this pull request Jan 29, 2026
* main:
  [ci] release (withastro#3659)
  fix: mobile toc issue with custom banners (withastro#3382)
  chore(deps): update actions/checkout action to v6.0.2 (withastro#3670)
  Fix table of contents intersection observer (withastro#3656)
  chore(deps): update peter-evans/create-pull-request action to v8.1.0 (withastro#3669)
  Pagefind CLI → Pagefind API (withastro#3534)
  chore(deps): update changesets/action action to v1.6.0 (withastro#3668)
  i18n(de): Fix orthographic errors in `getting-started.mdx` and `index.mdx` (withastro#3664)
  i18n(fr): update `resources/plugins.mdx` (withastro#3665)
  [ci] format
  i18n(th): Add Thai translations to Starlight UI (withastro#3663)
  i18n(de): update resources/plugins.mdx (withastro#3662)
  i18n(ko): update community plugins (withastro#3661)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🌟 core Changes to Starlight’s main package 🌟 patch Change that triggers a patch release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants