How to Configure the Storybook Docs Addon for Automatic Documentation (Autodocs)

Enable Storybook's Autodocs feature by installing @storybook/addon-docs, registering it in your .storybook/main.ts configuration, and applying the autodocs tag to your component stories either individually or globally.

The Storybook Docs addon (@storybook/addon-docs) provides a powerful Autodocs feature that automatically generates comprehensive documentation pages for your components by analyzing their stories and arguments. In the storybookjs/storybook repository, this functionality is implemented through a sophisticated MDX compilation pipeline that transforms your Component Story Format (CSF) files into interactive documentation. Configuring the Docs addon for automatic documentation requires specific setup in both your main configuration file and your component stories.

Understanding the Autodocs Architecture

The Autodocs system operates through several coordinated layers defined in the source code. According to the storybookjs/storybook repository, the architecture consists of:

• Addon Package (code/addons/docs/package.json): Implements the MDX compiler and Docs UI components
• Preset Configuration (code/addons/docs/src/preset.ts): Registers the MDX loader with Webpack or Vite and injects the documentation panel
• Tag System: Uses the autodocs tag to identify which components should receive automatic documentation pages

When Storybook initializes, the preset in code/addons/docs/src/preset.ts configures the build pipeline to handle MDX files:

{
  test: /\.mdx$/,
  use: [
    require.resolve('@storybook/addon-docs/mdx-loader'),
    // …additional loaders…
  ],
}

This loader processes the generated MDX content from your CSF files, creating documentation pages that include controls, source code viewers, and argument tables. If a component lacks the autodocs tag, Storybook skips documentation generation entirely, preventing empty pages.

Installing and Registering the Docs Addon

Before enabling Autodocs, you must install and register the addon in your Storybook configuration.

Installation

Install the package using your preferred package manager:

# Using npm

npm install -D @storybook/addon-docs

# Using Yarn

yarn add -D @storybook/addon-docs

Registration in main.ts

Register the addon in your .storybook/main.ts (or main.js) configuration file by adding it to the addons array:

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-webpack5';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    // 👇 Add the Docs addon
    '@storybook/addon-docs',
  ],
};

export default config;

Enabling Autodocs for Components

Autodocs requires the autodocs tag to be present on your stories. You can apply this tag to individual components or configure it globally.

Per-Story Configuration

Add the autodocs tag to the meta object of your CSF file to enable automatic documentation for that specific component:

// src/components/Button.stories.ts
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
  tags: ['autodocs'], // 👈 Enables Autodocs for this component
};

export default meta;

export const Primary: StoryObj<typeof Button> = {
  args: { label: 'Click me', primary: true },
};

Global Configuration

To enable Autodocs for all components by default, configure the tags parameter in your .storybook/preview.ts file:

// .storybook/preview.ts
import type { Preview } from '@storybook/react';

const preview: Preview = {
  parameters: {
    tags: ['autodocs'], // Applies to all stories
  },
};

export default preview;

Customizing Autodocs Behavior

The Docs addon provides several configuration options to tailor the automatic documentation output.

Changing the Default Page Name

By default, Autodocs pages are labeled "Documentation" in the sidebar. You can customize this using the docs.defaultName configuration in .storybook/main.ts:

// .storybook/main.ts
const config: StorybookConfig = {
  // ... other config
  addons: ['@storybook/addon-docs'],
  docs: {
    defaultName: 'API Reference', // Custom page name
  },
};

This configuration changes how the generated documentation pages appear in the navigation sidebar.

Disabling Autodocs for Specific Components

When using global tags, you may need to exclude certain components from automatic documentation. Remove the tag from specific stories:

// src/components/Internal.stories.ts
export default {
  component: InternalComponent,
  tags: [], // Empty array disables Autodocs
};

Alternatively, use the exclusion syntax (!tag) in your preview configuration to filter out specific tags:

// .storybook/preview.ts
export const parameters = {
  tags: ['autodocs', '!experimental'], // Exclude experimental stories
};

The exclusion syntax is processed by Storybook's tag system as documented in docs/writing-stories/tags.mdx.

Summary

• Install the @storybook/addon-docs package to enable the documentation infrastructure
• Register the addon in .storybook/main.ts by adding it to the addons array
• Tag stories with autodocs either individually in CSF files or globally in .storybook/preview.ts to trigger automatic documentation generation
• Customize the output using docs.defaultName in your main configuration and filter components using tag inclusions or exclusions
• The MDX compilation pipeline in code/addons/docs/src/preset.ts handles the transformation of your stories into interactive documentation pages

Frequently Asked Questions

What is the difference between addon-docs and Autodocs?

The @storybook/addon-docs package provides the underlying infrastructure for documentation in Storybook, including MDX compilation and the Docs UI components. Autodocs is a specific feature within this addon that automatically generates documentation pages from your CSF files without requiring manual MDX files. While addon-docs supports manual MDX documentation, Autodocs creates these pages automatically when the autodocs tag is present.

How do I disable Autodocs for specific components when using global tags?

Set the tags array to empty in the specific story file's meta object, or use the exclusion syntax (!autodocs) in your global configuration. For component-level control, tags: [] in the CSF meta object prevents documentation generation for that component while keeping global settings intact for others.

Does Autodocs work with all Storybook frameworks?

Yes, Autodocs works across all frameworks supported by Storybook (React, Vue, Angular, Svelte, etc.) because it operates on the framework-agnostic CSF format and the standardized args system. The MDX loader in code/addons/docs/src/preset.ts processes the compiled stories regardless of the underlying framework, though specific framework renderers may affect how props tables are generated.

Can I customize the MDX template that Autodocs uses?

While Autodocs generates MDX content automatically based on the templates in docs/writing-docs/autodocs.mdx, you can influence the output through story parameters and the Docs container components. For complete customization of the documentation layout, you may need to create manual MDX files or use the docs.page parameter to provide a custom template component that overrides the default automatic generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}