+ ))
+ .add('default', () => );
diff --git a/docs/src/new-components/basics/tooltip/WithTooltip.js b/docs/src/new-components/basics/tooltip/WithTooltip.js
new file mode 100644
index 000000000000..ddbef62ab426
--- /dev/null
+++ b/docs/src/new-components/basics/tooltip/WithTooltip.js
@@ -0,0 +1,95 @@
+/* eslint-disable react/prop-types */
+import React from 'react';
+import PropTypes from 'prop-types';
+import styled from 'styled-components';
+import TooltipTrigger from 'react-popper-tooltip';
+import { withState } from 'recompose';
+
+import Tooltip from './Tooltip';
+
+// A target that doesn't speak popper
+// prettier-ignore
+const TargetContainer = styled.div`
+ display: inline-block;
+ cursor: ${props => props.mode === 'hover' ? 'default' : 'pointer'};
+`;
+
+const TargetSvgContainer = styled.g`
+ cursor: ${props => (props.mode === 'hover' ? 'default' : 'pointer')};
+`;
+
+function WithTooltip({
+ svg,
+ trigger,
+ closeOnClick,
+ placement,
+ modifiers,
+ hasChrome,
+ tooltip,
+ children,
+ tooltipShown,
+ onVisibilityChange,
+ ...props
+}) {
+ const Container = svg ? TargetSvgContainer : TargetContainer;
+ return (
+ (
+
+ {typeof tooltip === 'function'
+ ? tooltip({ onHide: () => onVisibilityChange(false) })
+ : tooltip}
+
+ )}
+ >
+ {({ getTriggerProps, triggerRef }) => (
+
+ {children}
+
+ )}
+
+ );
+}
+
+WithTooltip.propTypes = {
+ svg: PropTypes.bool,
+ trigger: PropTypes.string,
+ closeOnClick: PropTypes.bool,
+ placement: PropTypes.string,
+ modifiers: PropTypes.shape({}),
+ hasChrome: PropTypes.bool,
+ tooltip: PropTypes.oneOfType([PropTypes.node, PropTypes.func]).isRequired,
+ children: PropTypes.node.isRequired,
+ onVisibilityChange: PropTypes.func.isRequired,
+};
+
+WithTooltip.defaultProps = {
+ svg: false,
+ trigger: 'hover',
+ closeOnClick: false,
+ placement: 'top',
+ modifiers: {},
+ hasChrome: true,
+};
+
+export default withState('tooltipShown', 'onVisibilityChange', ({ startOpen }) => startOpen)(
+ WithTooltip
+);
diff --git a/docs/src/new-components/basics/tooltip/WithTooltip.stories.js b/docs/src/new-components/basics/tooltip/WithTooltip.stories.js
new file mode 100644
index 000000000000..8f5fa1089ddf
--- /dev/null
+++ b/docs/src/new-components/basics/tooltip/WithTooltip.stories.js
@@ -0,0 +1,86 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { storiesOf } from '@storybook/react';
+import styled from 'styled-components';
+
+import TooltipMessage from './TooltipMessage';
+import WithTooltip from './WithTooltip';
+
+const ViewPort = styled.div`
+ height: 300px;
+`;
+
+const BackgroundBox = styled.div`
+ width: 500px;
+ height: 500px;
+ overflow-y: scroll;
+ background: #eee;
+ position: relative;
+`;
+
+const Spacer = styled.div`
+ height: 100px;
+`;
+
+const Trigger = styled.div`
+ width: 200px;
+ height: 100px;
+ background-color: red;
+ color: white;
+`;
+
+const Tooltip = ({ onHide }) => (
+
+);
+
+Tooltip.propTypes = {
+ onHide: PropTypes.func,
+};
+
+Tooltip.defaultProps = {
+ onHide: null,
+};
+
+storiesOf('basics/tooltip/WithTooltip', module)
+ .addDecorator(storyFn => (
+
+
+
+ {storyFn()}
+
+
+ ))
+ .add('simple hover', () => (
+ }>
+ Hover me!
+
+ ))
+ .add('simple hover, functional', () => (
+
+ Hover me!
+
+ ))
+ .add('simple click', () => (
+ }>
+ Click me!
+
+ ))
+ .add('simple click start open', () => (
+ }>
+ Click me!
+
+ ))
+ .add('simple click closeOnClick', () => (
+ }>
+ Click me!
+
+ ))
+ .add('no chrome', () => (
+ }>
+ Click me!
+
+ ));
diff --git a/docs/src/new-components/layout/Header.js b/docs/src/new-components/layout/Header.js
new file mode 100644
index 000000000000..d38338174982
--- /dev/null
+++ b/docs/src/new-components/layout/Header.js
@@ -0,0 +1,176 @@
+import React from 'react';
+import styled, { css } from 'styled-components';
+
+import { GlobalStyle } from '../basics/shared/global';
+import { Link, Icon, TooltipLinkList, WithTooltip, styles, site } from '../basics';
+import { navLinks } from './PageLayout';
+
+const { color, typography, spacing, breakpoint } = styles;
+const { metadata, url } = site;
+
+const LogotypeWrapper = styled.a`
+ display: inline-block;
+ img {
+ height: 22px;
+ width: auto;
+ margin-top: 14px;
+ @media (min-width: ${breakpoint}px) {
+ height: 26px;
+ margin-top: 10px;
+ }
+
+ display: block;
+ }
+`;
+
+const Version = styled(Link)`
+ display: inline-block;
+ vertical-align: top;
+ margin-left: 10px;
+ position: relative;
+ top: 2px;
+ font-size: ${typography.size.s1}px;
+ color: ${color.mediumdark};
+`;
+
+const TooltipLinkListWrapper = styled.div`
+ padding: 8px 5px;
+ color: ${color.darkest};
+`;
+
+const NavLink = styled(Link)`
+ font-size: ${typography.size.s2}px;
+ font-weight: ${typography.weight.bold};
+`;
+
+const Menu = styled(Link)`
+ width: 3rem;
+ height: 3rem;
+ border: none !important;
+ text-decoration: none !important;
+ background: none !important;
+ text-align: right;
+ display: flex;
+ align-items: center;
+ justify-content: flex-end;
+
+ svg {
+ vertical-align: top;
+ height: 1rem;
+ width: 1rem;
+ margin: 0;
+ }
+`;
+
+const MobileMenu = styled.div`
+ font-size: ${typography.size.s1}px;
+
+ ${TooltipLinkListWrapper} {
+ padding: 5px 0;
+ }
+`;
+
+const NavItem = styled.div`
+ display: inline-block;
+ line-height: 3rem;
+ height: 3rem;
+ vertical-align: top;
+
+ ${props =>
+ props.showDesktop &&
+ css`
+ display: none;
+ @media (min-width: ${breakpoint * 1.333}px) {
+ display: inline-block;
+ }
+ `};
+
+ ${props =>
+ props.showMobile &&
+ css`
+ @media (min-width: ${breakpoint * 1.333}px) {
+ display: none;
+ }
+ `};
+`;
+
+const NavGroup = styled.div`
+ position: absolute;
+ top: 0;
+ left: 0;
+ z-index: 1;
+
+ ${props =>
+ props.right &&
+ css`
+ left: auto;
+ right: 0;
+ `}
+
+ ${NavItem} + ${NavItem} {
+ margin-left: ${spacing.padding.large}px;
+ }
+`;
+
+const Nav = styled.div`
+ height: 3rem;
+ position: relative;
+ text-align: center;
+ z-index: 3;
+ display: flex;
+`;
+
+const NavWrapper = styled.nav`
+ padding-top: 12px;
+ @media (min-width: ${breakpoint}px) {
+ padding-top: 36px;
+ }
+`;
+
+export default function Header({ ...props }) {
+ const mobileMenu = (
+
+
+
+ );
+
+ return (
+
+
+
+
+
+ );
+}
diff --git a/docs/src/new-components/layout/PageLayout.js b/docs/src/new-components/layout/PageLayout.js
new file mode 100644
index 000000000000..d831a7c647be
--- /dev/null
+++ b/docs/src/new-components/layout/PageLayout.js
@@ -0,0 +1,12 @@
+import { site } from '../basics';
+
+const { url } = site;
+
+export const navLinks = [
+ { title: 'Docs', href: url.docs.home, isGatsby: false },
+ { title: 'Addons', href: url.addons, isGatsby: false },
+ { title: 'Community', href: url.community, isGatsby: false },
+ { title: 'Use cases', href: url.useCases, isGatsby: false },
+ { title: 'Support', href: url.support, isGatsby: false },
+ { title: 'Team', href: url.team, isGatsby: false },
+];
diff --git a/docs/src/new-components/lib/StoryLinkWrapper.js b/docs/src/new-components/lib/StoryLinkWrapper.js
new file mode 100644
index 000000000000..a43a69e9e9c1
--- /dev/null
+++ b/docs/src/new-components/lib/StoryLinkWrapper.js
@@ -0,0 +1,28 @@
+// This is allows us to test whether the link works via the actions addon
+import React, { Children } from 'react';
+import PropTypes from 'prop-types';
+import { action } from '@storybook/addon-actions';
+
+const onLinkClick = action('onLinkClick');
+
+export default function StoryLinkWrapper({ href, passHref, children }) {
+ const child = Children.only(children);
+
+ return React.cloneElement(child, {
+ href: passHref && href,
+ onClick: e => {
+ e.preventDefault();
+ onLinkClick(href);
+ },
+ });
+}
+
+StoryLinkWrapper.propTypes = {
+ href: PropTypes.string.isRequired,
+ passHref: PropTypes.bool,
+ children: PropTypes.node.isRequired,
+};
+
+StoryLinkWrapper.defaultProps = {
+ passHref: false,
+};
diff --git a/docs/src/pages/basics/guide-angular/index.md b/docs/src/pages/basics/guide-angular/index.md
deleted file mode 100644
index 82b2ef310127..000000000000
--- a/docs/src/pages/basics/guide-angular/index.md
+++ /dev/null
@@ -1,210 +0,0 @@
----
-id: 'guide-angular'
-title: 'Storybook for Angular'
----
-
-You may have tried to use our quick start guide to setup your project for Storybook. If you want to set up Storybook manually, this is the guide for you.
-
-> This will also help you understand how Storybook works.
-
-## Starter Guide Angular
-
-Storybook has its own webpack setup and a dev server.
-The webpack setup is very similar to [Angular CLI](https://cli.angular.io), but allows you to [configure it however you want](/configurations/custom-webpack-config/).
-
-In this guide, we are trying to set up Storybook for your Angular project.
-
-## Table of contents
-
-- [Create Angular project](#create-angular-project)
-- [Add @storybook/angular and babel-core](#add-storybookangular-and-babel-core)
-- [Create the config file](#create-the-config-file)
-- [Write your stories](#write-your-stories)
-- [Run your Storybook](#run-your-storybook)
-
-## Create Angular project
-
-First of all, you need to prepare an Angular project. To do that, run:
-
-```sh
-npm i -g @angular/cli
-ng new your-angular-prj
-cd your-angular-prj
-```
-
-## Add @storybook/angular, @babel/core, and babel-loader
-
-Next, install `@storybook/angular`, `@babel/core`, and `babel-loader` (it's a peerDependency) to your project:
-
-```sh
-npm i --save-dev @storybook/angular @babel/core babel-loader
-```
-
-Then add the following NPM script to your package json in order to start the storybook later in this guide:
-
-```json
-{
- "scripts": {
- "storybook": "start-storybook -p 9001 -c .storybook"
- }
-}
-```
-
-## Create the config file
-
-Storybook can be configured in several different ways.
-That’s why we need a config directory. We've added a `-c` option to the above NPM script mentioning `.storybook` as the config directory.
-
-For the basic Storybook configuration file, you don't need to do much, but simply tell Storybook where to find stories.
-
-To do that, simply create a file at `.storybook/config.js` with the following content:
-
-```js
-import { configure } from '@storybook/angular';
-
-function loadStories() {
- require('../src/stories/index.ts');
-}
-
-configure(loadStories, module);
-```
-
-That'll load stories in `../src/stories/index.ts`.
-
-Just like that, you can load stories from wherever you want to.
-
-## Storybook TypeScript configuration
-
-**Note:** You only need this if you are using Storybook `>= 4.0.0-alpha.23`.
-
-`@storybook/angular` is using [ForkTsCheckerWebpackPlugin](https://github.com/Realytics/fork-ts-checker-webpack-plugin) to boost the build performance.
-This makes it necessary to create a `tsconfig.json` file at `.storybook/tsconfig.json` with the following content:
-
-```json
-{
- "extends": "../tsconfig.json",
- "exclude": [
- "../src/test.ts",
- "../src/**/*.spec.ts",
- "../projects/**/*.spec.ts"
- ],
- "include": [
- "../src/**/*",
- "../projects/**/*"
- ]
-}
-```
-
-> Only files that are included in the `include` or `files` section are checked for semantic TypeScript errors.
-> For more information visit the [ForkTsCheckerWebpackPlugin documentation](https://github.com/Realytics/fork-ts-checker-webpack-plugin#modules-resolution).
-
-## Write your stories
-
-Now you can write some stories inside the `../src/stories/index.ts` file, like this:
-
-```js
-import { storiesOf } from '@storybook/angular';
-import { action } from '@storybook/addon-actions';
-import { MyButtonComponent } from '../app/my-button/my-button.component';
-
-storiesOf('My Button', module)
- .add('with some emoji', () => ({
- component: MyButtonComponent,
- props: {
- text: '😀 😎 👍 💯',
- },
- }))
- .add('with some emoji and action', () => ({
- component: MyButtonComponent,
- props: {
- text: '😀 😎 👍 💯',
- click: action('clicked'),
- },
- }));
-```
-
-Each story is a single state of your component. In the above case, there are two stories for the MyButton component:
-
-1. story with `@Input()` property binding.
-2. story with `@Input()` and `@Output()` property binding.
-
-## Run your Storybook
-
-Now everything is ready. Simply run your storybook with:
-
-```sh
-npm run storybook
-```
-
-Now you can change components and write stories whenever you need to.
-You'll get those changes into Storybook in a snap with the help of webpack's HMR API.
-
-## Module Metadata
-
-If your component has dependencies on other Angular directives and modules, these can be supplied using the `moduleMetadata` property on an individual story:
-
-```js
-import { CommonModule } from '@angular/common';
-import { storiesOf } from '@storybook/angular';
-import { MyButtonComponent } from '../app/my-button/my-button.component';
-import { MyPanelComponent } from '../app/my-panel/my-panel.component';
-import { MyDataService } from '../app/my-data/my-data.service';
-
-storiesOf('My Panel', module)
- .add('Default', () => ({
- component: MyPanelComponent,
- moduleMetadata: {
- imports: [CommonModule],
- schemas: [],
- declarations: [MyButtonComponent],
- providers: [MyDataService],
- }
- }));
-```
-
-If you have metadata that is common between your stories, this can configured once using the `moduleMetadata()` decorator:
-
-```js
-import { CommonModule } from '@angular/common';
-import { storiesOf, moduleMetadata } from '@storybook/angular';
-import { MyButtonComponent } from '../app/my-button/my-button.component';
-import { MyPanelComponent } from '../app/my-panel/my-panel.component';
-import { MyDataService } from '../app/my-data/my-data.service';
-
-storiesOf('My Panel', module)
- .addDecorator(
- moduleMetadata({
- imports: [CommonModule],
- schemas: [],
- declarations: [MyButtonComponent],
- providers: [MyDataService],
- })
- )
- .add('Default', () => ({
- component: MyPanelComponent
- }))
- .add('with a title', () => ({
- component: MyPanelComponent,
- props: {
- title: 'Foo',
- }
- }));
-```
-## Trouble Shooting
-
-If you have problems running @angular/cli using "ng serve" after install specifically the following error:
-
-```ERROR in node_modules/@storybook/angular/index.d.ts(31,44): error TS2304: Cannot find name 'NodeRequire'.```
-
-You may need to exclude your stories from being compiled when running your angular dev environment. To do this add "stories", "\*\*/\*.stories.ts" to the exclude section in src/app/tsconfig.app.json:
-
-```json
-{
- "exclude": [
- "stories",
- "**/*.stories.ts"
- ]
-}
-```
-
-If you're using scss for styling, you need to have `node-sass` dependency installed on your side (directly or via `@angular/cli`).
diff --git a/docs/src/pages/basics/guide-html/index.md b/docs/src/pages/basics/guide-html/index.md
deleted file mode 100644
index a954ac03dc9e..000000000000
--- a/docs/src/pages/basics/guide-html/index.md
+++ /dev/null
@@ -1,111 +0,0 @@
----
-id: 'guide-html'
-title: 'Storybook for HTML'
----
-
-You may have tried to use our quick start guide to setup your project for Storybook. If you want to set up Storybook manually, this is the guide for you.
-
-> This will also help you to understand how Storybook works.
-
-## Starter Guide HTML
-
-Storybook has its own Webpack setup and a dev server.
-
-In this guide, we will set up Storybook for your HTML project.
-
-## Table of contents
-
-- [Add @storybook/html](#add-storybookhtml)
-- [Add babel-runtime and babel-core](#add-babel-runtime-and-babel-core)
-- [Create the config file](#create-the-config-file)
-- [Write your stories](#write-your-stories)
-- [Run your Storybook](#run-your-storybook)
-
-## Add @storybook/html
-
-First of all, you need to add `@storybook/html` to your project. To do that, simply run:
-
-```sh
-npm i --save-dev @storybook/html
-```
-
-If you don't have `package.json` in your project, you'll need to init it first:
-
-```sh
-npm init
-```
-
-## Add @babel/core, and babel-loader
-
-Make sure that you have `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peerDependency:
-
-```sh
-npm i --save-dev @babel/core
-npm i --save-dev babel-loader
-```
-
-Then add the following NPM script to your package json in order to start the storybook later in this guide:
-
-```json
-{
- "scripts": {
- "storybook": "start-storybook -p 9001 -c .storybook"
- }
-}
-```
-
-## Create the config file
-
-Storybook can be configured in several different ways.
-That’s why we need a config directory. We've added a `-c` option to the above NPM script mentioning `.storybook` as the config directory.
-
-For the basic Storybook configuration file, you don't need to do much, but simply tell Storybook where to find stories.
-
-To do that, simply create a file at `.storybook/config.js` with the following content:
-
-```js
-import { configure } from '@storybook/html';
-
-function loadStories() {
- require('../stories/index.js');
- // You can require as many stories as you need.
-}
-
-configure(loadStories, module);
-```
-
-That'll load stories in `../stories/index.js`.
-
-## Write your stories
-
-Now you can write some stories inside the `../stories/index.js` file, like this:
-
-```js
-/* global document */
-import { storiesOf } from '@storybook/html';
-
-storiesOf('Demo', module)
- .add('heading', () => '
Hello World
')
- .add('button', () => {
- const button = document.createElement('button');
- button.innerText = 'Hello Button';
- button.addEventListener('click', e => console.log(e));
- return button;
- });
-
-```
-
-Story is a single HTML snippet or DOM node. In the above case, there are two stories:
-
-1. heading — an HTML snippet
-2. button — a DOM node with event listener
-
-## Run your Storybook
-
-Now everything is ready. Simply run your storybook with:
-
-```sh
-npm run storybook
-```
-
-Now you can change components and write stories whenever you need to.
diff --git a/docs/src/pages/basics/guide-marko/index.md b/docs/src/pages/basics/guide-marko/index.md
deleted file mode 100644
index 6daf34191857..000000000000
--- a/docs/src/pages/basics/guide-marko/index.md
+++ /dev/null
@@ -1,96 +0,0 @@
----
-id: 'guide-marko'
-title: 'Storybook for Marko'
----
-
-You may have tried to use our quick start guide to setup your project for Storybook. If you want to set up Storybook manually, this is the guide for you.
-
-> This will also help you to understand how Storybook works.
-
-## Starter Guide Marko
-
-Storybook has its own Webpack setup and a dev server.
-
-In this guide, we will set up Storybook for your Marko project.
-
-## Table of contents
-
-- [Add @storybook/marko](#add-storybookmarko)
-- [Add babel-runtime and babel-core](#add-babel-runtime-and-babel-core)
-- [Create the config file](#create-the-config-file)
-- [Write your stories](#write-your-stories)
-- [Run your Storybook](#run-your-storybook)
-
-## Add @storybook/marko
-
-First of all, you need to add `@storybook/marko` to your project. To do that, simply run:
-
-```sh
-npm i --save-dev @storybook/marko
-```
-
-## Add babel-runtime and babel-core
-
-Make sure that you have `babel-runtime` and `babel-core` in your dependencies as well because we list these as a peerDependency:
-
-```sh
-npm i --save babel-runtime
-npm i --save-dev babel-core
-```
-
-Then add the following NPM script to your package json in order to start the storybook later in this guide:
-
-```json
-{
- "scripts": {
- "storybook": "start-storybook -p 9001 -c .storybook"
- }
-}
-```
-
-## Create the config file
-
-Storybook can be configured in several different ways.
-That’s why we need a config directory. We've added a `-c` option to the above NPM script mentioning `.storybook` as the config directory.
-
-For the basic Storybook configuration file, you don't need to do much, but simply tell Storybook where to find stories.
-
-To do that, simply create a file at `.storybook/config.js` with the following content:
-
-```js
-import { configure } from '@storybook/marko';
-
-function loadStories() {
- require('../stories/index.js');
- // You can require as many stories as you need.
-}
-
-configure(loadStories, module);
-```
-
-That'll load stories in `../stories/index.js`.
-
-## Write your stories
-
-Now you can write some stories inside the `../stories/index.js` file, like this:
-
-```js
-import { storiesOf } from '@storybook/marko';
-import { action } from '@storybook/addon-actions';
-import Button from '../components/button/index.marko';
-
-storiesOf('Button', module)
- .add('with action', () => Button.renderSync({ click: action('action logged!') }));
-```
-
-Story is a single state of your component.
-
-## Run your Storybook
-
-Now everything is ready. Simply run your storybook with:
-
-```sh
-npm run storybook
-```
-
-Now you can change components and write stories whenever you need to.
diff --git a/docs/src/pages/basics/guide-mithril/index.md b/docs/src/pages/basics/guide-mithril/index.md
deleted file mode 100644
index 60fa58b01536..000000000000
--- a/docs/src/pages/basics/guide-mithril/index.md
+++ /dev/null
@@ -1,108 +0,0 @@
----
-id: 'guide-mithril'
-title: 'Storybook for Mithril'
----
-
-You may have tried to use our quick start guide to setup your project for Storybook. If you want to set up Storybook manually, this is the guide for you.
-
-> This will also help you to understand how Storybook works.
-
-## Starter Guide Mithril
-
-Storybook has its own Webpack setup and a dev server.
-
-In this guide, we will set up Storybook for your Mithril project.
-
-## Table of contents
-
-- [Add @storybook/mithril](#add-storybookmithril)
-- [Add mithril and babel-core](#add-mithril-and-babel-core)
-- [Create the config file](#create-the-config-file)
-- [Write your stories](#write-your-stories)
-- [Run your Storybook](#run-your-storybook)
-
-## Add @storybook/mithril
-
-First of all, you need to add `@storybook/mithril` to your project. To do that, simply run:
-
-```sh
-npm i --save-dev @storybook/mithril
-```
-
-## Add mithril and babel-core
-
-Make sure that you have `mithril`, `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peerDependency:
-
-```sh
-npm i --save mithril
-npm i --save-dev @babel/core babel-loader
-```
-
-Then add the following NPM script to your package json in order to start the storybook later in this guide:
-
-```json
-{
- "scripts": {
- "storybook": "start-storybook -p 9001 -c .storybook"
- }
-}
-```
-
-## Create the config file
-
-Storybook can be configured in several different ways.
-That’s why we need a config directory. We've added a `-c` option to the above NPM script mentioning `.storybook` as the config directory.
-
-For the basic Storybook configuration file, you don't need to do much, but simply tell Storybook where to find stories.
-
-To do that, simply create a file at `.storybook/config.js` with the following content:
-
-```js
-import { configure } from '@storybook/mithril';
-
-function loadStories() {
- require('../stories/index.js');
- // You can require as many stories as you need.
-}
-
-configure(loadStories, module);
-```
-
-That'll load stories in `../stories/index.js`.
-
-## Write your stories
-
-Now you can write some stories inside the `../stories/index.js` file, like this:
-
-```js
-/** @jsx m */
-
-import m from 'mithril';
-
-import { storiesOf } from '@storybook/mithril';
-import { action } from '@storybook/addon-actions';
-import Button from '../components/Button';
-
-storiesOf('Button', module)
- .add('with text', () => ({
- view: () =>
- }))
- .add('with some emoji', () => ({
- view: () =>
- }));
-```
-
-Story is a single state of your component. In the above case, there are two stories for the native button component:
-
-1. with text
-2. with some emoji
-
-## Run your Storybook
-
-Now everything is ready. Simply run your storybook with:
-
-```sh
-npm run storybook
-```
-
-Now you can change components and write stories whenever you need to.
diff --git a/docs/src/pages/basics/guide-preact/index.md b/docs/src/pages/basics/guide-preact/index.md
deleted file mode 100644
index c110a46afbc8..000000000000
--- a/docs/src/pages/basics/guide-preact/index.md
+++ /dev/null
@@ -1,114 +0,0 @@
----
-id: 'guide-preact'
-title: 'Storybook for Preact'
----
-
-You may have tried to use our quick start guide to setup your project for Storybook. If you want to set up Storybook manually, this is the guide for you.
-
-This will also help you to understand how Storybook works.
-
-## Starter Guide Preact
-
-Storybook has its own Webpack setup and a dev server.
-
-In this guide, we will set up Storybook for your Preact project.
-
-## Table of contents
-
-- [Add @storybook/preact](#add-storybookpreact)
-- [Add preact, @babel/core, and babel-loader](#add-preact-babel-core-and-babel-loader)
-- [Create the config file](#create-the-config-file)
-- [Write your stories](#write-your-stories)
-- [Run your Storybook](#run-your-storybook)
-
-## Add @storybook/react
-
-First of all, you need to add `@storybook/preact` to your project. To do that, run:
-
-```sh
-npm i --save-dev @storybook/preact
-```
-
-## Add preact, @babel/core, and babel-loader
-
-Make sure that you have `preact`, `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peer dependencies:
-
-```sh
-npm i --save preact
-npm i --save-dev @babel/core
-npm i --save-dev babel-loader
-```
-
-Then add the following NPM script to your `package.json` in order to start the storybook later in this guide:
-
-```json
-{
- "scripts": {
- "storybook": "start-storybook -p 9001 -c .storybook"
- }
-}
-```
-
-## Create the config file
-
-Storybook can be configured in several different ways.
-That’s why we need a config directory. We've added a `-c` option to the above NPM script mentioning `.storybook` as the config directory.
-
-For a basic Storybook configuration, the only thing you need to do is tell Storybook where to find stories.
-
-To do that, create a file at `.storybook/config.js` with the following content:
-
-```js
-import { configure } from '@storybook/preact';
-
-function loadStories() {
- require('../stories/index.js');
- // You can require as many stories as you need.
-}
-
-configure(loadStories, module);
-```
-
-That'll load stories in `../stories/index.js`.
-
-Just like that, you can load stories from wherever you want to.
-
-## Write your stories
-
-Now you can write some stories inside the `../stories/index.js` file, like this:
-
-```js
-import { h } from 'preact';
-import { storiesOf } from '@storybook/preact';
-
-const Button = ({ children, ...props }) => ;
-
-storiesOf('Button', module)
- .add('with text', () => )
- .add('with some emoji', () => (
-
- ));
-```
-
-Each story is a single state of your component. In the above case, there are two stories for the demo button component:
-
-1. With text
-2. With some emoji
-
-## Run your Storybook
-
-Now everything is ready. Run your storybook with:
-
-```sh
-npm run storybook
-```
-
-Then you can see all your stories, like this:
-
-
-
-Now you can change components and write stories whenever you need to. You'll see the changes in Storybook immediately since it uses Webpack's hot module reloading.
diff --git a/docs/src/pages/basics/guide-react/index.md b/docs/src/pages/basics/guide-react/index.md
deleted file mode 100644
index ed33c1c2e415..000000000000
--- a/docs/src/pages/basics/guide-react/index.md
+++ /dev/null
@@ -1,111 +0,0 @@
----
-id: 'guide-react'
-title: 'Storybook for React'
----
-
-You may have tried to use our quick start guide to setup your project for Storybook. If you want to set up Storybook manually, this is the guide for you.
-
-This will also help you to understand how Storybook works.
-
-## Starter Guide React
-
-Storybook has its own Webpack setup and a dev server. Webpack setup is very similar to [Create React App](https://github.com/facebookincubator/create-react-app), but allows you to configure it as you want.
-
-In this guide, we will set up Storybook for your React project.
-
-## Table of contents
-
-- [Add @storybook/react](#add-storybookreact)
-- [Add react, react-dom, @babel/core, and babel-loader](#add-react-react-dom-babel-core-and-babel-loader)
-- [Create the config file](#create-the-config-file)
-- [Write your stories](#write-your-stories)
-- [Run your Storybook](#run-your-storybook)
-
-## Add @storybook/react
-
-First of all, you need to add `@storybook/react` to your project. To do that, run:
-
-```sh
-npm i --save-dev @storybook/react
-```
-
-## Add react, react-dom, @babel/core, and babel-loader
-
-Make sure that you have `react`, `react-dom`, `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peer dependencies:
-
-```sh
-npm i --save react react-dom
-npm i --save-dev @babel/core
-npm i --save-dev babel-loader
-```
-
-Then add the following NPM script to your `package.json` in order to start the storybook later in this guide:
-
-```json
-{
- "scripts": {
- "storybook": "start-storybook -p 9001 -c .storybook"
- }
-}
-```
-
-## Create the config file
-
-Storybook can be configured in several different ways.
-That’s why we need a config directory. We've added a `-c` option to the above NPM script mentioning `.storybook` as the config directory.
-
-For a basic Storybook configuration, the only thing you need to do is tell Storybook where to find stories.
-
-To do that, create a file at `.storybook/config.js` with the following content:
-
-```js
-import { configure } from '@storybook/react';
-
-function loadStories() {
- require('../stories/index.js');
- // You can require as many stories as you need.
-}
-
-configure(loadStories, module);
-```
-
-That'll load stories in `../stories/index.js`.
-
-Just like that, you can load stories from wherever you want to.
-
-## Write your stories
-
-Now you can write some stories inside the `../stories/index.js` file, like this:
-
-```js
-import React from 'react';
-import { storiesOf } from '@storybook/react';
-import { Button } from '@storybook/react/demo';
-
-storiesOf('Button', module)
- .add('with text', () => (
-
- ))
- .add('with some emoji', () => (
-
- ));
-```
-
-Each story is a single state of your component. In the above case, there are two stories for the demo button component:
-
-1. With text
-2. With some emoji
-
-## Run your Storybook
-
-Now everything is ready. Run your storybook with:
-
-```sh
-npm run storybook
-```
-
-Then you can see all your stories, like this:
-
-
-
-Now you can change components and write stories whenever you need to. You'll see the changes in Storybook immediately since it uses Webpack's hot module reloading.
diff --git a/docs/src/pages/basics/guide-riot/index.md b/docs/src/pages/basics/guide-riot/index.md
deleted file mode 100644
index b96902024251..000000000000
--- a/docs/src/pages/basics/guide-riot/index.md
+++ /dev/null
@@ -1,145 +0,0 @@
----
-id: 'guide-riot'
-title: 'Storybook for Riot'
----
-
-You may have tried to use our quick start guide to setup your project for Storybook. If you want to set up Storybook manually, this is the guide for you.
-
-> This will also help you understand how Storybook works.
-
-## Starter Guide Riot
-
-Storybook has its own Webpack setup and a dev server.
-The Webpack setup is very similar to [tag-loader](https://github.com/riot/tag-loader), but allows you to [configure it however you want](/configurations/custom-webpack-config/).
-
-In this guide, we are trying to set up Storybook for your Riot project.
-
-## Table of contents
-
-- [Add @storybook/riot](#add-storybookriot)
-- [Add riot and babel-loader](#add-riot-and-babel-loader)
-- [Create the NPM script](#create-the-npm-script)
-- [Create the config file](#create-the-config-file)
-- [Write your stories](#write-your-stories)
-- [Run your Storybook](#run-your-storybook)
-
-## Add @storybook/riot
-
-First of all, you need to add `@storybook/riot` to your project. To do that, simply run:
-
-```sh
-npm i --save-dev @storybook/riot
-```
-
-## Add riot and babel-loader
-
-Make sure that you have `riot`, the `riot-compiler`, the `riot-tag-loader` and `babel-loader` in your dependencies as well because we list it as a peerDependency:
-
-```sh
-npm i --save riot
-npm i --save-dev babel-core riot-compiler riot-tag-loader
-```
-
-## Create the NPM script
-
-Add the following NPM script to your `package.json` in order to start the storybook later in this guide:
-
- {
- "scripts": {
- "storybook": "start-storybook -p 9001 -c .storybook"
- }
- }
-
-## Create the config file
-
-Storybook can be configured in several different ways.
-That’s why we need a config directory. We've added a `-c` option to the above NPM script mentioning `.storybook` as the config directory.
-
-There are 2 things you need to tell Storybook to do:
-
-1. Import and globally register with [`riot.mount()`](https://riot.js.org/api/#mounting) any global custom components just like you did with your project.
-2. Require your stories.
-
-Here's an example `.storybook/config.js` to get you started:
-
-```js
-import { configure } from '@storybook/riot';
-
-// Import your globally available components.
-import '../src/stories/Button.tag';
-
-function loadStories() {
- // You can require as many stories as you need.
- require('../src/stories');
-}
-
-configure(loadStories, module);
-```
-
-This example registered your custom `Button.tag` component, and loaded your Storybook stories defined in `../stories/index.js`.
-
-All custom components can be registered before or after calling `configure()`.
-
-> This stories folder is just an example, you can load stories from wherever you want to.
-> We think stories are best located close to the source files.
-
-## Write your stories
-
-There are several ways to implement a story using either a text import or a component import
-
-```js
-import { tag, mount, storiesOf } from '@storybook/riot';
-import SimpleTestRaw from './SimpleTest.txt'; //can be loaded as string if you prefer
-import './AnotherTest.tag';
-//if you need to import .tag files as text, just use the raw-loader instead of the riot-tag-loader
-
-storiesOf('Story|How to create a story', module)
- .add(
- 'built with tag', // the template is compiled below
- () =>
- tag('test', '
simple test ({ opts.value })
', '', '', () => {}) &&
- mount('test', { value: 'with a parameter' }))
-
- // tags[0] will be the parent tag, always
- // you can leave out the root tag, if we find out that the new root tag
- // is a built-in html tag, it will be wrapped
- .add('built as string', () => ({ tags: ['
simple test
'] })
-
- // the component is a string, it will be instantiated without params
- // e.g.
- .add('built from raw import', () => SimpleTestRaw)
-
- // the comprehensive form is this one
- // list all the possible tags (the root element is in the content)
- // then scenario is compiled and executed
- .add(
- 'built from tags and scenario',
- () => ({
- tags: [{ content: SimpleTestRaw, boundAs: 'mustBeUniquePlease' }],
- scenario:
- '',
- }),
- {
- notes:
- 'WARN : the tag file root element must have exactly the same name (or else you will see nothing)',
- }
- )
-
- // the tag is already compiled before running the js
- // the tag name 'anothertest' must match exactly the root tag inside the tag file
- // mind the lower case
- .add('built from the precompilation', () => mount('anothertest', {}), {
- notes: 'WARN, only works in lower case, never upper case with precompiled templates',
- });
-```
-
-## Run your Storybook
-
-Now everything is ready. Simply run your storybook with:
-
-```sh
-npm run storybook
-```
-
-Now you can change components and write stories whenever you need to.
-You'll get those changes into Storybook in a snap with the help of Webpack's HMR API.
diff --git a/docs/src/pages/basics/guide-svelte/index.md b/docs/src/pages/basics/guide-svelte/index.md
deleted file mode 100644
index 084d34a90f0c..000000000000
--- a/docs/src/pages/basics/guide-svelte/index.md
+++ /dev/null
@@ -1,158 +0,0 @@
----
-id: 'guide-svelte'
-title: 'Storybook for Svelte'
----
-
-You may have tried to use our quick start guide to setup your project for Storybook. If you want to set up Storybook manually, this is the guide for you.
-
-> This will also help you understand how Storybook works.
-
-## Starter Guide Svelte
-
-Storybook has its own Webpack setup and a dev server.
-
-The Webpack setup is very similar to [Svelte CLI's](https://github.com/sveltejs/svelte-cli), but allows you to [configure it however you want](/configurations/custom-webpack-config/).
-
-In this guide, we are trying to set up Storybook for your Svelte project.
-
-> It is very important to remember that Svelte components are precompiled from
-> .svelte or .html files to vanilla javascript, so there is no 'runtime'.
-
-## Table of contents
-
-- [Add @storybook/svelte](#add-storybooksvelte)
-- [Create the NPM script](#create-the-npm-script)
-- [Create the config file](#create-the-config-file)
-- [Write your stories](#write-your-stories)
-- [Run your Storybook](#run-your-storybook)
-
-## Add @storybook/svelte
-
-First of all, you need to add `@storybook/svelte` to your project. To do that, simply run:
-
-```sh
-yarn add @storybook/svelte --dev
-```
-
-## Create the NPM script
-
-Add the following NPM script to your `package.json` in order to start the storybook later in this guide:
-
-```json
-{
- "scripts": {
- "storybook": "start-storybook -p 9001 -c .storybook"
- }
-}
-```
-
-Those flags mean port (-p) 9001 and configuration (-c) located in the .storybook directory.
-
-## Create the config file
-
-Storybook can be configured in several different ways.
-
-That’s why we need a config directory. We've added a `-c` option to the above NPM script mentioning `.storybook` as the config directory.
-
-Here's an example `.storybook/config.js` to get you started:
-
-```js
-import { configure } from '@storybook/svelte';
-
-function loadStories() {
- // You can require as many stories as you need.
- require('../src/stories');
-}
-
-configure(loadStories, module);
-```
-
-> This stories folder is just an example, you can load stories from wherever you want to.
-> We think stories are best located close to the source files.
-
-## Write your stories
-
-Now you can write some stories inside the `../stories/index.js` file, like this:
-
-```js
-// Story about MyButton
-import { storiesOf } from '@storybook/svelte';
-
-import MyButton from '../components/MyButton.svelte';
-
-storiesOf('MyButton', module)
- .add('simple component example', () => ({
- Component: MyButton,
-
- data: {
- rounded: true
- },
-
- on: {
- click: event => {
- console.log('clicked', event);
- }
- }
- }));
-```
-
-Svelte storybooks don't support using templates in a story yet. Instead,
-you can create a .svelte file to compose components together, or simply to access
-all normal Svelte functionality, like slots.
-
-So you can create a story "view" file, essentially just a .svelte file to load
-your components into to test.
-
-```html
-
-
- {buttonText}
-
-```
-
-In this example, the `on:click` that is heard on the `MyButton` component is
-simply passed up to the containing component `MyButtonView` using the svelte
-shorthand. It's the equivalent to `on:click="fire('click', event)"`, but it's
-worth knowing about especially in this "component wrapper" scenario.
-
-> If your component doesn't use slots, you don't need to do this, but if it does
-> or some other svelte functionality that requires the component to exist in a svelte
-> view, then this is how to do that.
-
-You would then write a story for this "view" the exact same way you did with a component.
-
-```js
-// MyButtonView
-import { storiesOf } from '@storybook/svelte';
-
-import MyButtonView from '../views/MyButtonView.svelte';
-
-storiesOf('MyButtonView', module)
- .add('wrapped component(s) example', () => ({
- Components: MyButtonView,
-
- data: {
- buttonText: 'Some button text',
- rounded: true
- },
-
- on: {
- click: (event) => {
- console.log('clicked', event);
- }
- }
- }));
-```
-
-Each story represents a single state of your component.
-
-## Run your Storybook
-
-Now everything is ready. Simply run your storybook with:
-
-```sh
-yarn storybook
-```
-
-Now you can change components and write stories whenever you need to.
-You'll get those changes into Storybook in a snap with the help of Webpack's HMR API.
diff --git a/docs/src/pages/basics/guide-vue/index.md b/docs/src/pages/basics/guide-vue/index.md
deleted file mode 100644
index 2fa14f4da3e7..000000000000
--- a/docs/src/pages/basics/guide-vue/index.md
+++ /dev/null
@@ -1,130 +0,0 @@
----
-id: 'guide-vue'
-title: 'Storybook for Vue'
----
-
-You may have tried to use our quick start guide to setup your project for Storybook. If you want to set up Storybook manually, this is the guide for you.
-
-> This will also help you understand how Storybook works.
-
-## Starter Guide Vue
-
-Storybook has its own Webpack setup and a dev server.
-The Webpack setup is very similar to [Vue CLI's](https://github.com/vuejs/vue-cli), but allows you to [configure it however you want](/configurations/custom-webpack-config/).
-
-In this guide, we are trying to set up Storybook for your Vue project.
-
-## Table of contents
-
-- [Add @storybook/vue](#add-storybookvue)
-- [Add vue and babel-core](#add-vue-and-babel-core)
-- [Create the NPM script](#create-the-npm-script)
-- [Create the config file](#create-the-config-file)
-- [Write your stories](#write-your-stories)
-- [Run your Storybook](#run-your-storybook)
-
-## Add @storybook/vue
-
-First of all, you need to add `@storybook/vue` to your project. To do that, simply run:
-
-```sh
-npm i --save-dev @storybook/vue
-```
-
-## Add vue, babel-core, and babel-loader
-
-Make sure that you have `vue`, `babel-core`, `babel-loader` in your dependencies as well because we list it as a peerDependency:
-
-```sh
-npm i --save vue
-npm i --save-dev babel-loader vue-loader vue-template-compiler
-npm i --save-dev @babel/core babel-preset-vue
-```
-
-## Create the NPM script
-
-Add the following NPM script to your `package.json` in order to start the storybook later in this guide:
-
- {
- "scripts": {
- "storybook": "start-storybook -p 9001 -c .storybook"
- }
- }
-
-## Create the config file
-
-Storybook can be configured in several different ways.
-That’s why we need a config directory. We've added a `-c` option to the above NPM script mentioning `.storybook` as the config directory.
-
-There are 3 things you need to tell Storybook to do:
-
-1. Import and globally register with [`Vue.component()`](https://vuejs.org/v2/api/#Vue-component) any global custom components just like you did with your project. (Note: [components registered locally](https://vuejs.org/v2/guide/components.html#Local-Registration) will be brought in automatically).
-2. For any required Vue plugins (e.g. `vuex`), you'll also need to [install these with `Vue.use`](https://vuejs.org/v2/api/#Vue-use).
-3. Require your stories.
-
-Here's an example `.storybook/config.js` to get you started:
-
-```js
-import { configure } from '@storybook/vue';
-
-import Vue from 'vue';
-import Vuex from 'vuex'; // Vue plugins
-
-// Import your custom components.
-import Mybutton from '../src/stories/Button.vue';
-
-// Install Vue plugins.
-Vue.use(Vuex);
-
-// Register custom components.
-Vue.component('my-button', Mybutton);
-
-function loadStories() {
- // You can require as many stories as you need.
- require('../src/stories');
-}
-
-configure(loadStories, module);
-```
-
-This example registered your custom `Button.vue` component, installed the Vuex plugin, and loaded your Storybook stories defined in `../stories/index.js`.
-
-All custom components and Vue plugins should be registered before calling `configure()`.
-
-> This stories folder is just an example, you can load stories from wherever you want to.
-> We think stories are best located close to the source files.
-
-## Write your stories
-
-Now you can write some stories inside the `../stories/index.js` file, like this:
-
-```js
-import Vue from 'vue';
-
-import { storiesOf } from '@storybook/vue';
-
-import MyButton from './Button.vue';
-
-storiesOf('MyButton', module)
- .add('story as a template', () => 'story as a function template')
- .add('story as a component', () => ({
- components: { MyButton },
- template: 'rounded'
- }));
-```
-
-Each story is a single state of your component. In the above case, there are two stories for the MyButton component:
-
-1. story as a template
-2. story as a component
-
-## Run your Storybook
-
-Now everything is ready. Simply run your storybook with:
-
-```sh
-npm run storybook
-```
-
-Now you can change components and write stories whenever you need to.
-You'll get those changes into Storybook in a snap with the help of Webpack's HMR API.
diff --git a/docs/src/pages/basics/slow-start-guide/index.md b/docs/src/pages/basics/slow-start-guide/index.md
deleted file mode 100644
index 02b64af3167f..000000000000
--- a/docs/src/pages/basics/slow-start-guide/index.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-id: 'slow-start-guide'
-title: 'Slow Start Guide'
----
-
-Storybook supports multiple UI libraries. The manual setup for each framework is different:
-
-- [Storybook for React](/basics/guide-react/)
-- [Storybook for React Native](/basics/guide-react-native/)
-- [Storybook for Vue](/basics/guide-vue/)
-- [Storybook for Angular](/basics/guide-angular/)
-- [Storybook for Mithril](/basics/guide-mithril/)
-- [Storybook for Marko](/basics/guide-marko/)
-- [Storybook for HTML](/basics/guide-html/)
-- [Storybook for Svelte](/basics/guide-svelte/)
-- [Storybook for Riot](/basics/guide-riot/)
-- [Storybook for Preact](/basics/guide-preact/)
diff --git a/docs/src/pages/basics/writing-stories/index.md b/docs/src/pages/basics/writing-stories/index.md
index 1a6167ad0b95..67aaeba7330f 100644
--- a/docs/src/pages/basics/writing-stories/index.md
+++ b/docs/src/pages/basics/writing-stories/index.md
@@ -5,7 +5,7 @@ title: 'Writing Stories'
Storybook is all about writing stories. A story usually contains a single state of one component, almost like a visual test case.
-> Technically, a story is a function that returns a React element.
+> Technically, a story is a function that returns something that can be rendered to screen.
A Storybook can be comprised of many stories for many components.
@@ -13,9 +13,52 @@ A Storybook can be comprised of many stories for many components.
There are no rules for this, but in general, stories are easier to maintain when they are located closer to components.
-For example, if the UI components live in a directory called: `src/components`, then the stories can be written inside the `src/stories` directory.
+Some examples:
-The Storybook config file can also be edited to load stories from other folders too.
+
+ stories inside component directory
+
+ ```plaintext
+ •
+ └── src
+ └── components
+ └── button
+ ├── button.js
+ └── button.stories.js
+ ```
+
+
+
+
+ stories sub-directory in component directory
+
+ ```plaintext
+ •
+ └── src
+ └── components
+ └── button
+ ├── button.js
+ └── stories
+ └── button.stories.js
+ ```
+
+
+
+
+ stories directory outside src directory
+
+ ```plaintext
+ •
+ ├── src
+ │ └── components
+ │ └── button.js
+ └── stories
+ └── button.stories.js
+ ```
+
+
+
+It's up to you to find a naming/placing scheme that works for your project/team.
## Writing Stories
@@ -73,7 +116,7 @@ The **React Native** packager resolves all the imports at build-time, so it's no
A decorator is a way to wrap a story with a common set of components. Here is an example for centering all components:
-```js
+```jsx
import React from 'react';
import { storiesOf } from '@storybook/react';
import MyComponent from '../my_component';
@@ -88,7 +131,7 @@ This only applies the decorator to the current set of stories. (In this example,
It is possible to apply a decorator **globally** to all the stories. Here is an example of the Storybook config file:
-```js
+```jsx
import React from 'react';
import { configure, addDecorator } from '@storybook/react';
@@ -103,7 +146,7 @@ configure(function() {
As of storybook 3.3, [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) can be used in Storybook by default. Users can import a markdown file which extracts the raw markdown content into a string. The string can then be used in any addon that supports markdown such as notes and info.
-```js
+```jsx
import React from 'react';
import { storiesOf } from '@storybook/react';
import MyComponent from './MyComponent';
@@ -118,7 +161,7 @@ storiesOf('Component', module).add('With Markdown', () => , {
Stories can be organized in a nested structure using "/" as a separator:
-```js
+```jsx
// file: src/stories/index.js
import React from 'react';
diff --git a/docs/src/pages/configurations/cli-options/index.md b/docs/src/pages/configurations/cli-options/index.md
index acd0804beef0..4f92db3ff356 100644
--- a/docs/src/pages/configurations/cli-options/index.md
+++ b/docs/src/pages/configurations/cli-options/index.md
@@ -11,33 +11,37 @@ Here are all those options:
## For start-storybook
- Usage: start-storybook [options]
-
- Options:
-
- --help output usage information
- -V, --version output the version number
- -p, --port [number] Port to run Storybook
- -h, --host [string] Host to run Storybook
- -s, --static-dir Directory where to load static files from, comma-separated list
- -c, --config-dir [dir-name] Directory where to load Storybook configurations from
- --https Serve Storybook over HTTPS. Note: You must provide your own certificate information.
- --ssl-ca Provide an SSL certificate authority. (Optional with --https, required if using a self-signed certificate)
- --ssl-cert Provide an SSL certificate. (Required with --https)
- --ssl-key Provide an SSL key. (Required with --https)
- --smoke-test Exit after successful start
- --ci CI mode (skip interactive prompts, don't open browser)
- --quiet Suppress verbose build output
+```plaintext
+Usage: start-storybook [options]
+
+Options:
+
+--help output usage information
+-V, --version output the version number
+-p, --port [number] Port to run Storybook
+-h, --host [string] Host to run Storybook
+-s, --static-dir Directory where to load static files from, comma-separated list
+-c, --config-dir [dir-name] Directory where to load Storybook configurations from
+--https Serve Storybook over HTTPS. Note: You must provide your own certificate information.
+--ssl-ca Provide an SSL certificate authority. (Optional with --https, required if using a self-signed certificate)
+--ssl-cert Provide an SSL certificate. (Required with --https)
+--ssl-key Provide an SSL key. (Required with --https)
+--smoke-test Exit after successful start
+--ci CI mode (skip interactive prompts, don't open browser)
+--quiet Suppress verbose build output
+```
## For build-storybook
- Usage: build-storybook [options]
+```plaintext
+Usage: build-storybook [options]
- Options:
+Options:
- -h, --help output usage information
- -V, --version output the version number
- -s, --static-dir Directory where to load static files from, comma-separated list
- -o, --output-dir [dir-name] Directory where to store built files
- -c, --config-dir [dir-name] Directory where to load Storybook configurations from
- -w, --watch Enable watch mode
+-h, --help output usage information
+-V, --version output the version number
+-s, --static-dir Directory where to load static files from, comma-separated list
+-o, --output-dir [dir-name] Directory where to store built files
+-c, --config-dir [dir-name] Directory where to load Storybook configurations from
+-w, --watch Enable watch mode
+```
diff --git a/docs/src/pages/configurations/custom-webpack-config/index.md b/docs/src/pages/configurations/custom-webpack-config/index.md
index 3799d04f2b72..ba92df931408 100644
--- a/docs/src/pages/configurations/custom-webpack-config/index.md
+++ b/docs/src/pages/configurations/custom-webpack-config/index.md
@@ -5,9 +5,171 @@ title: 'Custom Webpack Config'
You can customize Storybook's webpack setup by providing a `webpack.config.js` file exporting a **webpack 4** compatible config exported as a **commonjs module**.
-The file can export an object or a function. The former configures in [extend mode](#extend-mode), the latter in [full control mode](#full-control-mode), both described here.
+Storybook has its own Webpack setup and a dev server.
+The webpack config [is configurable](/configurations/webpack), and the default can depend on which framework you're using and whether you've used a generator like [Create React App](https://github.com/facebookincubator/create-react-app) or Angular CLI etc.
-## Extend Mode
+> We're trying to make storybook more zero-config over time, **help to hook into the config of generators is very welcome**.
+
+
+ This is what the config for storybook looks like when using CRA in dev-mode:
+
+ ```js
+ {
+ mode: 'development',
+ bail: false,
+ devtool: '#cheap-module-source-map',
+ entry: [
+ '@storybook/core/dist/server/common/polyfills.js',
+ '@storybook/core/dist/server/preview/globals.js',
+ '/config.js',
+ 'webpack-hot-middleware/client.js?reload=true',
+ ],
+ output: {
+ path: './',
+ filename: '[name].[hash].bundle.js',
+ publicPath: '',
+ },
+ plugins: [
+ HtmlWebpackPlugin {
+ options: {
+ template: '@storybook/core/dist/server/templates/index.ejs',
+ templateContent: false,
+ templateParameters: [Function: templateParameters],
+ filename: 'iframe.html',
+ hash: false,
+ inject: false,
+ compile: true,
+ favicon: false,
+ minify: undefined,
+ cache: true,
+ showErrors: true,
+ chunks: 'all',
+ excludeChunks: [],
+ chunksSortMode: 'none',
+ meta: {},
+ title: 'Webpack App',
+ xhtml: false,
+ alwaysWriteToDisk: true,
+ },
+ },
+ DefinePlugin {
+ definitions: {
+ 'process.env': {
+ NODE_ENV: '"development"',
+ NODE_PATH: '""',
+ PUBLIC_URL: '"."',
+ ''
+ ''
+ },
+ },
+ },
+ WatchMissingNodeModulesPlugin {
+ nodeModulesPath: './node_modules',
+ },
+ HotModuleReplacementPlugin {},
+ CaseSensitivePathsPlugin {},
+ ProgressPlugin {},
+ DefinePlugin {
+ definitions: {
+ ''
+ ''
+ },
+ },
+ ],
+ module: {
+ rules: [
+ { test: /\.(mjs|jsx?)$/,
+ use: [
+ { loader: 'babel-loader', options:
+ { cacheDirectory: './node_modules/.cache/storybook',
+ presets: [
+ [ './node_modules/@babel/preset-env/lib/index.js', { shippedProposals: true, useBuiltIns: 'usage' } ],
+ './node_modules/@babel/preset-react/lib/index.js',
+ './node_modules/@babel/preset-flow/lib/index.js',
+ ],
+ plugins: [
+ './node_modules/@babel/plugin-proposal-object-rest-spread/lib/index.js',
+ './node_modules/@babel/plugin-proposal-class-properties/lib/index.js',
+ './node_modules/@babel/plugin-syntax-dynamic-import/lib/index.js',
+ [ './node_modules/babel-plugin-emotion/dist/babel-plugin-emotion.cjs.js', { sourceMap: true, autoLabel: true } ],
+ './node_modules/babel-plugin-macros/dist/index.js',
+ './node_modules/@babel/plugin-transform-react-constant-elements/lib/index.js',
+ './node_modules/babel-plugin-add-react-displayname/index.js',
+ [ './node_modules/babel-plugin-react-docgen/lib/index.js', { DOC_GEN_COLLECTION_NAME: 'STORYBOOK_REACT_CLASSES' } ],
+ ],
+ },
+ },
+ ],
+ include: [ './' ],
+ exclude: [ './node_modules' ],
+ },
+ { test: /\.md$/,
+ use: [
+ { loader: './node_modules/raw-loader/index.js' },
+ ],
+ },
+ { test: /\.css$/,
+ use: [
+ './node_modules/style-loader/index.js',
+ { loader: './node_modules/css-loader/dist/cjs.js', options: { importLoaders: 1 } },
+ { loader: './node_modules/postcss-loader/src/index.js', options: { ident: 'postcss', postcss: {}, plugins: [Function: plugins] } },
+ ],
+ },
+ { test: /\.(svg|ico|jpg|jpeg|png|gif|eot|otf|webp|ttf|woff|woff2|cur|ani)(\?.*)?$/,
+ loader: './node_modules/file-loader/dist/cjs.js',
+ query: { name: 'static/media/[name].[hash:8].[ext]' },
+ },
+ { test: /\.(mp4|webm|wav|mp3|m4a|aac|oga)(\?.*)?$/,
+ loader: './node_modules/url-loader/dist/cjs.js',
+ query: { limit: 10000, name: 'static/media/[name].[hash:8].[ext]' },
+ },
+ ],
+ },
+ resolve: {
+ extensions: [ '.mjs', '.js', '.jsx', '.json' ],
+ modules: [ 'node_modules' ],
+ mainFields: [ 'browser', 'main', 'module' ],
+ alias: {
+ 'core-js': './node_modules/core-js',
+ react: './node_modules/react',
+ 'react-dom': './node_modules/react-dom',
+ },
+ },
+ optimization: {
+ splitChunks: { chunks: 'all' },
+ runtimeChunk: true,
+ minimizer: [ [Object] ],
+ },
+ performance: { hints: false },
+ }
+ ```
+
+
+### Debug the default webpack config
+
+
+ To effectively customise the webpack config, you might need to get the full default config it's using.
+
+
+
+ - Create a `.storybook/webpack.config.js` file.
+ - Edit it's contents:
+ ```js
+ module.exports = async ({ config }) => console.dir(config.plugins, { depth: null }) || config;
+ ```
+ - Then run storybook:
+ ```sh
+ yarn storybook --quiet
+ ```
+
+ The console should log the entire config, for you to inspect.
+
+
+## Webpack customisation modes
+
+The file can export an [object](#extend-mode) or a [function](#full-control-mode).
+
+### Extend Mode
If your file exports an **object**, it puts Storybook into **extend-mode**.
@@ -38,11 +200,10 @@ But you won't be able to change the following config options:
- entry
- output
-- js loader with babel
For the advanced usage we strongly recommend [full control mode](#full-control-mode).
-## Full Control Mode
+### Full Control Mode
If your file exports a **function**, it puts Storybook into **full-control-mode**.
@@ -54,7 +215,7 @@ For example, here's a `webpack.config.js` to add [SASS](http://sass-lang.com/) s
const path = require('path');
// Export a function. Accept the base config as the only param.
-module.exports = ({ config, mode }) => {
+module.exports = async ({ config, mode }) => {
// `mode` has a value of 'DEVELOPMENT' or 'PRODUCTION'
// You can change the configuration based on that.
// 'PRODUCTION' is used when building the static version of storybook.
@@ -75,8 +236,6 @@ Storybook uses the config returned from the above function. So edit `config` wit
- entry
- output
-- first loader in the module.loaders (Babel loader for JS)
-- all existing plugins
> If your custom webpack config uses a loader that does not explicitly include specific file extensions via the `test` property, it is necessary to `exclude` the `.ejs` file extension from that loader.
@@ -86,3 +245,16 @@ If you have an existing webpack config for your project and want to reuse this a
- Import your main webpack config into Storybook's `webpack.config.js` and use the loaders and plugins used in that.
- Create a new file with common webpack options and use it in both inside the main webpack config and inside Storybook's `webpack.config.js`.
+
+**Example**
+*merging the loaders from your app's `webpack.config.js` with storybook's*
+
+```js
+const path = require('path');
+// your app's webpack.config.js
+const custom = require('../webpack.config.js');
+
+module.exports = async ({ config, mode }) => {
+ return {...config, loaders: custom.loaders };
+};
+```
diff --git a/docs/src/pages/configurations/default-config/index.md b/docs/src/pages/configurations/default-config/index.md
index 1705f0dabe8c..d97ed7a75b59 100644
--- a/docs/src/pages/configurations/default-config/index.md
+++ b/docs/src/pages/configurations/default-config/index.md
@@ -3,22 +3,8 @@ id: 'default-config'
title: 'Default Config'
---
-Storybook has a default Webpack setup which suits a large range of projects.
-It is similar to [Create React App](https://github.com/facebookincubator/create-react-app)'s config when using react, and has been tweaked to closely resemble the webpack config generated by [Vue CLI](https://github.com/vuejs/vue-cli).
-
Let's learn about the default config comes with Storybook.
-## Table of Contents
-
-- [Babel](#babel)
- - [ES2016+ Support](#es2016-support)
- - [.babelrc support](#babelrc-support)
-- [Webpack](#webpack)
- - [CSS Support](#css-support)
- - [Image and Static File Support](#image-and-static-file-support)
- - [JSON Loader](#json-loader)
-- [NPM Modules](#npm-modules)
-
## Babel
We use Babel for JavaScript(ES6) transpiling.
@@ -38,7 +24,146 @@ So, you could use any babel plugins or presets that you have used in your projec
## Webpack
We use Webpack to serve and load JavaScript modules for the web.
-We've added some Webpack loaders to bring some good defaults. (This setup is very close to what you get with the [Create React App](https://github.com/facebookincubator/create-react-app).)
+
+The webpack config [is configurable](/configurations/webpack), and the default can depend on which framework you're using and whether you've used a generator like [Create React App](https://github.com/facebookincubator/create-react-app) or Angular CLI etc.
+
+> We're trying to make storybook more zero-config over time, **help to hook into the config of generators is very welcome**.
+
+
+ This is what the config for storybook looks like when using CRA in dev-mode:
+
+ ```js
+ {
+ mode: 'development',
+ bail: false,
+ devtool: '#cheap-module-source-map',
+ entry: [
+ '@storybook/core/dist/server/common/polyfills.js',
+ '@storybook/core/dist/server/preview/globals.js',
+ '/config.js',
+ 'webpack-hot-middleware/client.js?reload=true',
+ ],
+ output: {
+ path: './',
+ filename: '[name].[hash].bundle.js',
+ publicPath: '',
+ },
+ plugins: [
+ HtmlWebpackPlugin {
+ options: {
+ template: '@storybook/core/dist/server/templates/index.ejs',
+ templateContent: false,
+ templateParameters: [Function: templateParameters],
+ filename: 'iframe.html',
+ hash: false,
+ inject: false,
+ compile: true,
+ favicon: false,
+ minify: undefined,
+ cache: true,
+ showErrors: true,
+ chunks: 'all',
+ excludeChunks: [],
+ chunksSortMode: 'none',
+ meta: {},
+ title: 'Webpack App',
+ xhtml: false,
+ alwaysWriteToDisk: true,
+ },
+ },
+ DefinePlugin {
+ definitions: {
+ 'process.env': {
+ NODE_ENV: '"development"',
+ NODE_PATH: '""',
+ PUBLIC_URL: '"."',
+ ''
+ ''
+ },
+ },
+ },
+ WatchMissingNodeModulesPlugin {
+ nodeModulesPath: './node_modules',
+ },
+ HotModuleReplacementPlugin {},
+ CaseSensitivePathsPlugin {},
+ ProgressPlugin {},
+ DefinePlugin {
+ definitions: {
+ ''
+ ''
+ },
+ },
+ ],
+ module: {
+ rules: [
+ { test: /\.(mjs|jsx?)$/,
+ use: [
+ { loader: 'babel-loader', options:
+ { cacheDirectory: './node_modules/.cache/storybook',
+ presets: [
+ [ './node_modules/@babel/preset-env/lib/index.js', { shippedProposals: true, useBuiltIns: 'usage' } ],
+ './node_modules/@babel/preset-react/lib/index.js',
+ './node_modules/@babel/preset-flow/lib/index.js',
+ ],
+ plugins: [
+ './node_modules/@babel/plugin-proposal-object-rest-spread/lib/index.js',
+ './node_modules/@babel/plugin-proposal-class-properties/lib/index.js',
+ './node_modules/@babel/plugin-syntax-dynamic-import/lib/index.js',
+ [ './node_modules/babel-plugin-emotion/dist/babel-plugin-emotion.cjs.js', { sourceMap: true, autoLabel: true } ],
+ './node_modules/babel-plugin-macros/dist/index.js',
+ './node_modules/@babel/plugin-transform-react-constant-elements/lib/index.js',
+ './node_modules/babel-plugin-add-react-displayname/index.js',
+ [ './node_modules/babel-plugin-react-docgen/lib/index.js', { DOC_GEN_COLLECTION_NAME: 'STORYBOOK_REACT_CLASSES' } ],
+ ],
+ },
+ },
+ ],
+ include: [ './' ],
+ exclude: [ './node_modules' ],
+ },
+ { test: /\.md$/,
+ use: [
+ { loader: './node_modules/raw-loader/index.js' },
+ ],
+ },
+ { test: /\.css$/,
+ use: [
+ './node_modules/style-loader/index.js',
+ { loader: './node_modules/css-loader/dist/cjs.js', options: { importLoaders: 1 } },
+ { loader: './node_modules/postcss-loader/src/index.js', options: { ident: 'postcss', postcss: {}, plugins: [Function: plugins] } },
+ ],
+ },
+ { test: /\.(svg|ico|jpg|jpeg|png|gif|eot|otf|webp|ttf|woff|woff2|cur|ani)(\?.*)?$/,
+ loader: './node_modules/file-loader/dist/cjs.js',
+ query: { name: 'static/media/[name].[hash:8].[ext]' },
+ },
+ { test: /\.(mp4|webm|wav|mp3|m4a|aac|oga)(\?.*)?$/,
+ loader: './node_modules/url-loader/dist/cjs.js',
+ query: { limit: 10000, name: 'static/media/[name].[hash:8].[ext]' },
+ },
+ ],
+ },
+ resolve: {
+ extensions: [ '.mjs', '.js', '.jsx', '.json' ],
+ modules: [ 'node_modules' ],
+ mainFields: [ 'browser', 'main', 'module' ],
+ alias: {
+ 'core-js': './node_modules/core-js',
+ react: './node_modules/react',
+ 'react-dom': './node_modules/react-dom',
+ },
+ },
+ optimization: {
+ splitChunks: { chunks: 'all' },
+ runtimeChunk: true,
+ minimizer: [ [Object] ],
+ },
+ performance: { hints: false },
+ }
+ ```
+
+
### CSS Support
@@ -54,7 +179,7 @@ import 'bootstrap/dist/css/bootstrap.css';
import './styles.css';
```
-> **Note:** this is plain CSS only. If you need a preprocessor like SASS, you need to [customize the webpack config](/configurations/custom-webpack-config/).
+> **Note:** with some frameworks/clis we inject plain CSS only. If you need a preprocessor like SASS, you need to [customize the webpack config](/configurations/custom-webpack-config/).
>
> **Warning:** storybooks for projects that use Angular CLI cannot import CSS by default. They must either [customize the webpack config](/configurations/custom-webpack-config/), or use the inline loader syntax:
> ```js
@@ -88,6 +213,18 @@ So, this is a good approach to loading all of your static content.
You can import `.json` files, as you do with Node.js.
This will also allow you to use NPM projects, which imports `.json` files inside them.
+```js
+import React from 'react';
+import { storiesOf } from '@storybook/react';
+
+import data from './data.json';
+
+storiesOf('Component', module)
+ .add('with data', () => (
+
{JSON.stringify(data, null, 2)}
+ ));
+```
+
## NPM Modules
You can use any of the NPM modules installed on your project.
diff --git a/docs/src/pages/configurations/standalone-options/index.md b/docs/src/pages/configurations/standalone-options/index.md
index baf61721519e..ff5401c22906 100644
--- a/docs/src/pages/configurations/standalone-options/index.md
+++ b/docs/src/pages/configurations/standalone-options/index.md
@@ -27,7 +27,9 @@ storybook({
Mode is defining what Storybook mode will be applied:
- dev - run Storybook in a dev mode - similar to "start-storybook" in CLI
+### dev
+
+run Storybook in a dev mode - similar to `start-storybook` in CLI
```js
const storybook = require('@storybook/react/standalone');
@@ -38,7 +40,9 @@ storybook({
});
```
- static - build static version of Storybook - similar to "build-storybook" in CLI
+### static
+
+build static version of Storybook - similar to `build-storybook` in CLI
```js
const storybook = require('@storybook/react/standalone');
@@ -53,28 +57,29 @@ Other options are similar to those in the CLI.
## For "dev" mode:
- Options:
-
- port [number] Port to run Storybook
- host [string] Host to run Storybook
- staticDir Directory where to load static files from, array of strings
- configDir [dir-name] Directory where to load Storybook configurations from
- https Serve Storybook over HTTPS. Note: You must provide your own certificate information.
- sslCa Provide an SSL certificate authority. (Optional with "https", required if using a self-signed certificate)
- sslCert Provide an SSL certificate. (Required with "https")
- sslKey Provide an SSL key. (Required with "https")
- smokeTest Exit after successful start
- ci CI mode (skip interactive prompts, don't open browser)
- quiet Suppress verbose build output
+```plaintext
+port [number] Port to run Storybook
+host [string] Host to run Storybook
+staticDir Directory where to load static files from, array of strings
+configDir [dir-name] Directory where to load Storybook configurations from
+https Serve Storybook over HTTPS. Note: You must provide your own certificate information.
+sslCa Provide an SSL certificate authority. (Optional with "https", required if using a self-signed certificate)
+sslCert Provide an SSL certificate. (Required with "https")
+sslKey Provide an SSL key. (Required with "https")
+smokeTest Exit after successful start
+ci CI mode (skip interactive prompts, don't open browser)
+quiet Suppress verbose build output
+```
## For "static" mode:
- Options:
-
- staticDir Directory where to load static files from, array of strings
- outputDir [dir-name] Directory where to store built files
- configDir [dir-name] Directory where to load Storybook configurations from
- watch Enable watch mode
+```plaintext
+staticDir Directory where to load static files from, array of strings
+outputDir [dir-name] Directory where to store built files
+configDir [dir-name] Directory where to load Storybook configurations from
+watch Enable watch mode
+quiet Suppress verbose build output
+```
Example:
diff --git a/docs/src/pages/configurations/theming/index.md b/docs/src/pages/configurations/theming/index.md
index 6dad5615fbf8..4fc8d9c9c18b 100644
--- a/docs/src/pages/configurations/theming/index.md
+++ b/docs/src/pages/configurations/theming/index.md
@@ -46,57 +46,58 @@ addParameters({
## Create a theme quickstart
+The `storybook/theming` is build using TypeScript, so this should help create a valid theme for typescript users. The types are part of the package itself.
+
The easiest way to customize Storybook to generate a new theme using `create()`. This function includes shorthands for the most common theme variables. Here's how to use it.
First create a new file in `.storybook` called `yourTheme.js`.
Next paste the code below and tweak the variables.
-```
+```ts
import { create } from '@storybook/theming';
export default create({
- // Is this a 'light' or 'dark' theme?
base: 'light',
- // Color palette
- colorPrimary: 'red', // primary color
- colorSecondary: 'pink', // secondary color
+ colorPrimary: 'hotpink',
+ colorSecondary: 'deepskyblue',
// UI
- appBg: 'papayawhip',
- appContentBg: 'white',
- appBorderColor: 'rgba(0,0,0,.1)',
+ appBg: 'white',
+ appContentBg: 'silver',
+ appBorderColor: 'grey',
appBorderRadius: 4,
- // Fonts
- fontBase: '"Helvetica", Arial, sans-serif',
- fontCode: 'Monaco, monospace',
+ // Typography
+ fontBase: '"Open Sans", sans-serif',
+ fontCode: 'monospace',
// Text colors
- textColor: '#FFFFFF',
- textInverseColor: '#333333',
+ textColor: 'black',
+ textInverseColor: 'rgba(255,255,255,0.9)',
// Toolbar default and active colors
- barTextColor: '#999999',
- barSelectedColor: 'blue',
- barBg: 'white',
+ barTextColor: 'silver',
+ barSelectedColor: 'black',
+ barBg: 'hotpink',
// Form colors
inputBg: 'white',
- inputBorder: 'rgba(0,0,0,.1)',
- inputTextColor: '#333333',
+ inputBorder: 'silver',
+ inputTextColor: 'black',
inputBorderRadius: 4,
- // Brand logo/text
- brand: ``,
+ brandTitle: 'My custom storybook',
+ brandUrl: 'https://example.com',
+ brandImage: 'https://placehold.it/350x150',
});
```
Finally, import your theme into `.storybook/config` and add it to your Storybook parameters.
-```
-import yourTheme from './yourTheme';
+```js
+import { yourTheme } from './yourTheme';
addParameters({
options: {
@@ -105,13 +106,27 @@ addParameters({
});
```
+Many them variables are optional, the `base` property is NOT. This is a perfectly valid theme:
+
+```ts
+import { create } from '@storybook/theming';
+
+export default create({
+ base: 'light',
+
+ brandTitle: 'My custom storybook',
+ brandUrl: 'https://example.com',
+ brandImage: 'https://placehold.it/350x150',
+});
+```
+
## Addons and theme creation
Some addons require specific theme variables that a Storybook user must add. If you share your theme with the community make sure to support the official and other popular addons so your users have a consistent experience.
For example, the popular Actions addon uses [react-inspector](https://github.com/xyc/react-inspector/blob/master/src/styles/themes/chromeLight.js) which has themes of it's own. Supply additional theme variables to style it like so:
-```
+```js
addonActionsTheme: {
...chromeLight,
BASE_FONT_FAMILY: typography.fonts.mono,
@@ -123,13 +138,13 @@ addonActionsTheme: {
For a native Storybook experience, we encourage addon authors to reuse the theme variables above. The theming engine relies on [emotion](https://emotion.sh/), a CSS-in-JS library.
-```
+```js
import { styled } from '@storybook/theming';
```
Use the theme variables in object notation:
-```
+```js
const Component = styled.div(
({ theme }) => ({
background: theme.background.app,
@@ -138,102 +153,11 @@ const Component = styled.div(
);
```
-Or with styled-components template literals:
+Or with template literals:
-```
+```js
const Component = styled.div`
background: `${props => props.theme.background.app}`
width: 0;
`;
```
-
-### Advanced theming
-
-For further customization adjust theme variables manually.
-
-This is the master list:
-
-```
-base: 'light' | 'dark',
-color: {
- primary
- secondary
- tertiary
- ancillary
-
- orange
- gold
- green
- seafoam
- purple
- ultraviolet
-
- lightest
- lighter
- light
- mediumlight
- medium
- mediumdark
- dark
- darker
- darkest
-
- border
-
- positive
- negative
- warning
-
- defaultText
- inverseText
-}
-background: {
- app
- content
- hoverable
-
- positive
- negative
- warning
-}
-typography: {
- fonts: {
- base
- mono
- }
- weight: {
- regular
- bold
- black
- }
- size: {
- s1
- s2
- s3
- m1
- m2
- m3
- l1
- l2
- l3
- code
- }
- input: {
- border
- background
- color
- borderRadius
- };
-
- layoutMargin
- appBorderColor
- appBorderRadius
-
- barTextColor
- barSelectedColor
- barBg
-
- brand
-}
-TODO finish this, what's the best way to document?
-```
diff --git a/docs/src/pages/guides/guide-angular/index.md b/docs/src/pages/guides/guide-angular/index.md
new file mode 100644
index 000000000000..1f0c082c627e
--- /dev/null
+++ b/docs/src/pages/guides/guide-angular/index.md
@@ -0,0 +1,147 @@
+---
+id: 'guide-angular'
+title: 'Storybook for Angular'
+---
+
+## Automatic setup
+
+You may have tried to use our quick start guide to setup your project for Storybook.
+If it failed because it couldn't detect you're using angular, you could try forcing it to use angular:
+
+```sh
+npx -p @storybook/cli sb init --type angular
+```
+
+## Manual setup
+
+If you want to set up Storybook manually for your Angular project, this is the guide for you.
+
+## Step 1: Add dependencies
+
+### Add @storybook/angular
+
+Add `@storybook/angular` to your project. To do that, run:
+
+```sh
+npm install @storybook/angular --save-dev
+```
+
+### Add @babel/core, and babel-loader
+
+Make sure that you have `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peer dependencies:
+
+```sh
+npm install babel-loader @babel/core --save-dev
+```
+
+## Step 2: Add a npm script
+
+Then add the following NPM script to your `package.json` in order to start the storybook later in this guide:
+
+```json
+{
+ "scripts": {
+ "storybook": "start-storybook"
+ }
+}
+```
+
+## Step 3: Create the config file
+
+For a basic Storybook configuration, the only thing you need to do is tell Storybook where to find stories.
+
+To do that, create a file at `.storybook/config.js` with the following content:
+
+```ts
+import { configure } from '@storybook/angular';
+
+function loadStories() {
+ require('../stories/index.js');
+ // You can require as many stories as you need.
+}
+
+configure(loadStories, module);
+```
+
+That'll load stories in `../stories/index.js`. You can choose where to place stories, you can co-locate them with source files, or place them in an other directory.
+
+> Requiring all your stories becomes bothersome real quick, so you can use this to load all stories matching a glob.
+>
+>
+> details
+>
+> ```ts
+> import { configure } from '@storybook/angular';
+>
+> function loadStories() {
+> const req = require.context('../stories', true, /\.stories\.ts$/);
+> req.keys().forEach(filename => req(filename));
+> }
+>
+> configure(loadStories, module);
+> ```
+>
+>
+
+## Step 4: Storybook TypeScript configuration
+
+`@storybook/angular` is using [ForkTsCheckerWebpackPlugin](https://github.com/Realytics/fork-ts-checker-webpack-plugin) to boost the build performance.
+This makes it necessary to create a `tsconfig.json` file at `.storybook/tsconfig.json` with the following content:
+
+```json
+{
+ "extends": "../tsconfig.json",
+ "exclude": [
+ "../src/test.ts",
+ "../src/**/*.spec.ts",
+ "../projects/**/*.spec.ts"
+ ],
+ "include": [
+ "../src/**/*",
+ "../projects/**/*"
+ ]
+}
+```
+
+## Step 5: Write your stories
+
+Now create a `../stories/index.js` file, and write your first story like this:
+
+```ts
+import { storiesOf } from '@storybook/angular';
+import { Button } from '@storybook/angular/demo';
+
+storiesOf('My Button', module)
+ .add('with emoji', () => ({
+ component: Button,
+ props: {
+ text: '😀 😎 👍 💯',
+ },
+ }))
+ .add('with emoji', () => ({
+ component: Button,
+ props: {
+ text: '😀 😎 👍 💯',
+ },
+ }));
+```
+
+Each story is a single state of your component. In the above case, there are two stories for the demo button component:
+
+```plaintext
+Button
+ ├── with text
+ └── with emoji
+```
+
+## Finally: Run your Storybook
+
+Now everything is ready. Run your storybook with:
+
+```sh
+npm run storybook
+```
+
+Storybook should start, on a random open port in dev-mode.
+
+Now you can develop your components and write stories and see the changes in Storybook immediately since it uses Webpack's hot module reloading.
diff --git a/docs/src/pages/basics/guide-ember/index.md b/docs/src/pages/guides/guide-ember/index.md
similarity index 100%
rename from docs/src/pages/basics/guide-ember/index.md
rename to docs/src/pages/guides/guide-ember/index.md
diff --git a/docs/src/pages/guides/guide-html/index.md b/docs/src/pages/guides/guide-html/index.md
new file mode 100644
index 000000000000..8db981a626d8
--- /dev/null
+++ b/docs/src/pages/guides/guide-html/index.md
@@ -0,0 +1,128 @@
+---
+id: 'guide-html'
+title: 'Storybook for HTML'
+---
+
+## Automatic setup
+
+You may have tried to use our quick start guide to setup your project for Storybook.
+If it failed because it couldn't detect you're using html, you could try forcing it to use html:
+
+```sh
+npx -p @storybook/cli sb init --type html
+```
+
+## Manual setup
+
+If you want to set up Storybook manually for your html project, this is the guide for you.
+
+## Step 1: Add dependencies
+
+### Init npm if necessary
+
+If you don't have `package.json` in your project, you'll need to init it first:
+
+```sh
+npm init
+```
+
+### Add @storybook/html
+
+Add `@storybook/html` to your project. To do that, run:
+
+```sh
+npm install @storybook/html --save-dev
+```
+
+### Add @babel/core and babel-loader
+
+Make sure that you have `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peer dependencies:
+
+```sh
+npm install babel-loader @babel/core --save-dev
+```
+
+## Step 2: Add a npm script
+
+Then add the following NPM script to your `package.json` in order to start the storybook later in this guide:
+
+```json
+{
+ "scripts": {
+ "storybook": "start-storybook"
+ }
+}
+```
+
+## Step 3: Create the config file
+
+For a basic Storybook configuration, the only thing you need to do is tell Storybook where to find stories.
+
+To do that, create a file at `.storybook/config.js` with the following content:
+
+```js
+import { configure } from '@storybook/html';
+
+function loadStories() {
+ require('../stories/index.js');
+ // You can require as many stories as you need.
+}
+
+configure(loadStories, module);
+```
+
+That'll load stories in `../stories/index.js`. You can choose where to place stories, you can co-locate them with source files, or place them in an other directory.
+
+> Requiring all your stories becomes bothersome real quick, so you can use this to load all stories matching a glob.
+>
+>
+> details
+>
+> ```js
+> import { configure } from '@storybook/html';
+>
+> function loadStories() {
+> const req = require.context('../stories', true, /\.stories\.js$/);
+> req.keys().forEach(filename => req(filename));
+> }
+>
+> configure(loadStories, module);
+> ```
+>
+>
+
+## Step 4: Write your stories
+
+Now create a `../stories/index.js` file, and write your first story like this:
+
+```js
+import { storiesOf } from '@storybook/html';
+
+storiesOf('Button', module)
+ .add('with text', () => '')
+ .add('with emoji', () => {
+ const button = document.createElement('button');
+ button.innerText = '😀 😎 👍 💯';
+ return button;
+ });
+```
+
+Each story is a single state of your component. In the above case, there are two stories for the demo button component:
+
+```plaintext
+Button
+ ├── with text
+ └── with emoji
+```
+
+## Finally: Run your Storybook
+
+Now everything is ready. Run your storybook with:
+
+```sh
+npm run storybook
+```
+
+Storybook should start, on a random open port in dev-mode.
+
+Now you can develop your components and write stories and see the changes in Storybook immediately since it uses Webpack's hot module reloading.
diff --git a/docs/src/pages/guides/guide-marko/index.md b/docs/src/pages/guides/guide-marko/index.md
new file mode 100644
index 000000000000..943efbb55295
--- /dev/null
+++ b/docs/src/pages/guides/guide-marko/index.md
@@ -0,0 +1,120 @@
+---
+id: 'guide-marko'
+title: 'Storybook for Marko'
+---
+
+## Automatic setup
+
+You may have tried to use our quick start guide to setup your project for Storybook.
+If it failed because it couldn't detect you're using marko, you could try forcing it to use marko:
+
+```sh
+npx -p @storybook/cli sb init --type marko
+```
+
+## Manual setup
+
+If you want to set up Storybook manually for your marko project, this is the guide for you.
+
+## Step 1: Add dependencies
+
+### Add @storybook/marko
+
+Add `@storybook/marko` to your project. To do that, run:
+
+```sh
+npm install @storybook/marko --save-dev
+```
+
+### Add marko, @babel/core and babel-loader
+
+Make sure that you have `marko`, `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peer dependencies:
+
+```sh
+npm install babel-loader @babel/core --save-dev
+```
+
+## Step 2: Add a npm script
+
+Then add the following NPM script to your `package.json` in order to start the storybook later in this guide:
+
+```json
+{
+ "scripts": {
+ "storybook": "start-storybook"
+ }
+}
+```
+
+## Step 3: Create the config file
+
+For a basic Storybook configuration, the only thing you need to do is tell Storybook where to find stories.
+
+To do that, create a file at `.storybook/config.js` with the following content:
+
+```js
+import { configure } from '@storybook/marko';
+
+function loadStories() {
+ require('../stories/index.js');
+ // You can require as many stories as you need.
+}
+
+configure(loadStories, module);
+```
+
+That'll load stories in `../stories/index.js`. You can choose where to place stories, you can co-locate them with source files, or place them in an other directory.
+
+> Requiring all your stories becomes bothersome real quick, so you can use this to load all stories matching a glob.
+>
+>
+> details
+>
+> ```js
+> import { configure } from '@storybook/marko';
+>
+> function loadStories() {
+> const req = require.context('../stories', true, /\.stories\.js$/);
+> req.keys().forEach(filename => req(filename));
+> }
+>
+> configure(loadStories, module);
+> ```
+>
+>
+
+## Step 4: Write your stories
+
+Now create a `../stories/index.js` file, and write your first story like this:
+
+```js
+/** @jsx m */
+
+import m from 'marko';
+import { storiesOf } from '@storybook/marko';
+import Button from '../components/button/index.marko';
+
+storiesOf('Button', module)
+ .add('with text', () => Button.renderSync({ text: 'some text'}))
+ .add('with emoji', () => Button.renderSync({ text: '😀 😎 👍 💯'}));
+```
+
+Each story is a single state of your component. In the above case, there are two stories for the demo button component:
+
+```plaintext
+Button
+ ├── with text
+ └── with emoji
+```
+
+## Finally: Run your Storybook
+
+Now everything is ready. Run your storybook with:
+
+```sh
+npm run storybook
+```
+
+Storybook should start, on a random open port in dev-mode.
+
+Now you can develop your components and write stories and see the changes in Storybook immediately since it uses Webpack's hot module reloading.
diff --git a/docs/src/pages/guides/guide-mithril/index.md b/docs/src/pages/guides/guide-mithril/index.md
new file mode 100644
index 000000000000..5cd447794e1b
--- /dev/null
+++ b/docs/src/pages/guides/guide-mithril/index.md
@@ -0,0 +1,125 @@
+---
+id: 'guide-mithril'
+title: 'Storybook for Mithril'
+---
+
+## Automatic setup
+
+You may have tried to use our quick start guide to setup your project for Storybook.
+If it failed because it couldn't detect you're using mithril, you could try forcing it to use mithril:
+
+```sh
+npx -p @storybook/cli sb init --type mithril
+```
+
+## Manual setup
+
+If you want to set up Storybook manually for your mithril project, this is the guide for you.
+
+## Step 1: Add dependencies
+
+### Add @storybook/mithril
+
+Add `@storybook/mithril` to your project. To do that, run:
+
+```sh
+npm install @storybook/mithril --save-dev
+```
+
+### Add mithril, @babel/core and babel-loader
+
+Make sure that you have `mithril`, `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peer dependencies:
+
+```sh
+npm install mithril --save
+npm install babel-loader @babel/core --save-dev
+```
+
+## Step 2: Add a npm script
+
+Then add the following NPM script to your `package.json` in order to start the storybook later in this guide:
+
+```json
+{
+ "scripts": {
+ "storybook": "start-storybook"
+ }
+}
+```
+
+## Step 3: Create the config file
+
+For a basic Storybook configuration, the only thing you need to do is tell Storybook where to find stories.
+
+To do that, create a file at `.storybook/config.js` with the following content:
+
+```js
+import { configure } from '@storybook/mithril';
+
+function loadStories() {
+ require('../stories/index.js');
+ // You can require as many stories as you need.
+}
+
+configure(loadStories, module);
+```
+
+That'll load stories in `../stories/index.js`. You can choose where to place stories, you can co-locate them with source files, or place them in an other directory.
+
+> Requiring all your stories becomes bothersome real quick, so you can use this to load all stories matching a glob.
+>
+>
+> details
+>
+> ```js
+> import { configure } from '@storybook/mithril';
+>
+> function loadStories() {
+> const req = require.context('../stories', true, /\.stories\.js$/);
+> req.keys().forEach(filename => req(filename));
+> }
+>
+> configure(loadStories, module);
+> ```
+>
+>
+
+## Step 4: Write your stories
+
+Now create a `../stories/index.js` file, and write your first story like this:
+
+```js
+/** @jsx m */
+
+import m from 'mithril';
+import { storiesOf } from '@storybook/mithril';
+import { Button } from '';
+
+storiesOf('Button', module)
+ .add('with text', () => (
+
+ ))
+ .add('with emoji', () => (
+
+ ));
+```
+
+Each story is a single state of your component. In the above case, there are two stories for the demo button component:
+
+```plaintext
+Button
+ ├── with text
+ └── with emoji
+```
+
+## Finally: Run your Storybook
+
+Now everything is ready. Run your storybook with:
+
+```sh
+npm run storybook
+```
+
+Storybook should start, on a random open port in dev-mode.
+
+Now you can develop your components and write stories and see the changes in Storybook immediately since it uses Webpack's hot module reloading.
diff --git a/docs/src/pages/guides/guide-preact/index.md b/docs/src/pages/guides/guide-preact/index.md
new file mode 100644
index 000000000000..21f33354d9fc
--- /dev/null
+++ b/docs/src/pages/guides/guide-preact/index.md
@@ -0,0 +1,123 @@
+---
+id: 'guide-preact'
+title: 'Storybook for Preact'
+---
+
+## Automatic setup
+
+You may have tried to use our quick start guide to setup your project for Storybook.
+If it failed because it couldn't detect you're using preact, you could try forcing it to use preact:
+
+```sh
+npx -p @storybook/cli sb init --type preact
+```
+
+## Manual setup
+
+If you want to set up Storybook manually for your preact project, this is the guide for you.
+
+## Step 1: Add dependencies
+
+### Add @storybook/preact
+
+Add `@storybook/preact` to your project. To do that, run:
+
+```sh
+npm install @storybook/preact --save-dev
+```
+
+### Add preact, @babel/core and babel-loader
+
+Make sure that you have `preact`, `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peer dependencies:
+
+```sh
+npm install preact --save
+npm install babel-loader @babel/core --save-dev
+```
+
+## Step 2: Add a npm script
+
+Then add the following NPM script to your `package.json` in order to start the storybook later in this guide:
+
+```json
+{
+ "scripts": {
+ "storybook": "start-storybook"
+ }
+}
+```
+
+## Step 3: Create the config file
+
+For a basic Storybook configuration, the only thing you need to do is tell Storybook where to find stories.
+
+To do that, create a file at `.storybook/config.js` with the following content:
+
+```js
+import { configure } from '@storybook/preact';
+
+function loadStories() {
+ require('../stories/index.js');
+ // You can require as many stories as you need.
+}
+
+configure(loadStories, module);
+```
+
+That'll load stories in `../stories/index.js`. You can choose where to place stories, you can co-locate them with source files, or place them in an other directory.
+
+> Requiring all your stories becomes bothersome real quick, so you can use this to load all stories matching a glob.
+>
+>
+> details
+>
+> ```js
+> import { configure } from '@storybook/preact';
+>
+> function loadStories() {
+> const req = require.context('../stories', true, /\.stories\.js$/);
+> req.keys().forEach(filename => req(filename));
+> }
+>
+> configure(loadStories, module);
+> ```
+>
+>
+
+## Step 4: Write your stories
+
+Now create a `../stories/index.js` file, and write your first story like this:
+
+```js
+import { h } from 'preact';
+import { storiesOf } from '@storybook/preact';
+import { Button } from '';
+
+storiesOf('Button', module)
+ .add('with text', () => (
+
+ ))
+ .add('with emoji', () => (
+
+ ));
+```
+
+Each story is a single state of your component. In the above case, there are two stories for the demo button component:
+
+```plaintext
+Button
+ ├── with text
+ └── with emoji
+```
+
+## Finally: Run your Storybook
+
+Now everything is ready. Run your storybook with:
+
+```sh
+npm run storybook
+```
+
+Storybook should start, on a random open port in dev-mode.
+
+Now you can develop your components and write stories and see the changes in Storybook immediately since it uses Webpack's hot module reloading.
diff --git a/docs/src/pages/basics/guide-react-native/index.md b/docs/src/pages/guides/guide-react-native/index.md
similarity index 95%
rename from docs/src/pages/basics/guide-react-native/index.md
rename to docs/src/pages/guides/guide-react-native/index.md
index f7d6adada7f9..5a1d3a55dafa 100644
--- a/docs/src/pages/basics/guide-react-native/index.md
+++ b/docs/src/pages/guides/guide-react-native/index.md
@@ -5,13 +5,14 @@ title: 'Storybook for React Native'
This guide will help you to manually setup React Native Storybook and explain about addons and Storybook server.
+## Automatic setup
-## Table of contents
+You may have tried to use our quick start guide to setup your project for Storybook.
+If it failed because it couldn't detect you're using react-native, you could try forcing it to use react-native:
-- [Manual setup](#manual-setup)
-- [Writing stories](#writing-stories)
-- [Addons](#addons)
-- [Storybook Server](#storybook-server)
+```sh
+npx -p @storybook/cli sb init --type react-native
+```
## Manual setup
diff --git a/docs/src/pages/guides/guide-react/index.md b/docs/src/pages/guides/guide-react/index.md
new file mode 100644
index 000000000000..51d47c08b797
--- /dev/null
+++ b/docs/src/pages/guides/guide-react/index.md
@@ -0,0 +1,123 @@
+---
+id: 'guide-react'
+title: 'Storybook for React'
+---
+
+## Automatic setup
+
+You may have tried to use our quick start guide to setup your project for Storybook.
+If it failed because it couldn't detect you're using react, you could try forcing it to use react:
+
+```sh
+npx -p @storybook/cli sb init --type react
+```
+
+## Manual setup
+
+If you want to set up Storybook manually for your React project, this is the guide for you.
+
+## Step 1: Add dependencies
+
+### Add @storybook/react
+
+Add `@storybook/react` to your project. To do that, run:
+
+```sh
+npm install @storybook/react --save-dev
+```
+
+### Add react, react-dom, @babel/core, and babel-loader
+
+Make sure that you have `react`, `react-dom`, `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peer dependencies:
+
+```sh
+npm install react react-dom --save
+npm install babel-loader @babel/core --save-dev
+```
+
+## Step 2: Add a npm script
+
+Then add the following NPM script to your `package.json` in order to start the storybook later in this guide:
+
+```json
+{
+ "scripts": {
+ "storybook": "start-storybook"
+ }
+}
+```
+
+## Step 3: Create the config file
+
+For a basic Storybook configuration, the only thing you need to do is tell Storybook where to find stories.
+
+To do that, create a file at `.storybook/config.js` with the following content:
+
+```js
+import { configure } from '@storybook/react';
+
+function loadStories() {
+ require('../stories/index.js');
+ // You can require as many stories as you need.
+}
+
+configure(loadStories, module);
+```
+
+That'll load stories in `../stories/index.js`. You can choose where to place stories, you can co-locate them with source files, or place them in an other directory.
+
+> Requiring all your stories becomes bothersome real quick, so you can use this to load all stories matching a glob.
+>
+>
+> details
+>
+> ```js
+> import { configure } from '@storybook/react';
+>
+> function loadStories() {
+> const req = require.context('../stories', true, /\.stories\.js$/);
+> req.keys().forEach(filename => req(filename));
+> }
+>
+> configure(loadStories, module);
+> ```
+>
+>
+
+## Step 4: Write your stories
+
+Now create a `../stories/index.js` file, and write your first story like this:
+
+```js
+import React from 'react';
+import { storiesOf } from '@storybook/react';
+import { Button } from '@storybook/react/demo';
+
+storiesOf('Button', module)
+ .add('with text', () => (
+
+ ))
+ .add('with emoji', () => (
+
+ ));
+```
+
+Each story is a single state of your component. In the above case, there are two stories for the demo button component:
+
+```plaintext
+Button
+ ├── with text
+ └── with emoji
+```
+
+## Finally: Run your Storybook
+
+Now everything is ready. Run your storybook with:
+
+```sh
+npm run storybook
+```
+
+Storybook should start, on a random open port in dev-mode.
+
+Now you can develop your components and write stories and see the changes in Storybook immediately since it uses Webpack's hot module reloading.
diff --git a/docs/src/pages/guides/guide-react/new.md b/docs/src/pages/guides/guide-react/new.md
new file mode 100644
index 000000000000..6e304e575bfd
--- /dev/null
+++ b/docs/src/pages/guides/guide-react/new.md
@@ -0,0 +1,158 @@
+
+## Automatic setup
+
+You may have tried to use our quick start guide to setup your project for Storybook.
+If it failed because it couldn't detect you're using vue, you could try forcing it to use vue:
+
+```sh
+npx -p @storybook/cli sb init --type vue
+```
+
+## Manual setup
+
+If you want to set up Storybook manually for your React project, this is the guide for you.
+
+## Step 1: Add dependencies
+
+### Add @storybook/vue
+
+Add `@storybook/vue` to your project. To do that, run:
+
+```sh
+npm install @storybook/vue --save-dev
+```
+
+### Add vue, vue-dom, @babel/core, and babel-loader
+
+Make sure that you have `vue`, `vue-loader`, `vue-template-compiler`, `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peer dependencies:
+
+```sh
+npm install vue --save
+npm install babel-loader vue-loader vue-template-compiler @babel/core --save-dev
+```
+
+## Step 2: Add a npm script
+
+Then add the following NPM script to your `package.json` in order to start the storybook later in this guide:
+
+```json
+{
+ "scripts": {
+ "storybook": "start-storybook"
+ }
+}
+```
+
+## Step 3: Create the config file
+
+For a basic Storybook configuration, the only thing you need to do is tell Storybook where to find stories.
+
+To do that, create a file at `.storybook/config.js` with the following content:
+
+```js
+import { configure } from '@storybook/vue';
+
+function loadStories() {
+ require('../stories/index.js');
+ // You can require as many stories as you need.
+}
+
+configure(loadStories, module);
+```
+
+That'll load stories in `../stories/index.js`. You can choose where to place stories, you can co-locate them with source files, or place them in an other directory.
+
+> Requiring all your stories becomes bothersome real quick, so you can use this to load all stories matching a glob.
+>
+>
+> details
+>
+> ```js
+> import { configure } from '@storybook/vue';
+>
+> function loadStories() {
+> const req = require.context('../stories', true, /\.stories\.js$/);
+> req.keys().forEach(filename => req(filename));
+> }
+>
+> configure(loadStories, module);
+> ```
+>
+>
+
+
+> You might be using global components or vue plugins such as vuex, in that case you'll need to register them in this `config.js` file.
+>
+>
+> details
+>
+> ```js
+> import { configure } from '@storybook/vue';
+>
+> import Vue from 'vue';
+>
+> // Import Vue plugins
+> import Vuex from 'vuex';
+>
+> // Import your global components.
+> import Mybutton from '../src/stories/Button.vue';
+>
+> // Install Vue plugins.
+> Vue.use(Vuex);
+>
+> // Register global components.
+> Vue.component('my-button', Mybutton);
+>
+> function loadStories() {
+> // You can require as many stories as you need.
+> require('../src/stories');
+> }
+>
+> configure(loadStories, module);
+> ```
+>
+> This example registered your custom `Button.vue` component, installed the Vuex plugin, and loaded your Storybook stories defined in `../stories/index.js`.
+>
+> All custom components and Vue plugins should be registered before calling `configure()`.
+>
+>
+
+
+## Step 4: Write your stories
+
+Now create a `../stories/index.js` file, and write your first story like this:
+
+```js
+import Vue from 'vue';
+import { storiesOf } from '@storybook/vue';
+import MyButton from './Button.vue';
+
+storiesOf('Button', module)
+ .add('with text', () => 'with text')
+ .add('with emoji', () => '😀 😎 👍 💯')
+ .add('as a component', () => ({
+ components: { MyButton },
+ template: 'rounded'
+ }));
+```
+
+Each story is a single state of your component. In the above case, there are two stories for the demo button component:
+
+```plaintext
+Button
+ ├── with text
+ ├── with emoji
+ └── as a component
+```
+
+## Finally: Run your Storybook
+
+Now everything is ready. Run your storybook with:
+
+```sh
+npm run storybook
+```
+
+Storybook should start, on a random open port in dev-mode.
+
+Now you can develop your components and write stories and see the changes in Storybook immediately since it uses Webpack's hot module reloading.
diff --git a/docs/src/pages/guides/guide-riot/index.md b/docs/src/pages/guides/guide-riot/index.md
new file mode 100644
index 000000000000..5afa2cacb2e4
--- /dev/null
+++ b/docs/src/pages/guides/guide-riot/index.md
@@ -0,0 +1,199 @@
+---
+id: 'guide-riot'
+title: 'Storybook for Riot'
+---
+
+## Automatic setup
+
+You may have tried to use our quick start guide to setup your project for Storybook.
+If it failed because it couldn't detect you're using riot, you could try forcing it to use riot:
+
+```sh
+npx -p @storybook/cli sb init --type riot
+```
+
+## Manual setup
+
+If you want to set up Storybook manually for your Angular project, this is the guide for you.
+
+## Step 1: Add dependencies
+
+### Add @storybook/riot
+
+Add `@storybook/riot` to your project. To do that, run:
+
+```sh
+npm install @storybook/riot --save-dev
+```
+
+### Add riot, @babel/core, and babel-loader
+
+Make sure that you have `riot`, `@babel/core`, and `babel-loader` in your dependencies as well because we list these as a peer dependencies:
+
+```sh
+npm install riot babel-loader @babel/core --save-dev
+```
+
+## Step 2: Add a npm script
+
+Then add the following NPM script to your `package.json` in order to start the storybook later in this guide:
+
+```json
+{
+ "scripts": {
+ "storybook": "start-storybook"
+ }
+}
+```
+
+## Step 3: Create the config file
+
+For a basic Storybook configuration, the only thing you need to do is tell Storybook where to find stories.
+
+To do that, create a file at `.storybook/config.js` with the following content:
+
+```ts
+import { configure } from '@storybook/riot';
+
+function loadStories() {
+ require('../stories/index.js');
+ // You can require as many stories as you need.
+}
+
+configure(loadStories, module);
+```
+
+That'll load stories in `../stories/index.js`. You can choose where to place stories, you can co-locate them with source files, or place them in an other directory.
+
+> Requiring all your stories becomes bothersome real quick, so you can use this to load all stories matching a glob.
+>
+>
+> details
+>
+> ```ts
+> import { configure } from '@storybook/riot';
+>
+> function loadStories() {
+> const req = require.context('../stories', true, /\.stories\.ts$/);
+> req.keys().forEach(filename => req(filename));
+> }
+>
+> configure(loadStories, module);
+> ```
+>
+>
+
+
+> Additionally this is the place where you can register global component.
+>
+>
+> details
+>
+> ```ts
+> import { configure } from '@storybook/riot';
+>
+> // Import your globally available components.
+> import '../src/stories/Button.tag';
+>
+> function loadStories() {
+> require('../stories/index.js');
+> // You can require as many stories as you need.
+}
+>
+> configure(loadStories, module);
+> ```
+>
+>
+
+## Step 4: Storybook TypeScript configuration
+
+`@storybook/riot` is using [ForkTsCheckerWebpackPlugin](https://github.com/Realytics/fork-ts-checker-webpack-plugin) to boost the build performance.
+This makes it necessary to create a `tsconfig.json` file at `.storybook/tsconfig.json` with the following content:
+
+```json
+{
+ "extends": "../tsconfig.json",
+ "exclude": [
+ "../src/test.ts",
+ "../src/**/*.spec.ts",
+ "../projects/**/*.spec.ts"
+ ],
+ "include": [
+ "../src/**/*",
+ "../projects/**/*"
+ ]
+}
+```
+
+## Step 5: Write your stories
+
+Now create a `../stories/index.js` file, and write your first story like this:
+
+```js
+import { tag, mount, storiesOf } from '@storybook/riot';
+import SimpleTestRaw from './SimpleTest.txt'; //can be loaded as string if you prefer
+import './AnotherTest.tag';
+//if you need to import .tag files as text, just use the raw-loader instead of the riot-tag-loader
+
+storiesOf('My Component', module)
+ .add(
+ 'built with tag', // the template is compiled below
+ () =>
+ tag('test', '
simple test ({ opts.value })
', '', '', () => {}) &&
+ mount('test', { value: 'with a parameter' }))
+
+ // tags[0] will be the parent tag, always
+ // you can leave out the root tag, if we find out that the new root tag
+ // is a built-in html tag, it will be wrapped
+ .add('built as string', () => ({ tags: ['