Setup CSF + MDX stories with @storybook/addon-docs
Over the last few months, Storybook has introduced several new features to make it easier to write rich docs pages for stories:
- DocsPage provides zero-config default docs for components.
-
Component Story Format (CSF) is a new way to write stories that drops the
storiesOf()
function in favor of standard ES6 exports. - MDX is an extended Markdown syntax that makes it possible to customize components' docs pages by combining standard Markdown with dynamic blocks for including stories, props table and more right in the docs.
-
vue-docgen-loader
has been added in the mix, making it possible to document properties, slots and events right in the components.
Those new features are all bundled in a new Storybook official addon: @storybook/addon-docs
.
Up until now, our Storybook has had similar features that we implemented thanks to storybook-readme, a third party addon that lets us include Markdown files in our stories and that exposes some options that we've used to include our own props/events table, automatic links to BootstrapVue's documentation etc.
Sadly storybook-readme
has some limitations, a few examples:
- It can't include more than one story in a docs page.
- It doesn't provide props tables out-of-the-box, forcing us to maintain our own implementation for that.
- The project isn't very active currently: the latest commit was pushed back in May, and there doesn't seem to be support for Storybook 6 at the moment.
Pros
Dropping storybook-readme
in favor of @storybook/addon-docs
might have some major advantages for us:
- A more flexible way of documenting stories.
- Eventually, we could even write Pajamas' specs right in Storybook rather than have two separate projects: one for implementing the components (GitLab UI) and another for documenting the design specs (design.gitlab.com).
- A subsequent advantage to bringing design specs into Storybook is that we wouldn't have to create both stories and examples as stories could be included right in the specs.
- A better integration in Storybook's ecosystem, making it easier to upgrade.
Cons
It also has some disadvantages:
- We need to get used to a slightly different way of writing stories and docs: this should be easily mitigated as long as we keep our component generator up-to-date.
- Aiming at upgrading Storybook from v5 to v6, we would need to migrate all current stories to the new format so that we can eventually drop
storybook-readme
which is preventing us from upgrading. - We might lose some features and have to somehow reimplement them. A few examples of what we might lose:
- Usage examples: those are currently shown below stories and are also imported in
design.gitlab.com
. If we were to merge GitLab UI anddesign.gitlab.com
, we could probably drop those examples altogether and rely only on stories, but we'll need to somehow preserve them in the meantime. - Automatic links to BootstrapVue docs.
- There doesn't seem to be a way to indicate
v-model
props and events in props tables either.
- Usage examples: those are currently shown below stories and are also imported in
Initial implementation plan proposal
If we want to proceed with this, we'll need to ensure that the migration can be done iteratively by following a few steps:
- Setup
@storybook/addon-docs
in our current instance. #979 (closed) - Figure out a way to preserve essential features with the new setup (usage examples mostly).
- Document ways for migrating current stories to the new format.
- Optionally: update documentation guidelines.
- Update the component generator to default to boilerplate MDX-ready stories.
- Coordinate the migration effort via an epic.
-
GlAlert
migration PoC: #980 (closed)
-
- Drop
storybook-readme
and custom documentation components. - Upgrade to Storybook v6.
Outcome
After gathering feedback about this proposal, we seem to agree that migrating to @storybook/addon-docs
would be beneficial, but that a prerequisite will be to move components usage examples to design.gitlab.com
. This makes sense because examples are mostly used in Pajamas docs pages and have a tendency to be plain copies of existing stories, which produces a lot of noise in GitLab UI. Therefore, here is a revised implementation plan:
-
Allow for writing examples in design.gitlab.com
: gitlab-org/gitlab-services/design.gitlab.com!2120 (merged). -
Update GitLab UI's docs and component generator to prevent new examples from being added and to explain how they can be written in design.gitlab.com
. -
Copy existing examples from GitLab UI to design.gitlab.com
gitlab-org/gitlab-services/design.gitlab.com!2121 (merged). -
Iteratively remove examples from GitLab UI. Requirements: - The script to copy examples over to
design.gitlab.com
should be run before deleting examples, to make sure the latest copy exists indesign.gitlab.com
. - A single MR can cover multiple components at once as long it only removes examples.
- If a component has examples that should be migrated to stories (e.g. if those examples were being referred to in the docs), an MR should be created for that component specifically.
- The script to copy examples over to
-
Cleanup any remaining examples-related code from GitLab UI (can be done at a later time). -
Setup @storybook/addon-docs
. #979 (closed). -
Document ways for migrating current stories to the new format. -
Update the component generator to boilerplate MDX-ready stories. -
Migrate existing stories to @storybook/addon-docs
. Coordinate the migration effort via an epic.-
GlAlert
migration PoC: #980 (closed)
-
-
Drop storybook-readme
and custom documentation components. -
Upgrade to Storybook v6.