Use Storybook docs with Svelte

Question

It seems like the only proper way to write custom docs content for the Storybook Docs addon is through MDX, implying that it was meant primarily for React. The addon page explicitly lists Svelte as a compatible framework, but no deployment instructions seem to be around.

Suppose I have a simple component: button.svelte:

<script>
  export let text;
</script>

<button on:click>{text}</button>

And the respective story, button.stories.js:

import Button from './button.svelte';

export default {
  title: 'Button',
};

export const button = () => ({
  Component: Button,
  props: {
    text: 'press me!',
  },
});

How would I go about adding arbitrary markdown documentation with Storybook Docs?

Answer 1

First, make sure your Storybook Docs addon is set up to parse MDX by installing all required dependencies.

yarn add -D react react-is babel-loader

Then you can write your MDX docs in a separate file with an .mdx extension, embedding your stories instead of writing them out explicitly.

Create a ./docs.mdx file in the same directory as button.stories.js with your desired documentation:

import { Story, Preview } from '@storybook/addon-docs/blocks';

# Button

One can write __proper Markdown__ here, as well as embed stories:

<!-- the IDs can be retrieved from the URL when opening a story -->
<Preview>
  <Story id="button--button" />
  <Story id="button--other" />
</Preview>

<!-- or an individual story -->
<Story id="button--flat" />

Then, modify your button.stories.js as follows:

import Button from './button.svelte';
import docs from './docs.mdx';  // add this import

export default {
  title: 'Button',
  parameters: {  // and this parameters section
    docs: {
      page: docs,
    },
  },
};

export const button = () => ({
  Component: Button,
  props: {
    text: 'press me!',
  },
});

// Another story just for demonstration
export const other = () => ({
  Component: Button,
  props: {
    text: 'me too!',
  },
});