Added documentation for the table of contents

[txgh25]

Closes #33817

Description

Added the documentation for the table of contents. Attempted to match the formatting of other documentations.

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

Caution

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

Documentation

• 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 publish.yml --field pr=<PR_NUMBER>

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation for the new TableOfContents doc block, including description and usage guidance.
  • Included an example snippet demonstrating rendering and integration.
  • Documented all public props with types and recommended defaults.
  • Updated the docs index to reference the new TableOfContents block and noted accepted namespace parameters.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Walkthrough

Adds a new TableOfContents MDX docs page describing the TableOfContents doc block (frontmatter, description, example, and props) and inserts a reference/entry for this block into the doc-blocks guide (docs/writing-docs/doc-blocks.mdx).

Changes

Cohort / File(s)	Summary
TableOfContents documentation docs/api/doc-blocks/doc-block-tableofcontents.mdx	New MDX page added documenting the TableOfContents doc block: frontmatter, description, Storybook "sidebar" callout, example MDX snippet, usage code block, and props table (title, disable, headingSelector, contentsSelector, ignoreSelector, className, unsafeTocbotOptions, channel).
Doc-blocks guide update docs/writing-docs/doc-blocks.mdx	Inserted a TableOfContents entry into the doc-blocks guide (placed between Subtitle and Title). Adds a link to the new API doc page and an info callout noting accepted parameters under parameters.docs.toc.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (4)

docs/api/doc-blocks/doc-block-tableofcontents.mdx (3)

89-93: Consider noting that channel is an advanced/internal prop

Most users will never need to override this — the block automatically uses Storybook's default channel. A brief note prevents confusion.

✏️ Suggested addition

 Storybook's event channel to be used for navigation when clicking items in the table.
+
+_In most cases you do not need to set this; the block uses Storybook's default channel automatically._

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/api/doc-blocks/doc-block-tableofcontents.mdx` around lines 89 - 93,
Update the `channel` prop documentation in doc-block-tableofcontents.mdx to
indicate that `channel` is an advanced/internal prop that most users should not
override because the block uses Storybook's default channel automatically; add a
short sentence after the Type: `Channel` line clarifying it's for advanced use
or internal integration and that default behavior covers common cases so
overriding is rarely necessary.

---

3-5: Frontmatter uses 4-space indentation; the rest of the docs use 2-space.

The sibling file doc-blocks.mdx and other doc-block pages use 2-space indentation under sidebar:. YAML parses both, but the inconsistency could trip up automated linting.

🔧 Suggested fix

 sidebar: 
-    order: 18
-    title: TableOfContents
+  order: 18
+  title: TableOfContents

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/api/doc-blocks/doc-block-tableofcontents.mdx` around lines 3 - 5, Fix
the frontmatter indentation under the "sidebar:" block by changing the 4-space
indented keys to 2-space indentation so it matches the rest of the docs;
specifically update the "order:" and "title:" lines under the "sidebar:"
frontmatter to use 2 spaces before them instead of 4 to keep consistency with
other doc-block pages like doc-blocks.mdx and avoid linting issues.

---

48-52: disable prop description is ambiguous about direction

"Enables or disables" doesn't tell users which boolean value hides the block. Compare with how other blocks document this (e.g. disable: true disables rendering).

✏️ Suggested fix

-Enables or disables the rendering of the table.
+If `true`, the block is not rendered.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/api/doc-blocks/doc-block-tableofcontents.mdx` around lines 48 - 52, The
description for the `disable` prop is ambiguous; update the `disable` prop
documentation in doc-block-tableofcontents.mdx to explicitly state the boolean
direction (e.g., "When true, the table of contents block is hidden; when false,
it is rendered") and match the wording used by other blocks (refer to other docs
that say `disable: true` disables rendering) so readers know which value turns
the block off.

docs/writing-docs/doc-blocks.mdx (1)

243-252: Missing screenshot — inconsistent with all other block entries

Every other entry in the Available blocks section includes a ![Screenshot of ...] image. The TableOfContents entry is the only one without one, making the section visually inconsistent.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/writing-docs/doc-blocks.mdx` around lines 243 - 252, Add the missing
screenshot line to the TableOfContents block entry so it matches other block
entries: insert a markdown image placeholder like `![Screenshot of
TableOfContents block](<path-or-filename>)` immediately under the "###
[TableOfContents]" heading (in the Available blocks section) so the
TableOfContents entry follows the same pattern as the other blocks; ensure the
alt text references "TableOfContents" and the image filename/path follows the
repo's naming convention for block screenshots.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/api/doc-blocks/doc-block-tableofcontents.mdx`:
- Line 19: The MDX example uses an unclosed JSX tag for the Meta component;
update the usage of Meta (the <Meta title="Docs/TableOfContents"> instance) to
be a self-closing tag so the MDX parser can parse it (change it to a properly
closed Meta tag, e.g., make it self-closing). Ensure the fix is applied to the
Meta usage in the doc-block TableOfContents example.
- Around line 10-12: Fix the typo in the Callout text: change the namespace
reference from `parameters.doc.toc` to `parameters.docs.toc` so the example
matches Storybook's docs API; update the string inside the <Callout
variant="info"> that currently mentions `parameters.doc.toc` to
`parameters.docs.toc` (ensuring any surrounding example text or inline code
samples in the same block are updated too).

In `@docs/writing-docs/doc-blocks.mdx`:
- Around line 245-249: Update the documentation text that currently says
"Accepts parameters in the namespace `parameters.docs.story`" to the correct
namespace for the TableOfContents block: `parameters.docs.toc`; locate the
callout describing TableOfContents and replace the incorrect namespace string so
it reads that TableOfContents accepts parameters in `parameters.docs.toc`,
keeping the surrounding Callout/variant info intact.

---

Nitpick comments:
In `@docs/api/doc-blocks/doc-block-tableofcontents.mdx`:
- Around line 89-93: Update the `channel` prop documentation in
doc-block-tableofcontents.mdx to indicate that `channel` is an advanced/internal
prop that most users should not override because the block uses Storybook's
default channel automatically; add a short sentence after the Type: `Channel`
line clarifying it's for advanced use or internal integration and that default
behavior covers common cases so overriding is rarely necessary.
- Around line 3-5: Fix the frontmatter indentation under the "sidebar:" block by
changing the 4-space indented keys to 2-space indentation so it matches the rest
of the docs; specifically update the "order:" and "title:" lines under the
"sidebar:" frontmatter to use 2 spaces before them instead of 4 to keep
consistency with other doc-block pages like doc-blocks.mdx and avoid linting
issues.
- Around line 48-52: The description for the `disable` prop is ambiguous; update
the `disable` prop documentation in doc-block-tableofcontents.mdx to explicitly
state the boolean direction (e.g., "When true, the table of contents block is
hidden; when false, it is rendered") and match the wording used by other blocks
(refer to other docs that say `disable: true` disables rendering) so readers
know which value turns the block off.

In `@docs/writing-docs/doc-blocks.mdx`:
- Around line 243-252: Add the missing screenshot line to the TableOfContents
block entry so it matches other block entries: insert a markdown image
placeholder like `![Screenshot of TableOfContents block](<path-or-filename>)`
immediately under the "### [TableOfContents]" heading (in the Available blocks
section) so the TableOfContents entry follows the same pattern as the other
blocks; ensure the alt text references "TableOfContents" and the image
filename/path follows the repo's naming convention for block screenshots.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

docs/api/doc-blocks/doc-block-tableofcontents.mdx (2)

89-93: channel prop lacks guidance on when/why a user would set it

The current description ("Storybook's event channel to be used for navigation when clicking items in the table") reads like an internal implementation detail. Without any note that this is automatically injected by Storybook and should rarely be set manually, users may be confused about whether they need to supply it.

Consider adding a note such as: "This is automatically injected by Storybook; you typically do not need to set this prop."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/api/doc-blocks/doc-block-tableofcontents.mdx` around lines 89 - 93,
Update the `channel` prop documentation for the TableOfContents component to
clarify usage: state that `channel` (type `Channel`) is automatically injected
by Storybook and normally should not be set manually, and add a short example
sentence like "This is automatically injected by Storybook; you typically do not
need to set this prop." Keep the existing description about it being used for
navigation when clicking items but prepend or append the note so users know it's
rarely required to supply themselves.

---

48-52: disable description is misleading — it only disables, never enables

"Enables or disables the rendering of the table" implies the prop is a toggle for both directions. Since the prop is named disable, a truthy value only suppresses rendering. The current phrasing could mislead users into thinking disable={false} actively enables something that was otherwise off.

✏️ Proposed fix

-Enables or disables the rendering of the table.
+When set to `true`, prevents the `TableOfContents` from rendering.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/api/doc-blocks/doc-block-tableofcontents.mdx` around lines 48 - 52,
Update the `disable` prop description in doc-block-tableofcontents.mdx to
clarify its one-way behavior: replace "Enables or disables the rendering of the
table." with a statement that `disable` suppresses rendering when true (e.g.,
"When true, disables/suppresses rendering of the table of contents; when false
or omitted, the table is rendered by default."), referencing the `disable` prop
name so readers understand it does not actively enable rendering when set to
false.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/api/doc-blocks/doc-block-tableofcontents.mdx`:
- Line 16: The code fence title currently uses the misleading filename
"ButtonDocs.mdx"; update the fenced code block title string to reflect the
TableOfContents example (e.g., change the title from "ButtonDocs.mdx" to
"MyDocs.mdx" or a more descriptive name like "TableOfContentsDocs.mdx") so the
example filename matches the documented feature; locate the fenced block
containing ```md title="ButtonDocs.mdx" and replace that title text accordingly.

---

Duplicate comments:
In `@docs/api/doc-blocks/doc-block-tableofcontents.mdx`:
- Line 19: The MDX example contains an unclosed Meta tag: the snippet shows Meta
title="Docs/TableOfContents" without being self-closed, which will cause MDX
parse errors; update the usage example in
docs/api/doc-blocks/doc-block-tableofcontents.mdx to use a self-closing Meta tag
(i.e., close the Meta element properly) so the example is valid MDX and
copy-paste safe, and verify the surrounding MDX still renders correctly.
- Around line 10-12: Update the Callout text in the doc block by capitalizing
"storybook" to "Storybook" so the sentence reads "To use the Storybook "sidebar"
table of contents layout, it should be configured with `parameters.docs.toc`";
edit the Callout block string (the line starting with To use the storybook...)
to apply this capitalization change.

---

Nitpick comments:
In `@docs/api/doc-blocks/doc-block-tableofcontents.mdx`:
- Around line 89-93: Update the `channel` prop documentation for the
TableOfContents component to clarify usage: state that `channel` (type
`Channel`) is automatically injected by Storybook and normally should not be set
manually, and add a short example sentence like "This is automatically injected
by Storybook; you typically do not need to set this prop." Keep the existing
description about it being used for navigation when clicking items but prepend
or append the note so users know it's rarely required to supply themselves.
- Around line 48-52: Update the `disable` prop description in
doc-block-tableofcontents.mdx to clarify its one-way behavior: replace "Enables
or disables the rendering of the table." with a statement that `disable`
suppresses rendering when true (e.g., "When true, disables/suppresses rendering
of the table of contents; when false or omitted, the table is rendered by
default."), referencing the `disable` prop name so readers understand it does
not actively enable rendering when set to false.