[storybook] Storybook directive, for inline story rendering

docs/_docset.yml

@@ -41,6 +41,9 @@ subs:
 
 features:
   primary-nav: false
+
+storybook:
+  registry: https://ci-artifacts.kibana.dev/storybooks/pr-272388/storybook-docs/docs_registry.json
 
 suppress:
   - AutolinkElasticCoDocs
@@ -149,6 +152,7 @@ toc:
       - file: lists.md
       - file: task-lists.md
       - file: line_breaks.md
+      - file: storybook.md
       - file: links.md
       - file: list-sub-pages.md
       - file: page-card.md

docs/syntax/directives.md

@@ -77,7 +77,8 @@ The following directives are available:
 - [Math](math.md) - Mathematical expressions and equations
 - [Page cards](page-card.md) - Full-width clickable navigation rows
 - [Settings](automated_settings.md) - Configuration blocks
+- [Storybook](storybook.md) - Embedded Storybook stories
 - [Stepper](stepper.md) - Step-by-step content
 - [Tabs](tabs.md) - Tabbed content organization
 - [Tables](tables.md) - Data tables
-- [Version blocks](version-variables.md) - API version information
+- [Version blocks](version-variables.md) - API version information

docs/syntax/index.md

@@ -12,7 +12,7 @@ Elastic Docs V3 uses a custom implementation of [MyST](https://mystmd.org/) (Mar
 
 If you know [Markdown](https://commonmark.org), you already know most of what you need. If not, the CommonMark project offers a [10-minute tutorial](https://commonmark.org/help/). 
 
-When you need more than basic Markdown, you can use _directives_ to add features like callouts, tabs, and diagrams. To learn how directives work in general, including how to add options and arguments and nest multiple directives, refer to [How directives work](directives.md). For a full list of available directives, refer to the sidebar.
+When you need more than basic Markdown, you can use _directives_ to add features like callouts, tabs, diagrams, and embedded Storybook stories. To learn how directives work in general, including how to add options and arguments and nest multiple directives, refer to [How directives work](directives.md). For a full list of available directives, refer to the sidebar.
 
 ## GitHub Flavored Markdown support
 
@@ -25,4 +25,4 @@ V3 supports some GitHub Flavored Markdown extensions:
 **Not supported:**
 - Automatic URL linking: https://www.elastic.co
   - Links must use standard Markdown syntax: [Elastic](https://www.elastic.co)
-- Using a subset of HTML
+- Using a subset of HTML

docs/syntax/storybook.md

@@ -0,0 +1,84 @@
+# Storybook
+
+The `{storybook}` directive embeds a Storybook story from a Kibana `docs_registry.json`. The registry supplies the Storybook runtime ID, inline module entry, bootstrap assets, and iframe fallback URL.
+
+Configure the registry URL in `docset.yml`:
+
+```yaml
+storybook:
+  registry: https://example.com/storybook-docs/docs_registry.json
+```
+
+This page uses the Kibana Storybook artifact registry from PR 272388 so docs-builder preview builds can exercise inline module loading from `docs-v3-preview.elastic.dev`.
+
+For local Kibana testing, `yarn storybook_docs shared_ux --serve` serves the registry at:
+
+```text
+http://127.0.0.1:6007/storybook-docs/docs_registry.json
+```
+
+## Usage
+
+Use a registry ID directly:
+
+```markdown
+:::{storybook}
+:id: kibana:shared_ux:ai-components-aibutton--default
+:height: 300
+:title: AI button default story
+:::
+```
+
+:::{storybook}
+:id: kibana:shared_ux:ai-components-aibutton--default
+:height: 300
+:title: AI button default story
+:::
+
+Or use structured properties:
+
+```markdown
+:::{storybook}
+:project: kibana
+:storybook: shared_ux
+:component: ai-components-aibutton
+:story: default
+:::
+```
+
+:::{storybook}
+:project: kibana
+:storybook: shared_ux
+:component: ai-components-aibutton
+:story: default
+:::
+
+If a bare `:id:` is used, it must match exactly one story in the configured registry:
+
+```markdown
+:::{storybook}
+:id: ai-components-aibutton--default
+:::
+```
+
+In the PR 272388 registry this bare ID is ambiguous — it resolves to both `kibana:presentation:ai-components-aibutton--default` and `kibana:shared_ux:ai-components-aibutton--default` — so it is not rendered live here. Use the fully-qualified `project:storybook:docsId` form when a docs ID is not unique.
+
+## Properties
+
+| Property | Required | Description |
+|---|---|---|
+| `:id:` | Yes* | Full registry ID such as `kibana:shared_ux:ai-components-aibutton--default`, or a bare docs/storybook ID that matches exactly one configured story. |
+| `:project:` | Yes* | Registry project prefix, for example `kibana`. Required when `:id:` is omitted. |
+| `:storybook:` | Yes* | Storybook alias, for example `shared_ux`. Required when `:id:` is omitted. |
+| `:component:` | No | Component ID used with `:story:` to form `{component}--{story}`. |
+| `:story:` | Yes* | Story name or docs ID. Required when `:id:` is omitted. |
+| `:height:` | No | Iframe fallback height in pixels. Defaults to the registry story height when present, otherwise `400`. |
+| `:title:` | No | Accessible title for the iframe fallback. Defaults to `Storybook story`. |
+
+## Rendering
+
+If the registry story has `renderMode: inline` and an `inline` entry, docs-builder renders a `<storybook-story>` element. The browser loads the registry bootstrap styles and scripts, then imports `inline.entry` and calls `mountStory(story.storybookId, container)`.
+
+If the story has `renderMode: iframe`, or no inline entry, docs-builder renders `iframe.url`.
+
+The registry, inline module, bootstrap assets, and iframe fallback can live on different paths. docs-builder uses the URLs from the registry directly; those assets must allow browser access from the docs site.

src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs

@@ -59,6 +59,8 @@ public record ConfigurationFile
 
 	public IReadOnlyDictionary<string, IFileInfo>? OpenApiSpecifications { get; }
 
+	public string? StorybookRegistry { get; }
+
 	/// <summary>
 	/// Resolved API configurations with template and specification file information.
 	/// </summary>
@@ -245,6 +247,9 @@ public ConfigurationFile(DocumentationSetFile docSetFile, IDocumentationSetConte
 				ApiConfigurations = apiConfigs.Count > 0 ? apiConfigs : null;
 			}
 
+			if (docSetFile.Storybook is not null)
+				StorybookRegistry = docSetFile.Storybook.Registry?.Trim();
+
 			// Process products from docset - resolve ProductLinks to Product objects
 			if (docSetFile.Products.Count > 0)
 			{

src/Elastic.Documentation.Configuration/Serialization/YamlStaticContext.cs

@@ -39,6 +39,7 @@ namespace Elastic.Documentation.Configuration.Serialization;
 // Table of contents
 [YamlSerializable(typeof(DocumentationSetFile))]
 [YamlSerializable(typeof(DocumentationSetFeatures))]
+[YamlSerializable(typeof(DocumentationSetStorybook))]
 [YamlSerializable(typeof(CodexDocSetMetadata))]
 [YamlSerializable(typeof(TableOfContentsFile))]
 [YamlSerializable(typeof(SiteNavigationFile))]

src/Elastic.Documentation.Configuration/Toc/DocumentationSetFile.cs

@@ -73,6 +73,9 @@ public class DocumentationSetFile : TableOfContentsFile
 	[YamlMember(Alias = "branding")]
 	public BrandingConfiguration? Branding { get; set; }
 
+	[YamlMember(Alias = "storybook")]
+	public DocumentationSetStorybook? Storybook { get; set; }
+
 	public static FileRef[] GetFileRefs(ITableOfContentsItem item)
 	{
 		if (item is FileRef fileRef)
@@ -740,6 +743,13 @@ public class DocumentationSetFeatures
 	public bool? DisableGithubEditLink { get; set; }
 }
 
+[YamlSerializable]
+public class DocumentationSetStorybook
+{
+	[YamlMember(Alias = "registry")]
+	public string? Registry { get; set; }
+}
+
 /// <summary>
 /// Codex-specific metadata. Only contains <c>group</c> for navigation grouping in a codex environment.
 /// </summary>

src/Elastic.Documentation.Site/Assets/main.ts

@@ -41,6 +41,7 @@ import('./web-components/VersionDropdown')
 import('./web-components/AppliesToPopover')
 import('./web-components/FullPageSearch/FullPageSearchComponent')
 import('./web-components/Diagnostics/DiagnosticsComponent')
+import('./web-components/StorybookStory/StorybookStoryComponent')
 
 if (config.buildType === 'isolated' || config.airGapped) {
     import('./isolated')
@@ -134,8 +135,19 @@ document.addEventListener('htmx:load', function () {
 document.addEventListener(
     'htmx:removingHeadElement',
     function (event: HtmxEvent) {
-        const tagName = event.detail.headElement.tagName
-        if (tagName === 'STYLE') {
+        const headElement = event.detail.headElement
+        if (headElement.tagName === 'STYLE') {
+            event.preventDefault()
+            return
+        }
+        // Keep the Storybook bootstrap assets that <storybook-story> injects into
+        // <head>; htmx would otherwise strip them on navigation, which both breaks an
+        // in-flight first load (the stylesheet's onload never fires) and leaves the
+        // module-level load caches pointing at elements that no longer exist.
+        if (
+            headElement.dataset?.storybookScript !== undefined ||
+            headElement.dataset?.storybookStyle !== undefined
+        ) {
             event.preventDefault()
         }
     }

src/Elastic.Documentation.Site/Assets/markdown/storybook.css

@@ -0,0 +1,32 @@
+.storybook-embed {
+	border: 1px solid #e3e8f2;
+	border-radius: 6px;
+	margin-block: 1.5rem;
+	overflow: hidden;
+}
+
+.storybook-embed iframe {
+	display: block;
+}
+
+.storybook-embed storybook-story {
+	display: block;
+	padding: 24px;
+}
+
+.storybook-embed-body {
+	padding: 0.75rem 1.5rem;
+	border-top: 1px solid #e3e8f2;
+	background: #f7f8fc;
+}
+
+.storybook-embed-error {
+	padding: 1rem;
+	color: #bd271e;
+	font-size: 14px;
+}
+
+.storybook-embed-error strong {
+	display: block;
+	margin-bottom: 0.25rem;
+}

src/Elastic.Documentation.Site/Assets/styles.css

@@ -29,6 +29,7 @@
 @import './markdown/agent-skill.css';
 @import './markdown/cli-modifiers.css';
 @import './markdown/contributors.css';
+@import './markdown/storybook.css';
 @import './api-docs.css';
 @import 'tippy.js/dist/tippy.css';