[Bug]: @fluentui/react-storybook-addon has no support for raw/unattached MDX docs pages (no TOC / docs chrome)

[Hotell]

Area

storybook

Environment

System:
  OS: macOS 15.7.7
Binaries:
  Node: 22.21.1
npmPackages:
  @fluentui/react-storybook-addon: 0.6.0
  storybook: 9.1.19
  @storybook/addon-docs: 9.1.19

Current Behavior

@fluentui/react-storybook-addon provides its branded docs chrome — the sticky "On this page" TOC, the theme picker, the LTR/RTL switch, and the Copy Page button — only for story-based docs pages (CSF autodocs), because that chrome lives in FluentDocsPage, which the addon registers as the global docs.page.

Raw / unattached MDX documentation pages (<Meta title="…" /> with no of= / no story) are not supported: they render their own MDX content and never go through FluentDocsPage, so they get none of the Fluent chrome — in particular no table of contents.

Storybook's own native parameters.docs.toc doesn't fill the gap either:

• On story pages, FluentDocsPage renders its custom Toc and ignores parameters.docs.toc.
• On raw MDX pages, the default DocsPage/DocsPageWrapper (which renders the native toc sidebar) is bypassed, so setting docs.toc (per‑<Meta> or globally) emits no TOC element at all (verified in the DOM).

So today there is no first-class way to give a long-form MDX documentation page the same "On this page" navigation (and other Fluent docs chrome) that story pages get.

Current workaround (imperfect): explicitly render the exported <TableOfContents> block inside the MDX:

import { Meta, TableOfContents } from '@storybook/addon-docs/blocks';

<Meta title="Docs/My Page" />

<TableOfContents headingSelector="h2, h3" title="On this page" contentsSelector=".sbdocs-content" />

It lists the headings, but because it's injected into the content flow (not a dedicated TOC column), tocbot positions it inline / at a wrong fixed offset instead of the sticky right-hand sidebar, so it doesn't match the addon's own TOC without extra custom CSS. It also doesn't bring the theme/dir/copy chrome.

Expected Behavior

@fluentui/react-storybook-addon should support raw/unattached MDX docs pages — rendering the same Fluent docs chrome for them as for story pages, most importantly a sticky "On this page" TOC generated from the MDX headings (and ideally the theme picker / LTR-RTL switch / Copy Page toggles), so MDX and story docs pages are visually and functionally consistent.

Acceptable shapes for a fix (any one):

• FluentDocsContainer renders the Fluent TOC/chrome for unattached MDX pages (deriving the TOC from the rendered headings), or
• the addon exports a documented block/helper (e.g. a Fluent <TableOfContents> / page wrapper) that MDX authors can drop in to get the branded sticky TOC and chrome, or
• FluentDocsPage/container honors parameters.docs.toc so the native TOC renders in the same sidebar slot.

Reproduction

Real-world example (Storybook 9 docsite that consumes the addon): microsoft/fluentui-system-icons#1138 — the standalone MDX pages under packages/docsite/stories/Icons/*.mdx cannot get a TOC / the Fluent docs chrome.

Minimal repro in any Storybook 9 project using @fluentui/react-storybook-addon:

1. Add the addon (its preset sets docs.container = FluentDocsContainer and docs.page = FluentDocsPage).
2. Add a raw/unattached MDX page (<Meta title="Docs/Repro" />) with several ##/### sections.
3. Open the page — there is no "On this page" TOC and none of the Fluent docs chrome (theme/dir/copy). Enabling parameters.docs.toc (per‑<Meta> or globally) changes nothing.

Steps to reproduce

1. In a Storybook 9 project, install and register @fluentui/react-storybook-addon.
2. Create a raw/unattached MDX page (<Meta title="Docs/Repro" />) with multiple ##/### headings.
3. Open the docs page and inspect the DOM.
4. Observe there is no .toc-wrapper / "On this page" element and no Fluent docs chrome — raw MDX pages are unsupported.

Suggested severity

Low - Has or doesn't need a workaround

Products/sites affected

Storybook docsites consuming @fluentui/react-storybook-addon that include long-form MDX documentation pages (e.g. the https://github.com/microsoft/fluentui-system-icons docsite).

Are you willing to submit a PR to fix?

no

Validations

• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• The provided reproduction is a minimal reproducible example of the bug.

[sohamsshah]

Hi Martin,
I would like to work on this one.
Can I be assigned this issue?