[storybook] PoC of Storybook directive, for inline stories

[clintandrewhall]

Summary

This PR is a proof-of-concept for embedding Kibana Storybook stories in docs-builder output, so teams can render interactive component examples directly inside product documentation.

The immediate problem we are trying to solve is that Storybook content today lives separately from our docs experience. We want a path where Kibana documentation can reference Storybook stories, have those stories render inside docs pages, and eventually support a workflow where Storybook-authored documentation can be previewed and published through the same docs system.

This implementation is intentionally early and exploratory. It was heavily AI-assisted to help move quickly on the shape of the integration, and I expect parts of the API and implementation to change based on review feedback, Kibana-side needs, and production deployment constraints.

Note

This PR was written with extensive assistance from GPT-5.4.

Approach

Rather than teaching docs-builder to understand Storybook MDX directly, this POC adds a first-class storybook directive to the markdown engine and treats that as the stable contract.

That means the current architecture is:

1. Kibana-side content can be transformed into normalized markdown.
2. docs-builder consumes that markdown via a {storybook} directive.
3. The rendered docs page embeds the Storybook iframe using a validated URL shape.

This keeps docs-builder focused on rendering and validation, while leaving repo-specific Storybook MDX interpretation to Kibana if we choose to build that transform.

What’s Included

New storybook directive

Adds support for:

:::{storybook}
:id: components-button--primary
:title: Button / Primary story
:::

or, when needed:

:::{storybook}
:root: /storybook/kibana-eui
:id: components-button--primary
:height: 320
:title: Button / Primary story
:::

The directive renders an iframe in HTML output and a structured <storybook ...> element in LLM markdown output.

Docset-level Storybook configuration

Adds storybook config in docset.yml so authors do not need to repeat the root on every story block.

Supported settings now include:

storybook:
  root: /storybook/kibana-eui
  server_root: http://localhost:6006
  allowed_roots:
    - http://localhost:6006/storybook/kibana-eui

This supports a few use cases:

• storybook.root
  • Default Storybook root for the docset
• storybook.server_root
  • Optional base server URL prepended to root-relative story roots
• storybook.allowed_roots
  • Explicit allow-list for absolute root overrides

URL generation and validation

The directive now builds the iframe URL internally as:

{root}/iframe.html?id={id}&viewMode=story

Validation ensures that:

• root-relative paths are allowed
• absolute roots must be explicitly configured
• iframe.html, query strings, and fragments are rejected in :root:
• literal / is supported as the root of the Storybook server

Documentation and testing notes

Adds and updates documentation for:

• directive syntax
• Kibana local testing
• Kibana-side MDX transform expectations

This is meant to make review easier and give the team a concrete starting point for trying the flow from Kibana.

Why this shape

The main design choice in this POC is that docs-builder understands a normalized Storybook embed contract, not Storybook MDX itself.

That gives us a cleaner separation of concerns:

• Kibana owns Storybook content, CSF metadata, package-to-root mapping, and any MDX transform
• docs-builder owns markdown parsing, validation, rendering, and docs-site output

That feels like the right boundary for now, especially since Storybook MDX resolution is repo-specific and may vary by package, build system, or authoring conventions.

Notes / Caveats

• This is not a final authoring API.
• The config shape, directive syntax, and deployment assumptions may change after feedback.
• The intended production model is that Storybook static assets are hosted on the same deployed site as the docs output, under a path like /storybook/<library>/.
• The Kibana-side MDX transform is documented, but not implemented in this PR.
• This should be read as a working integration spike, not a locked-in design.

Feedback I’m Looking For

• Is the docs-builder / Kibana responsibility split the right one?
• Is storybook.root + server_root the right docset-level model?
• Should the final authoring flow prefer normalized markdown generation, or should we consider native MDX ingestion later?
• Does the deployment model of static Storybook assets under the same site root match how we want to operate this long-term?
• Is this a good start to a formal inclusion of this functionality?

[github-actions]

🔍 Preview links for changed docs

• docs/syntax/storybook.md
• docs/syntax/directives.md
• docs/syntax/index.md