Storybook Docs First Page

Storybook has been a great tool for helping the development and testing of our components. Now with the addition of the DocsPage it will likely become our default platform for documentation and communication of our visual design libraries.

However, one problem we have found is that there is no way to declare which page the documentation should open on. You can sort the stories and the first will be displayed. You can also add a parameter to the story metadata and use that for sorting.

For .mdx documentation:

<Meta title="Components|Button" component={Button} parameters={{ order: 5 }} />

or for Component Story Format

export default {
  title: "Components|Button",
  component: Button,
  parameters: {
    order: 5
  }
};

Then sort the stories in your config.js:

import { addParameters } from "@storybook/react";

addParameters({
  options: {
    storySort: (a, b) =>
      a[1].kind === b[1].kind
        ? 0
        : a[1].parameters.order - b[1].parameters.order
  }
});

But after sorting your desired first page may not be the first in the ordering. To set a specific first page we create our own simple addon. As it’s small, you can put it straight into the addons.js file along with any other registered addons:

import { STORIES_CONFIGURED } from "@storybook/core-events";
import addonAPI from "@storybook/addons";

addonAPI.register("my-organisation/firstpage", storybookAPI => {
  storybookAPI.on(STORIES_CONFIGURED, (kind, story) => {
    if (storybookAPI.getUrlState().path === "/story/*") {
      storybookAPI.selectStory("Kind", "story");
    }
  });
});

This is only triggered on load when the stories are configured. Also by testing the url for /story/* we do not interrupt requests for a specific story or docs page.

Limitations

This description applies to v5.2 upwards, though I think similar things can be done using sortStoriesByKind for earlier versions. Also, if an incorrect story URL is entered then the first page by the ordering will be used. If this is a concern you can add into the addon:

import { STORIES_CONFIGURED, STORY_MISSING } from "@storybook/core-events";
import addonAPI from "@storybook/addons";

addonAPI.register("my-organisation/firstpage", storybookAPI => {
  storybookAPI.on(STORIES_CONFIGURED, (kind, story) => {
    if (storybookAPI.getUrlState().path === "/story/*") {
      storybookAPI.selectStory("Kind", "story");
    }
  });
  storybookAPI.on(STORY_MISSING, (kind, story) => {
    storybookAPI.selectStory("Kind", "story");
  });
});