Addon-docs: Support disable TOC in unattached MDX

[shilman]

Closes #23672

What I did

• Added a new parameter docs.toc.disableUnattachedMdx to be set in .storybook/preview.ts
• Updated an example story
• Updated the docs

Why not allow this on a per-file basis? Currently we don't have a convenient system for setting parameters on unattached MDX. We can set tags on MDX files, but that's more intrusive than parameters, so I am proposing this first in the hope that it's good enough for most use cases.

Checklist for Contributors

Testing

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

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

Manual testing

1. Run the UI storybook yarn storybook:ui
2. View the example story that should show TOC: http://localhost:6006/?path=/docs/addons-docs-yabbadabbadooo--docs
3. Uncomment the following line in code/.storybook/preview.tsx:

    toc: {
      // Uncomment this to test disabling toc in unattached MDX files
      // disableUnattachedMdx: true,
    },

4. TOC should disappear from the page on HMR

🦋 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>

Greptile Summary

This PR introduces a new parameter to disable the Table of Contents on unattached MDX files, with updates across configuration, documentation examples, and core rendering logic in DocsContainer.

• Modified /code/.storybook/preview.tsx to add a new, commented docs.toc.disableUnattachedMdx parameter for testing.
• Updated /code/addons/docs/template/stories/docs2/Title.mdx to include various heading formats to test TOC behavior.
• Adjusted /code/lib/blocks/src/blocks/DocsContainer.tsx to conditionally render the TOC based on the new parameter.
• Enhanced /docs/writing-docs/autodocs.mdx docs to explain the disabling option for unattached MDX files.

[greptile-apps]

LGTM

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit d1c977d

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

---

☁️ Nx Cloud last updated this comment at 2025-10-06 13:52:29 UTC

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch shilman/disable-toc-unattached-mdx

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[storybook-app-bot]

Package Benchmarks

^{Commit: d1c977d, ran on 6 October 2025 at 13:36:51 UTC}

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

@storybook/builder-webpack5

	Before	After	Difference
Dependency count	187	187	0
Self size	68 KB	68 KB	0 B
Dependency size	31.79 MB	31.82 MB	🚨 +28 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/angular

	Before	After	Difference
Dependency count	187	187	0
Self size	126 KB	126 KB	0 B
Dependency size	29.95 MB	29.97 MB	🚨 +28 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/ember

	Before	After	Difference
Dependency count	191	191	0
Self size	17 KB	17 KB	0 B
Dependency size	28.50 MB	28.53 MB	🚨 +28 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/nextjs

	Before	After	Difference
Dependency count	532	532	0
Self size	950 KB	950 KB	0 B
Dependency size	58.49 MB	58.52 MB	🚨 +28 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/react-webpack5

	Before	After	Difference
Dependency count	272	272	0
Self size	25 KB	25 KB	0 B
Dependency size	43.45 MB	43.48 MB	🚨 +28 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/server-webpack5

	Before	After	Difference
Dependency count	199	199	0
Self size	17 KB	17 KB	0 B
Dependency size	33.04 MB	33.07 MB	🚨 +28 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/cli

	Before	After	Difference
Dependency count	187	187	0
Self size	920 KB	920 KB	0 B
Dependency size	79.83 MB	79.86 MB	🚨 +28 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/codemod

	Before	After	Difference
Dependency count	169	169	0
Self size	35 KB	35 KB	0 B
Dependency size	76.26 MB	76.28 MB	🚨 +28 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/preset-react-webpack

	Before	After	Difference
Dependency count	170	170	0
Self size	21 KB	21 KB	0 B
Dependency size	30.94 MB	30.97 MB	🚨 +28 KB 🚨
Bundle Size Analyzer	Link	Link