storybook
storybook copied to clipboard
storybookjs
[Bug]: Addon-Docs doesn't render Canvas/Docs tabs in v7
Describe the bug
Our team is used to using the Canvas/Docs tabs provided by addon-docs.
Storybook 6 repro
Storybook 7 repro
To Reproduce
I created a repro using npx storybook@next repro and choosing "React 18 Webpack5 (TS)" and provide that unmodified here: https://github.com/swrobel/storybook-7-docs-repro
System
Environment Info:
System:
OS: macOS 13.2.1
CPU: (10) arm64 Apple M1 Max
Binaries:
Node: 18.15.0 - /opt/homebrew/bin/node
Yarn: 1.22.19 - /opt/homebrew/bin/yarn
npm: 9.5.0 - /opt/homebrew/bin/npm
Browsers:
Chrome: 111.0.5563.64
Firefox: 111.0
Safari: 16.3
npmPackages:
@storybook/addon-essentials: ^7.0.0-rc.5 => 7.0.0-rc.5
@storybook/addon-interactions: ^7.0.0-rc.5 => 7.0.0-rc.5
@storybook/addon-links: ^7.0.0-rc.5 => 7.0.0-rc.5
@storybook/blocks: ^7.0.0-rc.5 => 7.0.0-rc.5
@storybook/react: ^7.0.0-rc.5 => 7.0.0-rc.5
@storybook/react-webpack5: ^7.0.0-rc.5 => 7.0.0-rc.5
@storybook/testing-library: ^0.0.14-next.1 => 0.0.14-next.1
Additional context
No response
This is an intentional UI change in 7.0, which is a breaking release. If this change is negatively affecting you, can you describe the problem here?
Thank you for the reply! As I mentioned, our team is used to using the Canvas/Docs tabs provided by addon-docs. I didn't see anything in the release notes about this behavior change, and in fact, the docs for the RC that I linked to still show these tabs in the screenshots.
What's the reason for the change, and what's the new expected usage pattern? I though this was the whole purpose of addon-docs...
I found this mention in the Storybook 7 blog post, but as I mentioned, the addon-docs README is still giving outdated information. I suppose the best fix here is to update the documentation.
For those who also want the closest behavior to Storybook 6 + addon-docs (which required zero-config to show the Docs tab), you'll need to add the following to your main.js:
docs: {
autodocs: true,
}
The Canvas/Docs tabs are also extremely useful to our teams - we often use Storybook for fully featured pages and now viewing the pages and page variations inside of the Autodocs page is not as helpful.
Examples:
- ContentX List Page
- ContentX List Page w/ Filters
- ContentX List Page - Admin View
- ContentX List Page - Future State
Each of these pages are used by different teams and having direct access to the page and it's specific docs is important. In Storybook 6 it would automatically generate these, now it appears we have to create MDX files for each page now if we want separate docs?
I think adding an option in the storybook configuration would be good to switch to the previous behavior. By doing this everyone will be happy with the change.
@dylanjmcdonald is the scenario you're missing an auto-generated docs page for each story? were you using the default DocsPage documentation, or did you customize the template?
I also need this Cacas/Docs tab toggle for the following reason: some components will have multiple examples, each with a docs file.
I was manually upgrading from Storybook 6 to 7 and noticed the "Docs" tab disappeared with no errors and I couldn't find any documentation explaining this breaking change until I found this GitHub issue. The official docs for the addon shows a Docs tab. A bit odd
My project has stories.tsx for each of my React components and I rely on the addon + TypeScript comments to generate the docs. I customised the DocsContainer to sprinkle on some theming (I also use storybook-dark-mode)
Btw when I enable the autodocgen flag I don't see a tab anymore and instead see a menu item - is this intentional?
Hello,
I wanted to add my (my team's) voice to the chorus of people who have found this feature extremely useful. Having an additional line of documents on the side nav makes it more cluttered and hence hard to discover content. It was much more convenient to have a doc tab for each component designed on storybook rather than the current layout.
For anyone who is looking, here is the post describing the docs changes in 7.0: https://storybook.js.org/blog/storybook-7-docs/
And there is an entire section in the MIGRATION docs describing the changes at a technical level: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#70-docs-changes
That was a really nice feature having the docs tab always available. I just realized that it was intentionally removed via this issue. The page still suggests that the doc tab is still available https://storybook.js.org/addons/@storybook/addon-docs
The Docs tab was very nice. Dear Storybook team, please consider the ability to enable it and disable this new "Docs" page, IMHO the tab is way handier. Thank you 🙌
The fact that clicking on a story in the navigation takes you to the canvas mode for that story instead of linking to the specific section within the docs page is a deal breaker for us. 😢 I agree with others that ideally it should be optional. Thanks!
For anyone who is looking, here is the post describing the docs changes in 7.0: https://storybook.js.org/blog/storybook-7-docs/
And there is an entire section in the MIGRATION docs describing the changes at a technical level: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#70-docs-changes
This isn't a bug, it's just a new architecture that'd been implemented.
As stated in the docs, here's a solution:
"And if you want autodocs applied to all stories, set it in ./storybook/main.js. More options here."
//.storybook/main.js
module.exports = {
docs: {
autodocs: true
}
};
While the autodocs: true workaround solves the missing docs, it has a side effect that clicking a component opens its docs instead of its storybook/canvas. Is there a way of moving the docs to the bottom of the list, so the canvas opens by default?
edit: I managed to move stories to the top by customizing preview.js/.ts:
export const parameters = {
options: {
storySort: (a, b) => (a.type == 'story' ? 0 : 1) - (b.type == 'story' ? 0 : 1),
},
}
For our project(mb for part of storybook community as well), removing Docs tab per story/component is a huuuuuge STEP BACK! We've rely heavily on clicking on a story/component tab to open it doc section for fast copy paste code there or to read something useful and specisific for that component(check image 1). Now it opens canvas, showing how good looking is our component only (nothing more - check image 2), which is absolutely useless in our case. In the same time we have a bunch of useless generated tabs with canvas that bloating new side navigation bar. Tutorials and examples in official documentation with 2-3 stories are ok, but reality is different. Our stories/components per document are quite a lot, pages too long (check image 3), and now with autodocs and common generated doc file we have to search there for some story/component to scroll there and then to copy paste the code, which is a clumsy, long way for such quick and easy to be done task. In this context Im curious why there is no flexible options to choose between new v7 approach with common Doc and older v6(IMHO better) approach to set doc per story with auto scroll to it section. It could be really good to implement that flexibility in your feature releases.
image: 1 v6 storybook
image: 2 v7 storybook
image: 3 In some cases stories are really a lot as here with inputs.
+1 on providing configuration options to show a docs/canvas tab like before.
@mightym can you please provide an option to run docs as in version 6 in a tab instead in the sidebar? it breaks the UI which have another 2 tabs (we have tab for canvas, API (custom notes tab), we need the docs to be in one as well according to the design guidelines... Why do breaking changes over UI and UX if there aren't wanted at all? what's the benefit of removing working solution?
You yourself use a separate component to explain things. That's what documentation is for. I can't imagine creating one component for UX comments and another for development explanations. Please give us Canvas and Docs back :)
I'm also missing the Docs tab after having migrated vom storybook v6 to v7. It was much cleaner in my eyes to have the focus on the stories.
What bothers me most regarding the new UI is that clicking a story now automatically opens the Docs instead of the 1st story. As a result I need an additional click for every story!
Using the custom sort approach from @bladeSk helps a lot as it makes sure the Docs aren't the first child anymore. Nevertheless I'd prefer having a Docs tab as it was in v6.
Found this thread. Nice to know I'm not missing something that needs fixed in our setup to get the docs / canvas tab.
I don't totally mind the individual canvas BUT I would like to get the code snippet and doc notes available for that specific story accessible from that view (otherwise user has to click back to the Docs and manually scroll to find the story.
I just added https://storybook.js.org/addons/@storybook/addon-storysource to get the code snippet.
Even if there was an add on tab that showed the documentation comments that would be great.
@adamdiestelkamp prioritizing other things but will fix that in 8.x or die trying! Source handling is in general is my pet peeve with Storybook today
The docs/canvas is much better than side navbar list as UI/UX ! Especially the scrolling when clicking a story Please bring it back
@adamdiestelkamp prioritizing other things but will fix that in 8.x or die trying! Source handling is in general is my pet peeve with Storybook today
Do we have any update on this or at least some plugin?
@Biggisb Yes, we are in early 8.x and it is still on my list for a coming minor. I've added it to our Roadmap https://github.com/orgs/storybookjs/projects/20/views/1
@Biggisb Yes, we are in early 8.x and it is still on my list for a coming minor. I've added it to our Roadmap https://github.com/orgs/storybookjs/projects/20/views/1
Good to hear thanks, i will keep in eye on that. You are doing great work, thanks for that too!