A next-generation tool to create blazing-fast documentation sites

MDX Stories


You can create interactive component examples (aka stories) similar to ESM in MDX
To do so, you need to import some components from '@component-controls/blocks' and use them inside your MDX files


The MDX format has the following advantages:
  • You have full control over your documentation, testing, and design pages.
  • You can include custom markdown documentation text.
The MDX format has the following disadvantages:
  • Documentation pages are not automatically created.
  • IDE code-completion and linting support will be sub-par for now.

File extensions

The MDX story files need to have an .mdx file extension and they should contain at least one Story componnet (if not, they are treated as regular MDX documentation pages);


title: First Story
import { Button } from '../components/Button';
import { Playground, Story, PropsTable, ComponentSource, StorySource } from '@component-controls/blocks';
# My first doc story
<ComponentSource of={Button} title="Component source" />
<Playground description="Button story">
<Story name="simple">
click me
<StorySource id="." />
<PropsTable of={Button} />

External stories

You can import ESM stories into your MDX documentation. Usually, this is to use the benefits of writing your stories in .tsx/.jsx files with full code completion support from your code editor.
Our instrumenting module will take care to show the actual story source imported, not the code in the MDX file doing the importing.
title: External Story
import { Playground, Story } from '@component-controls/blocks';
import { customStory } from '../../stories/src/stories/external/external-story-props';
<Playground description="story from external file with props">
<Story name='mdx-external-story' controls={{ text: 'hello' }} >
{props => customStory(props)}
In the example below, click on open source to view the imported story source.


Below is a list of the most commonly used components (aka blocks) when writing MDX stories:



Component to display a live playground of component examples. Has custom actions for zooming, switching direction, reviewing story source, and configuration.


Block component to render story function with decorators.


Displays the configuration object of a story.


Displays the source code of a story. If controls are used, all story arguments will be highlighted. Additional commands are made available if the repository data of the story is available.


Displays a subtitle as assigned to the story.subtitle field


Displays the component's properties as well as configurable controls to interact with the component.


Displays import statement for a component as well as the component file source code Optionally also displays some repository information from the component's package.json


Description component with markdown. The 'of' property can specify which component's description to display.


Displays external dependencies for a component


Displays multiple stories in their own Playground components.


Displays a row of tags assigned to the current document, with links to their pages

Story templates

Using story templates you can reduce the amount of repetitive code in your MDX stories documentation. This is usually needed when you want to create separate stories for the various state values of your components.
In MDX files, you can bind stories to a template, and this syntax is compatible with Storybook 6
title: "MDX/Template bind"
component: Button
import { Playground, Story } from '@component-controls/blocks';
import { Button } from '../../../stories/src/components/Button';
export const Template = props => (
<Button {...props}>Button</Button>
<Story name='tom' controls={{
name: 'tom',
<Story name='harry' controls={{
name: 'harry',