Storybook · Writing and testing · all subjects

documentation/mdx

18 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

MDX files mix Markdown and JSX for interactive documentation

MDX files combine Markdown's readable syntax (such as # heading) with Javascript/JSX to create rich interactive documentation. You can include stories defined in Component Story Format (CSF), embed JSX component blocks at any point, and write pure documentation pages in MDX to add alongside stories.

CSF and MDX division of responsibilities

CSF is great for succinctly defining stories (component examples) and provides type safety and auto-completion with TypeScript. MDX is great for writing structured documentation and composing it with interactive JSX elements. This split leverages the best qualities of each format.

MDX blocks must be separated by blank lines

The MDX document consists of blocks separated by blank lines. Since MDX mixes different languages together, blank lines help distinguish where one language block starts and the next begins. Failing to separate blocks by whitespace can cause parse errors.

Comments in MDX are JSX blocks containing JS comments

Comments in MDX files use the format {/* comment text */}, which are JSX blocks that contain JavaScript comments.

Meta Doc Block placement and customization

The Meta block defines where a document will be placed in the sidebar. By default, the docs sidebar node is titled 'Docs', but this can be customized by passing a name prop (e.g., <Meta of={CheckboxStories} name="Info" />). To place a docs node at an arbitrary point in the navigation hierarchy, use the title prop (e.g., <Meta title="path/to/node" />).

Meta block of prop must reference full story file exports

When providing the of prop to the Meta block, you must reference the full set of exports of the story file and not the component itself to prevent render issues with the generated documentation.

MDX supports standard Markdown and GitHub Flavored Markdown

MDX supports standard markdown (commonmark) by default and can be extended to support GitHub Flavored Markdown (GFM) and other extensions.

Storybook MDX implementation is React-only

While MDX supports multiple runtimes (React, Preact, Vue), Storybook's implementation is React-only. Documentation is rendered in React, while stories render in the runtime of your choice (React, Vue, Angular, Web Components, Svelte, etc.).

Unattached documentation renders as documentation-only page

When providing only the Meta Doc Block without additional props or other blocks in an MDX file, Storybook considers it as 'unattached' documentation or a 'documentation-only' page, and renders it differently in the sidebar navigation menu.

File system location inference for MDX documentation

When omitting the Meta Doc Block, Storybook will rely on the file's physical location to place the documentation in the sidebar. This overrides any pre-existent auto-generated documentation with your own. Storybook infers the title and location using the same heuristic rules to generate auto-title stories and renders it in the sidebar as a Docs entry.

Markdown Doc Block imports Markdown content

The Markdown Doc Block allows you to import Markdown content (such as CHANGELOG.md files) and render it alongside your existing documentation. It provides additional configuration options to customize the rendering of your documentation.

Linking to stories and documentation pages with query strings

You can link to stories and documentation pages using the path query string. For documentation pages, use [text](?path=/docs/some--id) where some--id is the story's unique identifier. For story canvas, use [text](?path=/story/some--id). You can also use anchors to target specific sections: (?path=/docs/some--id#section-name).

Controls do not update story with inline rendering disabled

If you turn off inline rendering for stories via the inline configuration option on the Story Doc Block, the associated controls will not update the story within the MDX documentation page. This is a known limitation of the current implementation.

Enable remark-gfm plugin for Markdown tables in MDX

To render Markdown tables and other GitHub Flavored Markdown features correctly in MDX, enable the remark-gfm plugin in your Storybook configuration file (.storybook/main.js|ts). The remark-gfm package is not included by default and must be installed separately as a development dependency.

Troubleshoot missing documentation detection

If Storybook is not able to detect and render documentation for component stories, check the configuration file (.storybook/main.js|ts) and ensure the stories configuration element provides the correct path to the stories location (e.g., ../src/**/*.stories.@(js|jsx|mjs|ts|tsx)).

React version used for addon-docs

For most projects, Storybook's addon-docs uses the React version listed in the project's dependencies. If it does not find one, it uses React 18.2.0. Exceptions: Preact projects always use React 17, and Next.js projects always use the canary version that comes with the Next.js version installed, regardless of the React version in dependencies.

MDX extension for VSCode with experimental support

When working with VSCode, you can add the MDX extension (unifiedjs.vscode-mdx) and enable MDX experimental support for linting, type checking, and auto-completion by adding {"mdx.server.enable": true} to user settings.

Troubleshoot flaky MDX migration with hipster checker

If running the migration command for MDX files seems flaky and keeps failing, run npx @hipster/mdx2-issue-checker inside the project directory to output a list of files causing issues. You may need to run the command multiple times to fix all issues, then manually fix the identified problems.

Give your agent this brain