[Bug]: Markdown Headers Not Formatted - Storybook 10

[CollinHerber]

Describe the bug

Storybook 10:

Storybook 9:

Code:

import { Meta, Markdown } from "@storybook/addon-docs/blocks";

import Readme from "../../CHANGELOG.md?raw";

<Meta title="Changelogs"/>

<Markdown>{Readme}</Markdown>

Readme file:

### Consuming the nCino Web Components
nCino Web Components are Native Web Components that can be consumed in any framework, or no framework at all.

#### Global Styles
If you want to make use of the global utility styles available, import the styles for your design system.

Ex `import '@ncino/gator/styles`

#### Framework Samples
View the samples in the `./samples` directory for examples of how to consume the components for the framework of your choice.

#### Consumption Options
You can either import components individually or all components through a single file.

##### Single File
Simple import the `index.js` included in the Dist. This file includes all components.

Reproduction link

Unable to provide ATM

Reproduction steps

No response

System

Storybook Environment Info:

  System:
    OS: macOS 15.7.1
    CPU: (8) arm64 Apple M1 Pro
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 22.16.0 - ~/.local/share/nvm/v22.16.0/bin/node
    npm: 10.9.2 - ~/.local/share/nvm/v22.16.0/bin/npm
    pnpm: 10.19.0 - ~/.local/share/nvm/v22.16.0/bin/pnpm <----- active
  Browsers:
    Chrome: 141.0.7390.123
    Safari: 26.0.1
  npmPackages:
    @storybook/addon-a11y: ^10.0.1 => 10.0.1 
    @storybook/addon-designs: ^11.0.1 => 11.0.1 
    @storybook/addon-docs: ^10.0.1 => 10.0.1 
    @storybook/addon-links: ^10.0.1 => 10.0.1 
    @storybook/web-components-vite: ^10.0.1 => 10.0.1 
    chromatic: ^13.3.1 => 13.3.1 
    eslint-plugin-storybook: ^10.0.1 => 10.0.1 
    storybook: ^10.0.1 => 10.0.1 
    storybook-addon-code-editor: ^5.0.0 => 5.0.0

Additional context

No response

[dosubot]

Hi @CollinHerber! I'm Dosu and I’m helping the storybook team.

This is a known issue with Markdown rendering in Storybook 10, especially when using the <Markdown> block from @storybook/addon-docs/blocks. Storybook 10 switched to MDX 2, which introduced breaking changes in how Markdown is parsed and rendered—most notably, GitHub Flavored Markdown (GFM) features are disabled by default, and custom component overrides (like for headers) are now sandboxed differently. This can cause headers and other block elements to render incorrectly or not at all if your Markdown relies on GFM or specific overrides docs.

To fix header formatting and restore GFM features (like tables, strikethrough, etc.), install remark-gfm and add it to your Storybook config:

// .storybook/main.ts
import remarkGfm from 'remark-gfm';

const config = {
  addons: [
    {
      name: '@storybook/addon-docs',
      options: {
        mdxPluginOptions: {
          mdxCompileOptions: {
            remarkPlugins: [remarkGfm],
          },
        },
      },
    },
    // ...other addons
  ],
  // ...other config
};

export default config;

If you still see issues, make sure you are only using <Markdown> inside Docs or MDX pages, not in stories, since it requires a context provider that isn't available in stories thread. For more control, consider using custom MDX docs instead of autodocs or patching the Markdown rendering options as a workaround thread.

If you need more help, please share any browser console errors or a minimal reproduction when possible.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[ndelangen]

I investigated this, and seems like in raw from the component is working:

So I'd concluded that maybe the ?raw query parameter isn't working correctly.

So I tried it, but that also worked:

The repro I tested this on, didn't specify remarkGfm either...

So I'd request a reproduction for me to investigate @CollinHerber

[CollinHerber]

I will do some investigation based on the responses here, thanks. If I continue to have trouble I will take the time to attempt a mvp repro

[CollinHerber]

I spun up a fresh repo and used the ootb storybook config , used the same mdx file and same md file and it is working in the mvp repro.

Beyond that I have no idea what would cause it not to work in our main repo. We don't really have anything special going on there.

Here is our full main and preview file if it helps. Beyond that I can provide isolated bits of code, but not the entire repro for IP issues.

If you have any ideas on what I could test lmk.

// This file has been automatically migrated to valid ESM format by Storybook.
import { fileURLToPath } from 'node:url';
import { dirname } from 'node:path';
import type { StorybookConfig } from '@storybook/web-components-vite';
// @ts-ignore
import { getCodeEditorStaticDirs } from 'storybook-addon-code-editor/getStaticDirs';

const __filename = fileURLToPath(import.meta.url);

const config: StorybookConfig = {
    stories: [
        '../src/**/*.gator.stories.@(js|jsx|mjs|ts|tsx|mdx)',
        '../src/**/*.stories.gator.@(js|jsx|mjs|ts|tsx|mdx)',
        '../src/docs/changelogs.mdx',
        '../src/docs/in-progress.mdx',
        '../src/docs/getting-started.mdx',
        '../src/**/*.gator.mdx',
    ],
    addons: [
        getAbsolutePath('@storybook/addon-links'),
        getAbsolutePath('@storybook/addon-designs'),
        getAbsolutePath('@storybook/addon-a11y'),
        getAbsolutePath('storybook-addon-code-editor'),
        {
            name: getAbsolutePath('@storybook/addon-docs'),
            options: { framework: 'web-components' }
        },
    ],
    framework: {
        name: getAbsolutePath('@storybook/web-components-vite'),
        options: {},
    },
    staticDirs: ['../public', ...getCodeEditorStaticDirs(__filename)],
    async viteFinal(config, { configType }) {
        const { mergeConfig } = await import('vite');
        return mergeConfig(config, {
            server: {
                allowedHosts: true
            }
        });
    },
};
export default config;

function getAbsolutePath(value: string): any {
    return dirname(fileURLToPath(import.meta.resolve(`${value}/package.json`)));
}

import type { Preview, StoryContext } from '@storybook/web-components-vite';
import { convertArgsForStorybookCodeExample } from '../src/utils/storybook-utils';
import { useEffect } from 'storybook/preview-api';
import { configureLocalization } from '@lit/localize';
// @ts-ignore
import { sourceLocale, targetLocales } from '../src/generated/locale-codes.ts';
import '@ncino/styles/gator';
import '../src/index.gator';
import '../src/utils/components/slot-placeholder';
import { getBrandColor, setBrandColor } from '../src/utils/brand-color-utils.ts';

const preview: Preview = {
    argTypes: {
        dataTestid: {
            name: 'data-testid',
            control: { type: 'text' },
            description: '`data-testid` to be applied to the component, and relevant child components. This is required for consumers in order to leverage the nCino Test Automation Framework. Please refer to the [current Gold Standard](https://ncinodev.atlassian.net/wiki/spaces/ARCH/pages/3321823253/SGC+Data+attribute+for+UI+testing+ADOPTED) for guidance on how to use this attribute.',
            table: {
                category: 'Testing',
                type: { summary:'string' },
                defaultValue: { summary: 'undefined' },
            }
        },
    },
    parameters: {
        controls: {
            expanded: true,
            matchers: {
                color: /(background|color)$/i,
                date: /Date$/i,
            },
        },
        designToken: {
            disable: false,
            defaultTab: 'Colors',
            showSearch: true,
        },
        docs: {
            source:  {
                transform: (code: string, story: StoryContext) => {
                    return convertArgsForStorybookCodeExample(code, story.component as string, story.args);
                }
            }
        },
        options: {
            storySort: {
                order: [
                    'Getting Started',
                    'Changelogs',
                    'Playground',
                    'Components',
                    'Composites',
                    'Styles',
                    'Utilities',
                    'In Progress',
                    ['In Progress']
                ],
            },
        }
    },
};

export const globalTypes = {
    locale: {
        name: 'Locale',
        description: 'Internationalization locale',
        toolbar: {
            icon: 'globe',
            items: [
                { value: 'en', title: 'English | en' },
                { value: 'es-419', title: 'Español | es-419 (Latin America)' },
                { value: 'zh-Hans', title: 'Chinese | zh-Hans (Simplified)' },
                { value: 'fr-CA', title: 'French | fr-CA (Canada)' },
            ],
            showName: true,
        },
    },
    brandColor: {
        name: 'Brand Color',
        description: 'Preview components with different brand colors',
        defaultValue: '#103656',
        toolbar: {
            icon: 'paintbrush',
            dynamicTitle: true,
            value: getBrandColor(),
            items: [
                { value: '#103656', right: 'Default brand', title: '#103656' },
                { value: '#17A7DA', right: 'nCino banker blue', title: '#17A7DA' },
                { value: '#5CB54D', right: 'nCino gator green', title: '#5CB54D' },
                { value: '#FABA00', right: 'nCino oak gold', title: '#FABA00' },
                { value: '#CD1012', right: 'nCino acorn red', title: '#CD1012' },
            ],
        },
    }
};

export default preview;

const { getLocale, setLocale } = configureLocalization({
    sourceLocale,
    targetLocales,
    loadLocale: (locale) => import(`../src/generated/locales/${locale}.ts`),
});

export const decorators = [
    (Story, context) => {
        const { globals } = context;
        let locale = globals.locale;
        let brandColor = globals.brandColor;

        if (!locale) {
            locale = 'en';
        }

        useEffect(() => {
            console.warn(`Locale changed to: ${locale}`);
            setLocale(locale);
            setBrandColor(brandColor);
        }, [locale, brandColor]);

        return Story();
    },
];

[CollinHerber]

Here is the repro repo I used https://github.com/CollinHerber/storybook-10-md-repro

[yannbf]

Thanks for sharing that @CollinHerber! I have two questions:

1. Does the repro you linked us to actually show the problem? It seems you mentioned you couldn't reproduce. If you can't reproduce the issue, it's really hard for us to help unfortunately.
2. The link goes to a 404 page. Is the repo private? If so, can you make it public?

One thing you can try is to clear your lockfile and rerun yarn/npm install. It could be a hoisting issue.