@component-controls/storybook-custom-docs

Table of contents

• Important
• In action
• Overview
• Getting Started
  • Install
  • Configure
  • Pages format
  • Examples
    • Simple page
    • Render story
• API

Important

Storybook 6 final release, there is a regression that forces the viewMOde to story, unless the tab page key starts with docs or story. This used to work fine for storybook5 and storybook6 betas.

So until this is fixed, please replace code like

const page = {
  key: 'mixed-page',
  title: 'Mixed blocks',
  render: ({ active }) => active ? <Page /> : null,
}

with (notice the key/route starting with docs)

const page = {
  key: 'docs-mixed',
  title: 'Mixed blocks',
  render: ({ active }) => active ? <Page /> : null,
}

In action

Example site

You can create entirely new documentation pages with your own blocks of information, or you can use storybook docs blocks, component-controls blocks and even mix it all.

Overview

The Storybook docs addon is a great start to display documentation in Storybook, but the early versions (currently 5.x and 6.x) have a few shortcomings.

@component-controls/storybook-custom-docs gives the possibility to add custom documentation (aka docs) pages to storybook by solving the following challenges:

• Circumvent the hard-coded docs render: docs pages need to reside in the preview part of Storybook in order to render stories since that's where the stories are, while the TAB addons are placed in the manager part of storybook.
• Circumvent the hard-coded DOM tags: docs pages need to reside inside the preview iframe in order to render stories in a custom docs page and prevent CSS styles leaking into the story functions, while TAB addons are rendered outside the iframe.

Getting Started

Install

yarn add @component-controls/storybook-custom-docs --dev

Configure

within .storybook/main.js:

module.exports = {
    addons: [
    {
      name: '@component-controls/storybook-custom-docs',
      options: {
        pages: [
          // files exporting the custom pages:
          require.resolve('./custom-page'),
          require.resolve('./custom-page-docs')
        ],
      },
    },
  ],
}

Pages format

The page definition files need to have a default export with the following fields

import React from 'react';
export default {
  // key used for navigation
  key: string,
  // title of the tab
  title: string,
  // react render function. 
  // active boolean - if the tab custom page is active
  // storyId as a string
  // Return an object that can be rendered from ReactDOM.render
  render: ({ active, storyId }) => Element,
}

Examples

Simple page

import React from 'react';

export default {
  key: 'custom',
  title: 'Custom Page',
  render: ({ active, storyId }) => active ? <div>{storyId}</div> : null,
}

Render story

import React from 'react';
import { DocsContainer, Story} from '@storybook/addon-docs/blocks';
import { useContext, } from '@component-controls/storybook-custom-docs';

const Page = () => {
  const context = useContext();
  return (
    <DocsContainer context={context}><Story id={storyId}/></DocsContainer>
  )
}
export default {
  key: 'docs-page',
  title: 'Docs Page',
  render: ({ active, storyId }) => {
    return active ? <Page storyId={storyId} /> : null;  
  } 
}

API