diff --git a/docs/api/doc-blocks/doc-block-tableofcontents.mdx b/docs/api/doc-blocks/doc-block-tableofcontents.mdx new file mode 100644 index 000000000000..96b282affee7 --- /dev/null +++ b/docs/api/doc-blocks/doc-block-tableofcontents.mdx @@ -0,0 +1,90 @@ +--- +title: 'TableOfContents' +sidebar: + order: 14 + title: TableOfContents +--- + +The `TableOfContents` block renders a table of contents for the current documentation page, allowing users to navigate between sections quickly. It appears as a fixed sidebar on the right side of the documentation page and is hidden on smaller screens (below 768px). + +The table of contents is enabled and configured via the `docs.toc` [parameter](../../writing-stories/parameters.mdx) rather than being added directly to MDX files. When enabled, it is automatically rendered alongside the page content by [Storybook's docs container](../doc-blocks/doc-block-meta.mdx). + + + + For a step-by-step guide on enabling and customizing the table of contents, see the [Generate a table of contents](../../writing-docs/autodocs.mdx#generate-a-table-of-contents) section in the Autodocs documentation. + + + +## Enabling the table of contents + +Enable the table of contents globally in your Storybook preview configuration: + +{/* prettier-ignore-start */} + + + +{/* prettier-ignore-end */} + +You can also enable or disable it for specific components in their stories file: + +{/* prettier-ignore-start */} + + + +{/* prettier-ignore-end */} + +## `toc` parameter options + +The `docs.toc` parameter accepts either `true` (to enable with defaults) or an object with the following properties: + +### `contentsSelector` + +Type: `string` + +Default: `'.sbdocs-content'` + +CSS selector for the container to search for headings. Use this if you have a custom docs page layout. + +### `disable` + +Type: `boolean` + +Default: `false` + +When `true`, it hides the table of contents for the documentation page. A hidden (empty) container is still rendered to preserve the page layout. + +### `headingSelector` + +Type: `string` + +Default: `'h3'` + +CSS selector that defines which heading levels to include in the table of contents. For example, use `'h1, h2, h3'` to include the top three heading levels. + +### `ignoreSelector` + +Type: `string` + +Default: `'.docs-story *, .skip-toc'` + +CSS selector for headings to exclude from the table of contents. By default, headings inside story blocks are excluded. To also exclude a specific heading, add the `skip-toc` class to it. + +### `title` + +Type: `string | null | ReactElement` + +Default: `'Table of contents'` (visually hidden) + +Text or element to display as the title above the table of contents. Set to `null` to render no title. When a string is provided, it is rendered as a visually hidden `

` by default; pass a non-empty string to make it visible. + +### `unsafeTocbotOptions` + +Type: `object` + +Provides additional configuration options passed directly to the underlying [`Tocbot`](https://tscanlin.github.io/tocbot/) library. These options are not guaranteed to remain available in future versions of Storybook. + +{/* prettier-ignore-start */} + + + +{/* prettier-ignore-end */} diff --git a/docs/api/doc-blocks/doc-block-title.mdx b/docs/api/doc-blocks/doc-block-title.mdx index e5ffc02a82f0..1c40d97e7499 100644 --- a/docs/api/doc-blocks/doc-block-title.mdx +++ b/docs/api/doc-blocks/doc-block-title.mdx @@ -1,7 +1,7 @@ --- title: 'Title' sidebar: - order: 14 + order: 15 title: Title --- diff --git a/docs/api/doc-blocks/doc-block-typeset.mdx b/docs/api/doc-blocks/doc-block-typeset.mdx index 7e507541f7f8..f7c49b5dabe6 100644 --- a/docs/api/doc-blocks/doc-block-typeset.mdx +++ b/docs/api/doc-blocks/doc-block-typeset.mdx @@ -1,7 +1,7 @@ --- title: 'Typeset' sidebar: - order: 15 + order: 16 title: Typeset --- diff --git a/docs/api/doc-blocks/doc-block-unstyled.mdx b/docs/api/doc-blocks/doc-block-unstyled.mdx index 4ef7db0320a2..addc5f677448 100644 --- a/docs/api/doc-blocks/doc-block-unstyled.mdx +++ b/docs/api/doc-blocks/doc-block-unstyled.mdx @@ -1,7 +1,7 @@ --- title: 'Unstyled' sidebar: - order: 16 + order: 17 title: Unstyled --- diff --git a/docs/api/doc-blocks/doc-block-useof.mdx b/docs/api/doc-blocks/doc-block-useof.mdx index beb560eb48d9..a47517330bad 100644 --- a/docs/api/doc-blocks/doc-block-useof.mdx +++ b/docs/api/doc-blocks/doc-block-useof.mdx @@ -1,7 +1,7 @@ --- title: 'useOf' sidebar: - order: 17 + order: 18 title: useOf --- diff --git a/docs/writing-docs/doc-blocks.mdx b/docs/writing-docs/doc-blocks.mdx index cd360b99ce0d..ea52c2ada97d 100644 --- a/docs/writing-docs/doc-blocks.mdx +++ b/docs/writing-docs/doc-blocks.mdx @@ -240,6 +240,16 @@ The `Subtitle` block can serve as a secondary heading for your docs entry. ![Screenshot of Subtitle block](../_assets/api/doc-block-title-subtitle-description.png) +### [TableOfContents](../api/doc-blocks/doc-block-tableofcontents.mdx) + + + + Accepts parameters in the namespace `parameters.docs.toc`. + + + +The `TableOfContents` block renders a table of contents for the current documentation page, allowing users to quickly navigate between sections. It appears as a fixed sidebar on the right side of the page. + ### [Title](../api/doc-blocks/doc-block-title.mdx) The `Title` block serves as the primary heading for your docs entry. It is typically used to provide the component or page name.