From 15f676872605a46bdc3c436c1a51733054150759 Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Thu, 13 Jul 2023 15:30:42 +0100 Subject: [PATCH 1/3] Adds TOC documentation --- .../angular/my-component-disable-toc.ts.mdx | 21 +++++ .../common/my-component-disable-toc.js.mdx | 17 ++++ .../my-component-disable-toc.ts-4-9.mdx | 22 +++++ .../common/my-component-disable-toc.ts.mdx | 22 +++++ .../storybook-preview-custom-toc.js.mdx | 20 +++++ .../storybook-preview-custom-toc.ts.mdx | 25 ++++++ .../storybook-preview-enable-toc.js.mdx | 11 +++ .../storybook-preview-enable-toc.ts.mdx | 16 ++++ .../my-component-disable-toc.js.mdx | 15 ++++ .../my-component-disable-toc.ts.mdx | 18 ++++ docs/writing-docs/autodocs.md | 87 ++++++++++++++++++- 11 files changed, 270 insertions(+), 4 deletions(-) create mode 100644 docs/snippets/angular/my-component-disable-toc.ts.mdx create mode 100644 docs/snippets/common/my-component-disable-toc.js.mdx create mode 100644 docs/snippets/common/my-component-disable-toc.ts-4-9.mdx create mode 100644 docs/snippets/common/my-component-disable-toc.ts.mdx create mode 100644 docs/snippets/common/storybook-preview-custom-toc.js.mdx create mode 100644 docs/snippets/common/storybook-preview-custom-toc.ts.mdx create mode 100644 docs/snippets/common/storybook-preview-enable-toc.js.mdx create mode 100644 docs/snippets/common/storybook-preview-enable-toc.ts.mdx create mode 100644 docs/snippets/web-components/my-component-disable-toc.js.mdx create mode 100644 docs/snippets/web-components/my-component-disable-toc.ts.mdx diff --git a/docs/snippets/angular/my-component-disable-toc.ts.mdx b/docs/snippets/angular/my-component-disable-toc.ts.mdx new file mode 100644 index 000000000000..6882159c2318 --- /dev/null +++ b/docs/snippets/angular/my-component-disable-toc.ts.mdx @@ -0,0 +1,21 @@ +```ts +// MyComponent.stories.ts + +import type { Meta } from '@storybook/angular'; + +import { MyComponent } from './MyComponent.component'; + +const meta: Meta = { + component: MyComponent, + tags: ['autodocs'], + parameters: { + docs: { + toc: { + disable: true, // 👈 Disables the table of contents + }, + }, + }, +}; + +export default meta; +``` diff --git a/docs/snippets/common/my-component-disable-toc.js.mdx b/docs/snippets/common/my-component-disable-toc.js.mdx new file mode 100644 index 000000000000..e78fca95fafd --- /dev/null +++ b/docs/snippets/common/my-component-disable-toc.js.mdx @@ -0,0 +1,17 @@ +```js +// MyComponent.stories.js|jsx + +import { MyComponent } from './MyComponent'; + +export default { + component: MyComponent, + tags: ['autodocs'], + parameters: { + docs: { + toc: { + disable: true, // 👈 Disables the table of contents + }, + }, + }, +}; +``` diff --git a/docs/snippets/common/my-component-disable-toc.ts-4-9.mdx b/docs/snippets/common/my-component-disable-toc.ts-4-9.mdx new file mode 100644 index 000000000000..b61b5eca2a87 --- /dev/null +++ b/docs/snippets/common/my-component-disable-toc.ts-4-9.mdx @@ -0,0 +1,22 @@ +```ts +// MyComponent.stories.ts|tsx + +// Replace your-framework with the name of your framework +import type { Meta } from '@storybook/your-framework'; + +import { MyComponent } from './MyComponent'; + +const meta = { + component: MyComponent, + tags: ['autodocs'], + parameters: { + docs: { + toc: { + disable: true, // 👈 Disables the table of contents + }, + }, + }, +} satisfies Meta; + +export default meta; +``` diff --git a/docs/snippets/common/my-component-disable-toc.ts.mdx b/docs/snippets/common/my-component-disable-toc.ts.mdx new file mode 100644 index 000000000000..eda13b92ab13 --- /dev/null +++ b/docs/snippets/common/my-component-disable-toc.ts.mdx @@ -0,0 +1,22 @@ +```ts +// MyComponent.stories.ts|tsx + +// Replace your-framework with the name of your framework +import type { Meta } from '@storybook/your-framework'; + +import { MyComponent } from './MyComponent'; + +const meta: Meta = { + component: MyComponent, + tags: ['autodocs'], + parameters: { + docs: { + toc: { + disable: true, // 👈 Disables the table of contents + }, + }, + }, +}; + +export default meta; +``` diff --git a/docs/snippets/common/storybook-preview-custom-toc.js.mdx b/docs/snippets/common/storybook-preview-custom-toc.js.mdx new file mode 100644 index 000000000000..0d326085ae03 --- /dev/null +++ b/docs/snippets/common/storybook-preview-custom-toc.js.mdx @@ -0,0 +1,20 @@ +```js +// .storybook/preview.js + +export default { + parameters: { + docs: { + toc: { + contentsSelector: '.sbdocs-content', + headingSelector: 'h1, h2, h3', + ignoreSelector: '#primary', + title: 'Table of Contents', + disable: false, + unsafeTocbotOptions: { + orderedList: false, + }, + }, + }, + }, +}; +``` diff --git a/docs/snippets/common/storybook-preview-custom-toc.ts.mdx b/docs/snippets/common/storybook-preview-custom-toc.ts.mdx new file mode 100644 index 000000000000..366447ac9772 --- /dev/null +++ b/docs/snippets/common/storybook-preview-custom-toc.ts.mdx @@ -0,0 +1,25 @@ +```ts +// .storybook/preview.ts + +// Replace your-framework with the framework you are using (e.g., react, vue3) +import { Preview } from '@storybook/your-framework'; + +const preview: Preview = { + parameters: { + docs: { + toc: { + contentsSelector: '.sbdocs-content', + headingSelector: 'h1, h2, h3', + ignoreSelector: '#primary', + title: 'Table of Contents', + disable: false, + unsafeTocbotOptions: { + orderedList: false, + }, + }, + }, + }, +}; + +export default preview; +``` diff --git a/docs/snippets/common/storybook-preview-enable-toc.js.mdx b/docs/snippets/common/storybook-preview-enable-toc.js.mdx new file mode 100644 index 000000000000..42b7a5a00d49 --- /dev/null +++ b/docs/snippets/common/storybook-preview-enable-toc.js.mdx @@ -0,0 +1,11 @@ +```js +// .storybook/preview.js + +export default { + parameters: { + docs: { + toc: true, // 👈 Enables the table of contents + }, + }, +}; +``` diff --git a/docs/snippets/common/storybook-preview-enable-toc.ts.mdx b/docs/snippets/common/storybook-preview-enable-toc.ts.mdx new file mode 100644 index 000000000000..83adea500cf5 --- /dev/null +++ b/docs/snippets/common/storybook-preview-enable-toc.ts.mdx @@ -0,0 +1,16 @@ +```ts +// .storybook/preview.ts + +// Replace your-framework with the framework you are using (e.g., react, vue3) +import { Preview } from '@storybook/your-framework'; + +const preview: Preview = { + parameters: { + docs: { + toc: true, // 👈 Enables the table of contents + }, + }, +}; + +export default preview; +``` diff --git a/docs/snippets/web-components/my-component-disable-toc.js.mdx b/docs/snippets/web-components/my-component-disable-toc.js.mdx new file mode 100644 index 000000000000..9da978dc1bbf --- /dev/null +++ b/docs/snippets/web-components/my-component-disable-toc.js.mdx @@ -0,0 +1,15 @@ +```js +// MyComponent.stories.js + +export default { + component: 'my-component', + tags: ['autodocs'], + parameters: { + docs: { + toc: { + disable: true, // 👈 Disables the table of contents + }, + }, + }, +}; +``` diff --git a/docs/snippets/web-components/my-component-disable-toc.ts.mdx b/docs/snippets/web-components/my-component-disable-toc.ts.mdx new file mode 100644 index 000000000000..d01661634924 --- /dev/null +++ b/docs/snippets/web-components/my-component-disable-toc.ts.mdx @@ -0,0 +1,18 @@ +```ts +// MyComponent.stories.ts + +import type { Meta } from '@storybook/web-components'; + +const meta: Meta = { + component: 'my-component', + tags: ['autodocs'], + parameters: { + docs: { + toc: { + disable: true, // 👈 Disables the table of contents + }, + }, + }, +}; +export default meta; +``` diff --git a/docs/writing-docs/autodocs.md b/docs/writing-docs/autodocs.md index fa61f3668aef..5a992dba02d9 100644 --- a/docs/writing-docs/autodocs.md +++ b/docs/writing-docs/autodocs.md @@ -46,10 +46,10 @@ By default, Storybook offers zero-config support for documentation and automatic -| Option | Description | -| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Option | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `autodocs` | Configures auto-generated documentation pages. Available options: `true`, `false`,`tag` (default). `true`/`false` enable/disable autodocs globally. `tag` allows you to opt in per component by adding the `tags: ['autodocs']` annotation in the component's default export.
Default: `docs: { autodocs: false }` | -| `defaultName` | Renames the auto-generated documentation page
Default: `docs: { defaultName: 'Documentation' }` | +| `defaultName` | Renames the auto-generated documentation page
Default: `docs: { defaultName: 'Documentation' }` | ### Write a custom template @@ -68,7 +68,7 @@ To replace the default documentation template used by Storybook, you can extend
-💡 Internally, Storybook uses a similar implementation to generate the default template. See the Doc Blocks [API reference](./doc-blocks.md#available-blocks) if you want to learn more about how Doc Blocks work. +💡 Internally, Storybook uses a similar implementation to generate the default template. See the Doc Blocks [API reference](./doc-blocks.md#available-blocks) to learn more about how Doc Blocks work.
@@ -111,6 +111,69 @@ Then you can use it in your `.storybook/preview.js` or an individual story file +### Generate a table of contents + +Storybook's auto-generated documentation pages can be quite long and difficult to navigate. To help with this, you can enable the table of contents feature to provide a quick overview of the documentation page and allow users to jump to a specific section. To enable it, extend your Storybook UI configuration file (i.e., `.storybook/preview.js`) and provide a `docs` [parameter](../writing-stories/parameters.md#global-parameters) with a `toc` property. + + + + + + + +### Configure the table of contents + +To simplify navigation, the table of contents on the documentation page will only show the `h3` headings that are automatically generated. However, if you want to customize the table of contents, you can add more parameters to the `toc` property. The following options and examples of how to use them are available. + +| Option | Description | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `contentsSelector` | Defines the container's CSS selector for search for the headings
`toc: { contentsSelector: '.sbdocs-content' }` | +| `disable` | Hides the table of contents for the documentation pages
`toc: { disable: true }` | +| `headingSelector` | Defines the list of headings to feature in the table of contents
`toc: { headingSelector: 'h1, h2, h3' }` | +| `ignoreSelector` | Configures the table of contents to ignore specific headings or stories
`toc: { ignoreSelector: 'h2' }` | +| `title` | Defines a title caption for the table of contents.
Accepts one of: `string`, `null`, React element
`toc: { title: 'Table of Contents' }` | +| `unsafeTocbotOptions` | Provides additional [`TocBot`](https://tscanlin.github.io/tocbot/) configuration options
`toc: { unsafeTocbotOptions: { orderedList: true } }` | + +
+ +ℹī¸ The `contentsSelector`, `headingSelector`, and `ignoreSelector` properties allow additional customization. For more information on using them, see the [`Tocbot` documentation](https://tscanlin.github.io/tocbot/). + +
+ + + + + + + +#### Component-level configuration + +If you want to customize the table of contents for a specific story, you can include a `toc` property in the story's default export and provide the required [configuration](#configure-the-table-of-contents). For example, if you need to hide the table of contents for a specific story, adjust your story as follows: + + + + + + + ### Customize component documentation Creating automated documentation with Storybook's Autodocs provides you with the starting point to build a sustainable documentation pattern. Nevertheless, it may not be suited for every case, and you may want to extend it and provide additional information. We recommend combining [MDX](./mdx.md) alongside Storybook's [Doc Blocks](./doc-blocks.md) for such cases to author your documentation. @@ -170,6 +233,22 @@ Out of the box, Storybook has a set of components that you can use to customize ## Troubleshooting +### The table of contents doesn't render as expected + +When using Autodocs's table of contents, you may encounter situations where it appears differently than expected. To help you resolve these problems, we have compiled a list of possible scenarios that may cause issues. If you've run into any of the items listed below and you're interested in helping us improve the support for this feature, we encourage you to reach out to the maintainers using the default communication channels (e.g., [Discord server](https://discord.com/channels/486522875931656193/570426522528382976), [GitHub issues](https://github.com/storybookjs/storybook/issues)). + +#### With simple documentation pages + +If you have a documentation page with only one matching heading and create a table of contents for it, the table of contents will not be hidden by default. A potential solution for this issue would be to add a second heading or turn it off entirely. + +#### With small screens + +If the screen width is less than 1200px, the table of contents will be hidden by default. Currently, there's no built-in solution for this issue that doesn't impact the documentation page's style compatibility. + +#### With MDX + +If you're writing [unattached documentation](./mdx.md#writing-unattached-documentation) using MDX, you cannot customize the table of contents primarily due to the lack of support for defining parameters based on the current implementation. As a result, the table of contents will always revert to the default [configuration](#configure-the-table-of-contents) provided globally. + ### The auto-generated documentation is not showing up in a monorepo setup Out of the box, Storybook's Autodocs feature is built to generate documentation for your stories automatically. Nevertheless, if you're working with a monorepo setup (e.g., [`Yarn Workspaces`](https://yarnpkg.com/features/workspaces), [`pnpm Workspaces`](https://pnpm.io/workspaces)), you may run into issues where part of the documentation may not be generated for you. To help you troubleshoot those issues, we've prepared some recommendations that might help you. From 950218ff2d93f5f0698e3b9241ffe53a1237777c Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Thu, 13 Jul 2023 17:43:15 +0100 Subject: [PATCH 2/3] Fixes autodocs webcomponents snippets --- docs/snippets/web-components/button-story-auto-docs.js.mdx | 2 +- docs/snippets/web-components/button-story-auto-docs.ts.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/snippets/web-components/button-story-auto-docs.js.mdx b/docs/snippets/web-components/button-story-auto-docs.js.mdx index d2f2263f49be..c45b64d54fde 100644 --- a/docs/snippets/web-components/button-story-auto-docs.js.mdx +++ b/docs/snippets/web-components/button-story-auto-docs.js.mdx @@ -4,7 +4,7 @@ export default { component: 'custom-button', //👇 Enables auto-generated documentation for the component story - tags: ['docsPage'], + tags: ['autodocs'], argTypes: { backgroundColor: { control: 'color' }, }, diff --git a/docs/snippets/web-components/button-story-auto-docs.ts.mdx b/docs/snippets/web-components/button-story-auto-docs.ts.mdx index 5de4291cfd00..10bed84c1567 100644 --- a/docs/snippets/web-components/button-story-auto-docs.ts.mdx +++ b/docs/snippets/web-components/button-story-auto-docs.ts.mdx @@ -6,7 +6,7 @@ import type { Meta, StoryObj } from '@storybook/web-components'; const Meta: Meta = { component: 'custom-button', //👇 Enables auto-generated documentation for the component story - tags: ['docsPage'], + tags: ['autodocs'], argTypes: { backgroundColor: { control: 'color' }, }, From 2035c5f14f966f78bdb6f0e93fd24572f81de6bd Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Thu, 13 Jul 2023 19:28:39 +0100 Subject: [PATCH 3/3] Addressing feedback --- docs/writing-docs/autodocs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing-docs/autodocs.md b/docs/writing-docs/autodocs.md index 5a992dba02d9..67f8e562fd6d 100644 --- a/docs/writing-docs/autodocs.md +++ b/docs/writing-docs/autodocs.md @@ -128,7 +128,7 @@ Storybook's auto-generated documentation pages can be quite long and difficult t ### Configure the table of contents -To simplify navigation, the table of contents on the documentation page will only show the `h3` headings that are automatically generated. However, if you want to customize the table of contents, you can add more parameters to the `toc` property. The following options and examples of how to use them are available. +By default, the table of contents on the documentation page will only show the `h3` headings that are automatically generated. However, if you want to customize the table of contents, you can add more parameters to the `toc` property. The following options and examples of how to use them are available. | Option | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |