[Bug]: Page id does not work on mdx files

[sandrina-p]

Describe the bug

Stories can have custom URL based on the id, and it works in CSF format (eg *.stories.tsx file), but it does not work in *.mdx files:

<Meta title="Example/Button/Guidelines" id="button-guidelines" />

Can you fix it pls? 🙇

Reproduction link

https://stackblitz.com/edit/github-wmqb1cu2?file=src%2Fstories%2FButton.guidelines.mdx,src%2Fstories%2FButton.stories.ts,package.json&preset=node

Reproduction steps

1. Open the storybook
2. Go to Button > Guidelines

Expected URL:

• ?path=/docs/button-guidelines--docs

Current URL:

• ?path=/docs/example-button-guidelines--docs

System

Latest version, react with vite

Additional context

No response

[dosubot]

Hi @sandrina-p! I'm Dosu and I’m helping the storybook team.

This is a confirmed gap — the id prop on <Meta> is not extracted for unattached MDX files. The MDX analyzer (@storybook/docs-mdx) only pulls out title, name, of, tags, and a few other properties, but not id [1]. So the docs entry ID always falls back to toId(title, name) [2], which is why you get example-button-guidelines--docs instead of button-guidelines--docs.

In CSF files, meta.id is extracted and used as metaId in the ID generation [3], but that path doesn't exist for standalone MDX.

A previous discussion also reported this same limitation [4].

Workaround: If you can attach the MDX to a CSF file using <Meta of={ButtonStories} />, the docs page will inherit the CSF file's meta.id, giving you a stable custom URL. For fully standalone MDX, there's currently no way to set a custom id.

To properly fix this, the analyze() function in @storybook/docs-mdx would need to extract the id prop from <Meta>, and the indexer would need to use it — something like const id = result.id ?? toId(title, name). There's an open PR to inline the @storybook/docs-mdx analyzer into core, which would make adding this support easier.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[sandrina-p]

The workaround worked! I've updated the demo above, the "Header" story to:

<Meta of={HeaderStories} name="guidelines" />

URL: ?path=/docs/header--guidelines

[sandrina-p]

Ah but wait. I have mdx files without an associated CSF file... so this bug still happens and there's no workaround. Not even the name prop sets a defined URL. For example:

<Meta title="Foundations/Accessibility/1. Overview" id="accessibility-overview" />

[dosubot]

Right — for fully standalone MDX files (no associated CSF file), there's currently no way to set a custom id for the URL. Neither id nor name on <Meta> will affect the generated URL; it always derives from the title [1].

One possible workaround for your case: you could create a minimal "dummy" CSF file with just the meta export that sets the id, and then attach your MDX to it:

// Accessibility.overview.stories.ts
export default {
  title: 'Foundations/Accessibility/1. Overview',
  id: 'accessibility-overview',
  tags: ['autodocs'],
};

import * as OverviewStories from './Accessibility.overview.stories';

<Meta of={OverviewStories} name="Overview" />

It's not ideal since it requires creating an otherwise empty CSF file, but it would give you a stable custom URL until proper id support is added for unattached MDX.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.