Addon-Docs: Change URL hash when TOC item is clicked, and fix TOC loading bugs

[Sidnioulz]

Closes #26345.
Closes #29361.
Closes #25632.

Continuation of #23618.

This PR was done to help finalise a contribution from @sookmax. The original PR updated the URL when clicking on a ToC item or scrolling to a new ToC section.

What I did

I made the following changes to the original PR:

• TableOfContents: The URL change on scroll was reverted, as requested by @JReinhold in the original review
• TableOfContents: Missing useEffect hook dependencies were added in the ToC component
• Manager API::url: Added location hash to internal navigation events so it's preserved on initial load and when globalsUpdated fires
• nit: The git history was rewritten to better qualify and scope changes

As a result, the URL no longer updates when users scroll, and the page now correctly loads on the right docs subsection when loading Storybook with a location hash set.

Checklist for Contributors

Testing

Caution

The original PR did not introduce tests, and neither does this one. I'd like to be advised on how best to proceed. I've tried, without much conviction, to build a stories file but I'd need to mock the channel for this and I don't know how to.

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

1. Checkout the repo, compile, and run storybook:ui
2. Open http://localhost:6006/?path=/docs/core-tags-config--docs#inheritance in your browser
3. Notice how a scroll event occurs and takes you to the relevant section

Section IDs with a space need to be URL encoded. The ID generated in MDX already contains %20, so that needs to be encoded to %2520 to load properly.

1. Checkout as above
2. Open http://localhost:6006/?path=/docs/core-tags-config--docs#tag%20removal this time
3. Notice how you do not get scrolled to the relevant section
4. Open http://localhost:6006/?path=/docs/core-tags-config--docs#tag%2520removal this time
5. Notice that now, it loads

Note

If maintainers know where I can edit the behaviour that generates header IDs in the docs addon, I'll happily adjust it to use _ instead of %20 to help keep URL hashes cleaner.

Caution

The 🔗 links next to headings in the addon-doc also need to be URL encoded so we get the %2520 link that will work with tocbot. I feel the better solution is to adjust all links to use _ rather than further mess with that code. Please let me know how you'd prefer me to proceed.

Documentation

Note

I do not think documentation changes are relevant here.

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=<PR_NUMBER>

name	before	after	diff	z	%
createSize	0 B	0 B	0 B	-	-
generateSize	80.5 MB	80.5 MB	0 B	0.68	0%
initSize	80.5 MB	80.5 MB	0 B	-0.3	0%
diffSize	97 B	97 B	0 B	-0.33	0%
buildSize	7.24 MB	7.27 MB	26 kB	2.75	0.4%
buildSbAddonsSize	1.87 MB	1.89 MB	17.1 kB	15.75	0.9%
buildSbCommonSize	195 kB	195 kB	0 B	-	0%
buildSbManagerSize	1.88 MB	1.88 MB	204 B	-0.76	0%
buildSbPreviewSize	0 B	0 B	0 B	-	-
buildStaticSize	0 B	0 B	0 B	-	-
buildPrebuildSize	3.94 MB	3.96 MB	17.3 kB	6.18	0.4%
buildPreviewSize	3.3 MB	3.31 MB	8.71 kB	1.28	0.3%
testBuildSize	0 B	0 B	0 B	-	-
testBuildSbAddonsSize	0 B	0 B	0 B	-	-
testBuildSbCommonSize	0 B	0 B	0 B	-	-
testBuildSbManagerSize	0 B	0 B	0 B	-	-
testBuildSbPreviewSize	0 B	0 B	0 B	-	-
testBuildStaticSize	0 B	0 B	0 B	-	-
testBuildPrebuildSize	0 B	0 B	0 B	-	-
testBuildPreviewSize	0 B	0 B	0 B	-	-

name	before	after	diff	z	%
createTime	14.3s	17.6s	3.2s	-0.12	18.2%
generateTime	20.8s	19.6s	-1s -214ms	0.29	-6.2%
initTime	4.9s	4.8s	-87ms	-0.23	-1.8%
buildTime	9.9s	9.7s	-129ms	0.74	-1.3%
testBuildTime	0ms	0ms	0ms	-	-
devPreviewResponsive	5.4s	5.1s	-349ms	-0.64	-6.8%
devManagerResponsive	4.3s	3.9s	-388ms	-0.41	-9.9%
devManagerHeaderVisible	1s	717ms	-357ms	-0.67	-49.8%
devManagerIndexVisible	1.1s	727ms	-429ms	-0.88	-59%
devStoryVisibleUncached	2.9s	2.3s	-605ms	-1.94	🔰-25.3%
devStoryVisible	1.1s	802ms	-384ms	-0.44	-47.9%
devAutodocsVisible	868ms	756ms	-112ms	-0.01	-14.8%
devMDXVisible	831ms	728ms	-103ms	-0.24	-14.1%
buildManagerHeaderVisible	796ms	713ms	-83ms	-0.44	-11.6%
buildManagerIndexVisible	895ms	804ms	-91ms	-0.47	-11.3%
buildStoryVisible	710ms	654ms	-56ms	-0.45	-8.6%
buildAutodocsVisible	720ms	616ms	-104ms	-0.26	-16.9%
buildMDXVisible	575ms	672ms	97ms	0.09	14.4%

Greptile Summary

Here's my concise review of the changes focused on fixing Table of Contents URL handling and navigation:

Updates Table of Contents functionality to properly handle URL hash navigation and preserve hash fragments across state changes, focusing on consistent URL behavior.

• Added hash preservation in code/core/src/manager-api/modules/url.ts for navigation events and state updates
• Fixed URL hash handling in code/lib/blocks/src/components/TableOfContents.tsx by emitting proper NAVIGATE_URL events
• Updated useNavigate hook in code/core/src/router/router.tsx to handle empty hash navigation correctly
• Added missing cleanup for setTimeout and error handling in code/lib/blocks/src/blocks/DocsContainer.tsx

_{💡 (5/5) You can turn off certain types of comments like style here!}

[greptile-apps]

_{4 file(s) reviewed, 4 comment(s)
Edit PR Review Bot Settings | Greptile}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 0017926.

Command	Status	Duration	Result
nx run-many -t build --parallel=3	✅ Succeeded	2m	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-02-12 08:14:31 UTC

[Sidnioulz]

Note the failing unit tests on https://github.com/storybookjs/storybook/actions/runs/12474578164/job/34816789722?pr=30130.

RouterData is supposed to always contain a location object, but it appears to be null in some states. I could address this in the code by using optional chaining when initialising hash, but there might be something to fix in these unit tests' context too. WDYT?

[JReinhold]

Let's try to improve the slugs of heading's IDs, turning spaces into dashes to avoid %20 in the URL. I think this is currently done via https://github.com/rehypejs/rehype-slug

[Sidnioulz]

Let's try to improve the slugs of heading's IDs, turning spaces into dashes to avoid %20 in the URL. I think this is currently done via https://github.com/rehypejs/rehype-slug

Turns out the block responsible for those headings was not yet using slugs. I've used github-slugger which is internally used by rehype-slug in the relevant component. I find it odd that rehype-slug is listed as a devDep for the addon-docs though rather than a runtime dep. I've added github-slugger as a runtime dep to blocks but that can be adjusted if needed.

Will now wait for CI to run and then address the failing tests.

[storybook-pr-benchmarking]

Package Benchmarks

^{Commit: 0017926, ran on 12 February 2025 at 08:18:15 UTC}

The following packages have significant changes to their size or dependencies:

@storybook/addon-docs

	Before	After	Difference
Dependency count	13	13	0
Self size	2.26 MB	2.24 MB	🎉 -16 KB 🎉
Dependency size	9.41 MB	9.43 MB	🚨 +19 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/addon-essentials

	Before	After	Difference
Dependency count	32	32	0
Self size	12 KB	12 KB	0 B
Dependency size	15.43 MB	15.44 MB	🚨 +11 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/blocks

	Before	After	Difference
Dependency count	2	2	0
Self size	607 KB	626 KB	🚨 +19 KB 🚨
Dependency size	1.28 MB	1.28 MB	0 B
Bundle Size Analyzer	Link	Link

[Sidnioulz]

@JReinhold CI now passing, this should be ready for review :)

[Sidnioulz]

@JReinhold would you have some time this week to review this PR?

I'd love to see it go online as there were a few other issues mentioning problems with heading links, we've got a new tocbot release fixing up some of the issues with current heading highlighting and now #30411. It could be nice to bundle these changes together so they can be announced in a next minor release. I'll do a first review of #30411 myself.

[JReinhold]

Great work!

When I'm trying it out, it seems to (almost) work as it should:

• clicking a heading-link and reloading takes me back to the heading
• clicking a link in the toc and reloading also takes me back to the heading

However there appears to be a problem with Unicode. If you look at the docs for the Unicode stories: http://localhost:6006/?path=/docs/%F0%9F%98%80--docs

Clinking the headings and reloading works fine, however clicking the toc and reloading does not. They also generate different hashes:

• heading link: %EB%B0%94%EB%B3%B4 - 바보 decoded
• toc link: %25EB%25B0%2594%25EB%25B3%25B4 - %EB%B0%94%EB%B3%B4 decoded

[JReinhold]

I've made this a devDependency. We do that with all dependencies where possible, so they are prebundled, which greatly reduces Storybook's install-size.

[JReinhold]

I think I've fixed the unicode problem with my commit, and couldn't get the behavior to crash. Would be great if you could try it out too.

[JReinhold]

From my POV this is good to go, but I'm unsure if there is more stuff you want to do here @Sidnioulz? I'm slightly confused about the PR description 😅

[Sidnioulz]

Thanks for the review @JReinhold!

I had forgotten to remove the instance of URL encoding that your commit removed, after applying passing heading IDs through GitHub Slugger. I checked and also conclude that reloading works in the example you showcase, regardless of whether I clicked in tocbot or not.

I'm happy to merge as-is if this meets your standards, I just regret that I don't have dedicated tests for the navigation logic as I feel there should be some that cover hashes, search params, etc. WDYT?

[JReinhold]

I dont think it's feasible to test this properly in a unit test or a story, simply too many moving parts.
The only thing that would make sense would be an E2E test, but even then the main part to assert on would be that it scrolls properly which isn't simple to do either.

I think this is a case where the ROI on a test for this is not there. If you want to take a go at an E2E test I wont stop you, but I'd say merge this now and if we find out that this regress more than we thought, we can write a test for it then.

[Sidnioulz]

I dont think it's feasible to test this properly in a unit test or a story, simply too many moving parts. The only thing that would make sense would be an E2E test, but even then the main part to assert on would be that it scrolls properly which isn't simple to do either.

I think this is a case where the ROI on a test for this is not there. If you want to take a go at an E2E test I wont stop you, but I'd say merge this now and if we find out that this regress more than we thought, we can write a test for it then.

Alright, happy to have it merged then!

Errata: I realise the Heading component hasn't been updated, only Subheading! I've added a commit to update Heading.