\n\n# Overview\n\nThe Storybook [docs addon](https://github.com/storybookjs/storybook/tree/next/addons/docs) is a great start to display documentation in Storybook, but the early versions (currently 5.x and 6.x) have a few shortcomings.\n\n`@component-controls/storybook-custom-docs` gives the possibility to add custom documentation (aka `docs`) pages to storybook by solving the following challenges:\n\n- Circumvent the hard-coded [docs render](https://github.com/storybookjs/storybook/blob/855815293b59412eea2b57f20eaa02982fcb5360/lib/core/src/client/preview/StoryRenderer.tsx#L168): 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. \n- Circumvent the hard-coded [DOM tags](https://github.com/storybookjs/storybook/blob/855815293b59412eea2b57f20eaa02982fcb5360/lib/core/src/server/templates/index.ejs#L31): 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`. \n\n# Getting Started\n\n## Install\n\n```sh\nyarn add @component-controls/storybook-custom-docs --dev\n```\n\n## Configure\n\nwithin `.storybook/main.js`:\n\n```js\nmodule.exports = {\n addons: [\n {\n name: '@component-controls/storybook-custom-docs',\n options: {\n pages: [\n // files exporting the custom pages:\n require.resolve('./custom-page'),\n require.resolve('./custom-page-docs')\n ],\n },\n },\n ],\n}\n```\n\n## Pages format\n\nThe page definition files need to have a default export with the following fields\n\n```js\nimport React from 'react';\nexport default {\n // key used for navigation\n key: string,\n // title of the tab\n title: string,\n // react render function. \n // active boolean - if the tab custom page is active\n // storyId as a string\n // Return an object that can be rendered from ReactDOM.render\n render: ({ active, storyId }) => Element,\n}\n```\n\n## Examples\n\n### Simple page\n\n```js\nimport React from 'react';\n\nexport default {\n key: 'custom',\n title: 'Custom Page',\n render: ({ active, storyId }) => active ?
![\"create](\"https://github.com/ccontrols/component-controls/raw/master/misc/storybook-custom-docs/images/custom-docs-pages.gif\")
\n