storybook-addon-md 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# storybook-addon-md
+
+## 0.1.0
+
+Initial release.
+
+- Discover ordinary Markdown through configurable include and exclude patterns.
+- Render standalone pages or attach shared documentation to component stories.
+- Support frontmatter, sibling-story associations, and status and tag chips.
+- Bundle relative assets and update documentation during development.
+- Customize Markdown rendering, layouts, stylesheets, and CSS variables.
+- Include a GitHub-inspired example with system light and dark themes.
+
+Tested with Storybook 10.6.0, React 19.2.4, and Vite 7.3.6.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rui Duarte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+# Storybook Markdown
+
+A Storybook addon for **ordinary Markdown documentation**. Write `.md` files beside your components or in a docs folder, and browse them inside Storybook.
+
+- **Automatic discovery.** Configure file patterns once. Additions, edits, and deletions update during development.
+- **Component and standalone docs.** Attach guidance to existing stories, share it across components, or publish a page on its own.
+- **Native Docs.** Keep Storybook’s examples, generated props, and documentation styling.
+- **Your theme.** Customize content through CSS variables, a stylesheet, or your own layout and Markdown renderer.
+- **Static builds.** Relative images and downloads are bundled with your documentation.
+
+Write `Button.metadata.md` beside `Button.stories.tsx`:
+
+```md
+---
+status: Stable
+tags: [Actions]
+---
+
+## Overview
+
+Use buttons to trigger actions.
+
+## When to use
+
+- Submit a form.
+- Confirm a choice.
+```
+
+The component gets a **Markdown** Docs entry with your guidance, status and tag chips, examples, and props. Authors manage Markdown files; the addon manages disposable MDX wrappers.
+
+## Table of Contents
+
+- [Install](#install)
+- [Guide](#guide)
+- [Configuration](#configuration)
+- [Styling](#styling)
+- [Example](#example)
+- [Development](#development)
+- [Releasing](#releasing)
+- [Limitations](#limitations)
+
+## Install
+
+The tested setup is **Storybook 10.6.0**, **@storybook/react-vite 10.6.0**, **@storybook/addon-docs 10.6.0**, **Vite 7.3.6**, and **React 19.2.4**. Node 22.13+ is required; local verification uses Node 24.21.0 and CI uses Node 24 on Linux.
+
+This repository uses [Nub](https://nubjs.com/docs) 0.7.5. The checked-in `nub.lock` pins dependencies, and `.npmrc` selects the hoisted layout for Storybook and Vitest. `nub.jsonc` keeps scripts on standard Node without Nub runtime hooks. CI installs with `nub install --frozen-lockfile`.
+
+To build an installable tarball from this repository:
+
+```sh
+nub install
+nub pack
+```
+
+Install it in your Storybook project:
+
+```sh
+nub add -D /path/to/storybook-addon-md-0.1.0.tgz @storybook/addon-docs@10.6.0
+```
+
+The package ships compiled JavaScript and TypeScript declarations. Consumers do not need to compile the addon.
+
+Register it after addon-docs in `.storybook/main.ts`:
+
+```ts
+import type { StorybookConfig } from '@storybook/react-vite';
+import type { MarkdownOptions } from 'storybook-addon-md';
+
+const config: StorybookConfig = {
+  framework: '@storybook/react-vite',
+  stories: ['../src/**/*.stories.@(ts|tsx|js|jsx)'],
+  addons: [
+    '@storybook/addon-docs',
+    {
+      name: 'storybook-addon-md',
+      options: {
+        patterns: ['src/**/*.md', 'docs/**/*.md'],
+        exclude: ['docs/private/**'],
+      } satisfies MarkdownOptions,
+    },
+  ],
+};
+
+export default config;
+```
+
+Keep your normal story patterns: referenced story files must match them. Markdown files belong in the addon’s `patterns`, not Storybook’s `stories` list.
+
+Add `storybook-markdown-generated/` to `.gitignore`.
+
+## Guide
+
+### Standalone Pages
+
+A plain `docs/Introduction.md` appears at `Documentation/docs/Introduction`. No frontmatter, component, or story file is required.
+
+Use `title` to choose its sidebar location:
+
+```md
+---
+title: Guides/Introduction
+---
+
+## Getting started
+
+Write ordinary Markdown here.
+```
+
+### Component Documentation
+
+Name a document `Button.metadata.md` beside `Button.stories.tsx` to associate it automatically. The convention also checks `.stories.ts`, `.stories.jsx`, and `.stories.js`. Missing or ambiguous siblings produce an error.
+
+For a different location or filename, set `stories` relative to the Markdown file:
+
+```yaml
+stories: ../components/Button.stories.tsx
+```
+
+An explicit `stories` field takes precedence over the filename convention. Existing stories and Autodocs pages remain available. Each component’s **Markdown** entry combines its attached documents in source-path order, followed by its primary example, controls/props, and remaining examples.
+
+### Shared Documentation
+
+Use an array to attach one document to several story files:
+
+```yaml
+stories:
+  - ../components/Button.stories.tsx
+  - ../components/Toggle.stories.tsx
+```
+
+Each referenced component displays the shared content alongside its own documentation and examples.
+
+### Frontmatter
+
+Frontmatter is optional YAML with lowercase top-level keys.
+
+| Field        | Value                                     | Behavior                                                                              |
+| ------------ | ----------------------------------------- | ------------------------------------------------------------------------------------- |
+| `title`      | Non-empty string                          | Sidebar location for a standalone page. Does not relocate attached docs.              |
+| `stories`    | Relative path or non-empty array of paths | Associates the document with story files.                                             |
+| `tags`       | Array of non-empty strings                | Renders chips below the title. These are content labels, not Storybook indexing tags. |
+| `status`     | Non-empty string                          | Renders a chip after the tags, preserving the value in `data-status`.                 |
+| Other fields | YAML values                               | Preserved as metadata for custom layouts and renderers.                               |
+
+Shared pages deduplicate tags and statuses separately in document order. A tag and status with the same label remain separate chips. Fields such as `component` and `category` have no built-in meaning.
+
+Invalid frontmatter, duplicate standalone sidebar titles, and missing references produce errors with source paths. Development errors appear in the terminal and Vite overlay or Storybook error view, then recover when corrected.
+
+### Links and Assets
+
+Use Markdown links and images, including reference-style syntax:
+
+```md
+![Button states](./assets/button-states.svg)
+
+[Download the checklist](./checklist.pdf)
+```
+
+Local paths resolve from the source `.md` file. URL-encoded filenames and fragments are supported. Files are validated and bundled as hashed assets in static builds. Filenames containing URL-reserved characters use safe disposable copies in the generated folder.
+
+**Links to `.md` files open their original source**, including frontmatter. They do not navigate to the rendered Storybook page or recursively bundle the linked document’s assets. For page navigation, use a Storybook URL such as `/?path=/docs/guides-introduction--docs`, adjusted for your deployment prefix.
+
+External, fragment-only, query-only, and root-relative URLs are unchanged. Supply root-relative assets through Storybook’s `staticDirs`. Source files and local references must stay inside `root`; referenced files become part of the static build.
+
+## Configuration
+
+| Option         | Default                        | Description                                                              |
+| -------------- | ------------------------------ | ------------------------------------------------------------------------ |
+| `patterns`     | Required                       | Array of Markdown globs relative to `root`. Supports negative globs.     |
+| `exclude`      | `[]`                           | Excluded globs relative to `root`. Exclusions take precedence.           |
+| `root`         | `..`                           | Content root relative to the Storybook config directory.                 |
+| `generatedDir` | `storybook-markdown-generated` | Visible folder name under the working directory.                         |
+| `stylesheet`   | None                           | CSS file relative to `root`, loaded for documentation pages.             |
+| `presentation` | None                           | Module relative to `root`, exporting `Layout` and/or `MarkdownRenderer`. |
+
+Keep the Storybook config directory inside `root`. Restart Storybook after changing addon options.
+
+### Generated Files
+
+The addon creates a disposable subdirectory per configuration, registers its MDX glob before indexing, and removes obsolete files. Ignore your configured `generatedDir` in Git and leave its contents to the addon.
+
+The folder must be a visible name containing letters, digits, hyphens, or underscores. Leading-dot paths and `node_modules` interfere with Storybook 10.6’s watcher; nested paths and `storybook-static` are also rejected.
+
+### Sidebar Order
+
+Generated filenames are opaque identifiers. Set Storybook’s `parameters.options.storySort` when sidebar order matters. The [example preview] puts Guides first and sorts component titles alphabetically.
+
+## Styling
+
+The default presentation uses native Storybook Docs blocks and one shared stylesheet. Existing `parameters.docs.container` and `parameters.docs.theme` still apply.
+
+### CSS Variables
+
+Set `stylesheet: '.storybook/markdown.css'` in the addon options, then define your overrides:
+
+```css
+.storybook-addon-md-page {
+  --sbmd-font-size: 16px;
+  --sbmd-line-height: 1.8;
+  --sbmd-heading-color: currentColor;
+  --sbmd-tag-radius: 6px;
+  --sbmd-tag-border: 1px solid currentColor;
+}
+```
+
+Variables cover typography, spacing, links, code, tables, images, and chips. They inherit from your theme container, and default text and link colors follow the active Docs theme. See the [CSS variable reference](STYLING.md) for the complete list.
+
+Use ordinary CSS for other properties. `.storybook-addon-md` wraps Markdown content, including custom renderer output; titles, props, and examples sit outside it. Other stable selectors are `.storybook-addon-md-page`, `.storybook-addon-md-title`, `.storybook-addon-md-tags`, and `.storybook-addon-md-tag`.
+
+The stylesheet is global to the preview, so scope selectors and account for Storybook’s specificity. For example, use `.sbdocs-content .storybook-addon-md h2` when overriding its heading rules. Vite handles CSS edits, imports, and relative `url()` assets.
+
+### Status Chips
+
+Status chips share the tag variables. Use `data-status` to map values to your theme:
+
+```css
+.storybook-addon-md-tag[data-status='stable' i] {
+  --sbmd-tag-color: light-dark(#1a7f37, #3fb950);
+  --sbmd-tag-background: light-dark(#dafbe1, #12261e);
+  --sbmd-tag-border: 1px solid currentColor;
+}
+```
+
+The `i` flag matches both `Stable` and `stable`. The addon accepts any status; your stylesheet decides its colors. Set `color-scheme: light dark` on the theme container when using `light-dark()`.
+
+### Light and Dark Themes
+
+Use Storybook’s standard Docs theme configuration for a fixed theme:
+
+```ts
+import { themes } from 'storybook/theming';
+
+export default {
+  parameters: { docs: { theme: themes.dark } },
+};
+```
+
+For live system-preference switching, follow the example’s [Docs container] and [manager configuration]. They subscribe to preference changes so Storybook’s interface and documentation update together without reloading.
+
+### Custom Layouts and Renderers
+
+Set `presentation: '.storybook/markdown-presentation.tsx'` and export either or both components:
+
+```tsx
+import { DefaultLayout, DefaultMarkdownRenderer } from 'storybook-addon-md/runtime';
+import type { LayoutProps, MarkdownDocument } from 'storybook-addon-md/runtime';
+
+export function Layout(props: LayoutProps) {
+  return <DefaultLayout {...props} />;
+}
+
+export function MarkdownRenderer(document: MarkdownDocument) {
+  return <DefaultMarkdownRenderer {...document} />;
+}
+```
+
+`MarkdownRenderer` receives `{ markdown, metadata, source }`: processed Markdown with resolved asset URLs, preserved frontmatter, and the source path relative to `root`.
+
+`Layout` receives `{ documents, title, attached, children, examples }`. Render `children` and `examples` to keep documentation and native example/props blocks. `examples` is `null` for standalone pages. `title` contains the standalone sidebar title and is empty for attached pages; `DefaultLayout` uses Storybook’s `Title` block for those.
+
+Both customization files must stay inside `root`. Missing files produce source-specific errors. Styling and presentation are independent options.
+
+## Example
+
+Run the included Storybook:
+
+```sh
+nub install
+nub run storybook
+```
+
+Open **Guides → Introduction**, **Components → Button**, or **Components → Toggle** for standalone, attached, and shared documentation.
+
+The theme takes its direction from [GitHub Primer]. [Markdown styles] reference [Tailwind theme variables] for shared colors, typography, spacing, and radii. The example uses Tailwind v4, `clsx`, and `class-variance-authority`; these are development dependencies, not addon requirements. Tailwind Preflight is omitted to preserve native Docs styles.
+
+Components use `light-dark()` and `color-scheme: light dark` on `:root`. The manager and Docs container also follow system-preference changes live.
+
+## Development
+
+Install Chromium for the browser suites:
+
+```sh
+nub exec playwright install chromium
+```
+
+| Command                   | Purpose                                                       |
+| ------------------------- | ------------------------------------------------------------- |
+| `nub run build`           | Compile the addon and its declarations.                       |
+| `nub run check`           | Build the addon, then type-check source, examples, and tests. |
+| `nub run lint`            | Run Oxlint. Use `lint:fix` for automatic fixes.               |
+| `nub run format:check`    | Check Oxfmt formatting. Use `format` to write changes.        |
+| `nub run test`            | Run Vitest unit tests.                                        |
+| `nub run test:browser`    | Run Vitest Browser Mode with Playwright/Chromium.             |
+| `nub run test:e2e`        | Verify development and static Storybooks in Chromium.         |
+| `nub run test:package`    | Install and verify a packed addon in an isolated consumer.    |
+| `nub run build-storybook` | Build the example as a static site.                           |
+| `nub pack`                | Build and package the addon.                                  |
+
+Use `test:watch` or `test:browser:watch` while developing. End-to-end tests use ports 16006/16007, and the package smoke check uses 16008. Browser screenshots and failure traces go to `test-results/`.
+
+[CI] runs the checks on Node 24 and Linux, including a dependency audit. Tests cover discovery, associations, watcher recovery, assets, customization, keyboard interaction, and live theme switching. The package smoke check supplies its own image fixture.
+
+Content parsing lives in `src/content.ts`, disposable generation in `src/generator.ts`, Storybook integration in `src/preset.ts`, and presentation in `src/runtime.tsx`. The addon uses Storybook’s MDX compilation and indexing; it does not install a custom indexer.
+
+Report reproducible bugs in the [issue tracker].
+
+## Releasing
+
+Releases use [Changesets](https://changesets.dev/guide/automating). For a user-facing change, run `nub run changeset`, choose a patch/minor/major bump, and include the generated release note in your PR. Tooling-only changes do not need a release note.
+
+After CI passes for a push to `main`, `release.yml` opens or updates a release PR with the version and changelog. Merge that PR to publish after CI passes again. Nub manages dependencies and scripts; Changesets invokes npm for publishing.
+
+One-time setup:
+
+1. If the package does not exist on npm yet, publish the initial version from a clean checkout: `nub run build`, `npm login`, then `npm publish --access public`.
+2. In the npm package’s **Settings → Trusted publishing**, select GitHub Actions, owner `ruijdacd`, repository `storybook-addon-md`, workflow `release.yml`, and allow publishing. Leave the environment empty.
+3. In GitHub’s **Settings → Actions → General**, enable **Allow GitHub Actions to create and approve pull requests**.
+
+No `NPM_TOKEN` secret is needed. The workflow uses GitHub’s automatic token for release PRs and OIDC for [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/). It installs npm 11 with Node 24 to support OIDC.
+
+Release PRs created with the automatic GitHub token do not trigger PR workflows. If branch protection requires those checks, close and reopen the release PR yourself to trigger CI before merging. The release workflow always waits for CI on the merged commit.
+
+## Limitations
+
+- Only the Storybook, React, and Vite setup listed under [Install](#install) has been tested. Other renderers and builders are unsupported.
+- Markdown supports tables, lists, fenced code, and reference links. Braces and JSX-like text are content, never evaluated. The default renderer displays raw HTML as text; use Markdown syntax for links and images.
+- The **Markdown** page name is reserved under attached components. Avoid giving a hand-written MDX page the same name there.
+- The watcher observes `root` and rescans matching Markdown when documentation or its dependencies change. Interactive story state may reset. Keep `root` focused on your project.
+- Large monorepos, simultaneous Storybooks sharing one config directory, symlinked content directories, and MDX authoring are outside the initial scope.
+
+[example preview]: https://github.com/ruijdacd/storybook-addon-md/blob/main/example/.storybook/preview.ts
+[Docs container]: https://github.com/ruijdacd/storybook-addon-md/blob/main/example/.storybook/SystemDocsContainer.tsx
+[manager configuration]: https://github.com/ruijdacd/storybook-addon-md/blob/main/example/.storybook/manager.ts
+[GitHub Primer]: https://primer.style/product/
+[Markdown styles]: https://github.com/ruijdacd/storybook-addon-md/blob/main/example/.storybook/markdown.css
+[Tailwind theme variables]: https://github.com/ruijdacd/storybook-addon-md/blob/main/example/.storybook/tailwind.css
+[CI]: https://github.com/ruijdacd/storybook-addon-md/actions/workflows/ci.yml
+[issue tracker]: https://github.com/ruijdacd/storybook-addon-md/issues

package/STYLING.md

@@ -0,0 +1,105 @@
+# CSS variable reference
+
+Set these variables on `.storybook-addon-md-page` in the file configured by `stylesheet`. All are optional. The shared addon stylesheet supplies defaults, with text, links, borders, and inline-code backgrounds taken from the active Storybook Docs theme.
+
+```css
+.storybook-addon-md-page {
+  --sbmd-font-size: 16px;
+  --sbmd-h2-size: 26px;
+  --sbmd-paragraph-spacing: 20px;
+  --sbmd-quote-border: 3px solid currentColor;
+  --sbmd-quote-radius: 8px;
+  --sbmd-table-cell-padding: 12px 16px;
+  --sbmd-tag-radius: 6px;
+}
+```
+
+Variables accept normal CSS values for the property listed below, including `clamp()`, `calc()`, and references to your own theme variables. Border variables accept full border shorthands. Heading margins set space above the heading; title margin sets space below it. Paragraph spacing also applies to lists. Tag margin sets space below the chip list.
+
+Use your theme selector to override colors in dark mode. The [complete example](https://github.com/ruijdacd/storybook-addon-md/blob/main/example/.storybook/markdown.css) maps the addon variables to Tailwind v4 theme variables. Its `light-dark()` colors follow the system preference.
+
+| Variable                          | CSS property                |
+| --------------------------------- | --------------------------- |
+| `--sbmd-background`               | `background`                |
+| `--sbmd-checkbox-color`           | `accent-color`              |
+| `--sbmd-checkbox-gap`             | `margin-inline-end`         |
+| `--sbmd-code-border`              | `border`                    |
+| `--sbmd-code-padding`             | `padding`                   |
+| `--sbmd-code-radius`              | `border-radius`             |
+| `--sbmd-color`                    | `color`                     |
+| `--sbmd-font-family`              | `font-family`               |
+| `--sbmd-font-size`                | `font-size`                 |
+| `--sbmd-h1-size`                  | `font-size`                 |
+| `--sbmd-h2-border`                | `border-bottom`             |
+| `--sbmd-h2-letter-spacing`        | `letter-spacing`            |
+| `--sbmd-h2-margin`                | `margin-top`                |
+| `--sbmd-h2-padding`               | `padding-bottom`            |
+| `--sbmd-h2-size`                  | `font-size`                 |
+| `--sbmd-h3-letter-spacing`        | `letter-spacing`            |
+| `--sbmd-h3-margin`                | `margin-top`                |
+| `--sbmd-h3-size`                  | `font-size`                 |
+| `--sbmd-h4-size`                  | `font-size`                 |
+| `--sbmd-h5-size`                  | `font-size`                 |
+| `--sbmd-h6-size`                  | `font-size`                 |
+| `--sbmd-heading-color`            | `color`                     |
+| `--sbmd-heading-font-family`      | `font-family`               |
+| `--sbmd-heading-line-height`      | `line-height`               |
+| `--sbmd-heading-weight`           | `font-weight`               |
+| `--sbmd-image-border`             | `border`                    |
+| `--sbmd-image-margin`             | `margin-block`              |
+| `--sbmd-image-radius`             | `border-radius`             |
+| `--sbmd-inline-code-background`   | `background`                |
+| `--sbmd-inline-code-border`       | `border`                    |
+| `--sbmd-inline-code-color`        | `color`                     |
+| `--sbmd-inline-code-padding`      | `padding`                   |
+| `--sbmd-inline-code-radius`       | `border-radius`             |
+| `--sbmd-inline-code-size`         | `font-size`                 |
+| `--sbmd-line-height`              | `line-height`               |
+| `--sbmd-link-color`               | `color`                     |
+| `--sbmd-link-decoration`          | `text-decoration`           |
+| `--sbmd-link-focus-offset`        | `outline-offset`            |
+| `--sbmd-link-focus-outline`       | `outline`                   |
+| `--sbmd-link-hover-thickness`     | `text-decoration-thickness` |
+| `--sbmd-link-radius`              | `border-radius`             |
+| `--sbmd-link-thickness`           | `text-decoration-thickness` |
+| `--sbmd-link-underline-offset`    | `text-underline-offset`     |
+| `--sbmd-list-item-spacing`        | `margin-top`                |
+| `--sbmd-list-marker-color`        | `color`                     |
+| `--sbmd-max-width`                | `max-width`                 |
+| `--sbmd-page-border`              | `border`                    |
+| `--sbmd-page-padding`             | `padding`                   |
+| `--sbmd-page-radius`              | `border-radius`             |
+| `--sbmd-paragraph-spacing`        | `margin-block`              |
+| `--sbmd-quote-background`         | `background`                |
+| `--sbmd-quote-border`             | `border-inline-start`       |
+| `--sbmd-quote-margin`             | `margin`                    |
+| `--sbmd-quote-padding`            | `padding`                   |
+| `--sbmd-quote-radius`             | `border-radius`             |
+| `--sbmd-rule-color`               | `background`                |
+| `--sbmd-rule-height`              | `height`                    |
+| `--sbmd-rule-margin`              | `margin-block`              |
+| `--sbmd-table-align`              | `text-align`                |
+| `--sbmd-table-background`         | `background`                |
+| `--sbmd-table-border`             | `border`                    |
+| `--sbmd-table-cell-padding`       | `padding`                   |
+| `--sbmd-table-heading-background` | `background`                |
+| `--sbmd-table-heading-weight`     | `font-weight`               |
+| `--sbmd-table-margin`             | `margin-block`              |
+| `--sbmd-table-stripe-background`  | `background`                |
+| `--sbmd-tag-background`           | `background`                |
+| `--sbmd-tag-border`               | `border`                    |
+| `--sbmd-tag-color`                | `color`                     |
+| `--sbmd-tag-font-size`            | `font-size`                 |
+| `--sbmd-tag-font-weight`          | `font-weight`               |
+| `--sbmd-tag-gap`                  | `gap`                       |
+| `--sbmd-tag-line-height`          | `line-height`               |
+| `--sbmd-tag-padding`              | `padding`                   |
+| `--sbmd-tag-radius`               | `border-radius`             |
+| `--sbmd-title-letter-spacing`     | `letter-spacing`            |
+| `--sbmd-title-line-height`        | `line-height`               |
+| `--sbmd-title-margin`             | `margin-bottom`             |
+| `--sbmd-title-size`               | `font-size`                 |
+
+Status chips have `data-status` set to the original frontmatter value. Override `--sbmd-tag-*` on selectors such as `.storybook-addon-md-tag[data-status="stable" i]` to assign a status-specific appearance.
+
+These styles target Markdown content and its title/chips. Story canvases, props controls, and syntax highlighting still use Storybook’s theme. Custom renderers can use the shared styles when they produce matching HTML elements; custom layouts own any additional structure. Internal `--sbmd-native-*` variables carry Storybook theme values and are not customization hooks.

package/dist/content.d.ts

@@ -0,0 +1,40 @@
+import type { MarkdownOptions } from './index.js';
+export interface ContentOptions extends MarkdownOptions {
+    root: string;
+    output: string;
+}
+export interface Frontmatter extends Record<string, unknown> {
+    title?: string;
+    stories?: string | string[];
+    tags?: string[];
+    status?: string;
+}
+export type DiscoveredDocument = Awaited<ReturnType<typeof discover>>[number];
+export declare const slash: (value: string) => string;
+export declare const fail: (source: string, message: string) => Error;
+export declare function localFile(file: string, root: string, source: string, kind: string): Promise<string>;
+export declare function parseMarkdown(text: string, source: string): {
+    body: string;
+    metadata: Frontmatter;
+};
+export declare function resolveAssets(body: string, file: string, root: string): Promise<{
+    markdown: string;
+    assets: {
+        file: string;
+        suffix: string;
+        token: string;
+    }[];
+}>;
+export declare function discover({ root, patterns, exclude, output }: ContentOptions): Promise<{
+    markdown: string;
+    assets: {
+        file: string;
+        suffix: string;
+        token: string;
+    }[];
+    file: string;
+    source: string;
+    title: string;
+    metadata: Frontmatter;
+    stories: string[];
+}[]>;