storybook-addon-md 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # storybook-addon-md
 
+## 0.4.0
+
+### Minor Changes
+
+- df081eb: Respect `docs.defaultName`, use leading H1s as standalone titles, and add `tagFields` and the `storybook-addon-md/node` parsing API. Markdown pages retain props, examples, and original manifest source.
+
+  Migration: update attached links from `--markdown` to `--docs` (or the configured name), enable Autodocs in preview-level tags, and render the supplied `heading` in custom layouts. MCP component IDs are unchanged.
+
+## 0.3.0
+
+### Minor Changes
+
+- 209fe53: Add opt-in documentation manifests with original Markdown, frontmatter summaries, and live updates for standalone and attached docs. Enable `manifests: true` to use [Storybook 10.6.0 manifests](https://storybook.js.org/docs/ai/manifests) and [@storybook/addon-mcp](https://storybook.js.org/docs/ai/mcp/overview) without a custom preset.
+
+  See the [setup guide](https://github.com/ruijdacd/storybook-addon-md#documentation-manifests-and-mcp) and [examples with and without MCP](https://github.com/ruijdacd/storybook-addon-md#examples-and-contributing).
+
+### Patch Changes
+
+- a94853e: Use rem values for default Markdown styles so they scale with the root font size. Add `--sbmd-monospace-font-family` to customize inline code and code blocks, with Storybook’s monospace theme font as the default. See the [CSS variable reference](https://github.com/ruijdacd/storybook-addon-md/blob/main/STYLING.md).
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -61,7 +61,19 @@ Use buttons to trigger actions.
 - Confirm a choice.
 ```
 
-The component gets a **Markdown** Docs entry with the content, status and tag chips, examples, and props. Existing stories and Autodocs remain available.
+The component gets one **Docs** entry with Markdown, status and tag chips, examples, and automatic props. The name follows Storybook's `docs.defaultName`, falling back to `Docs`.
+
+Enable Autodocs at project level in `.storybook/preview.ts`:
+
+```ts
+export default {
+  tags: ['autodocs'],
+};
+```
+
+Storybook 10.6.0 replaces project-level Autodocs with the attached Markdown page. Components without Markdown keep ordinary Autodocs. Use `tags: ['!autodocs']` on components that should not have automatic docs. Component-only or story-only `autodocs` tags conflict with attached MDX in this Storybook version; move the enabling tag to the preview. Native props and examples on Markdown pages do not require an `autodocs` tag.
+
+Authored MDX keeps its title and explicit `name`. Additional attached MDX pages can use a distinct name such as `<Meta of={ButtonStories} name="Design notes" />`. An authored page using the default docs name for the same component conflicts with the addon page: keep the authored page and exclude that component's Markdown from `patterns` (or remove its association). The addon does not overwrite authored pages.
 
 The sibling convention supports `.stories.tsx`, `.stories.ts`, `.stories.jsx`, and `.stories.js`. To associate a different file, or share a document across components, set `stories` relative to the Markdown file:
 
@@ -89,34 +101,118 @@ Write ordinary Markdown here.
 
 Without a title, `docs/Introduction.md` appears at `Documentation/docs/Introduction`.
 
+A leading Markdown H1 supplies the visible title, including inline formatting. Otherwise the final segment of `title` is shown. Both `# Heading` and Setext H1 syntax work; a later H1 is ordinary content. Sidebar placement and IDs always use the configured or inferred sidebar title. The original file and manifest content remain unchanged.
+
 ### Frontmatter
 
 YAML frontmatter is optional. Use lowercase field names.
 
-| Field        | Meaning                                            |
-| ------------ | -------------------------------------------------- |
-| `title`      | Sidebar location for standalone pages.             |
-| `stories`    | Relative story-file path or array of paths.        |
-| `tags`       | Array of labels rendered as chips below the title. |
-| `status`     | A chip with its value preserved in `data-status`.  |
-| Other fields | Preserved as metadata for custom presentation.     |
+| Field         | Meaning                                             |
+| ------------- | --------------------------------------------------- |
+| `title`       | Sidebar location for standalone pages.              |
+| `stories`     | Relative story-file path or array of paths.         |
+| `tags`        | Array of labels rendered as chips below the title.  |
+| `description` | Optional string summary in documentation manifests. |
+| `status`      | A chip with its value preserved in `data-status`.   |
+| Other fields  | Preserved as metadata for custom presentation.      |
 
 Invalid frontmatter, missing or ambiguous story references, and missing local assets produce source-specific errors.
 
 ## Configuration
 
-| Option         | Default                        | Purpose                                                       |
-| -------------- | ------------------------------ | ------------------------------------------------------------- |
-| `patterns`     | Required                       | Markdown globs; prefix with `!` to exclude files.             |
-| `root`         | `..`                           | Project folder, resolved from the Storybook config directory. |
-| `generatedDir` | `storybook-markdown-generated` | Disposable output folder under the working directory.         |
-| `stylesheet`   | None                           | Custom stylesheet path.                                       |
-| `presentation` | None                           | Module exporting `Layout` and/or `MarkdownRenderer`.          |
+| Option         | Default                        | Purpose                                                         |
+| -------------- | ------------------------------ | --------------------------------------------------------------- |
+| `patterns`     | Required                       | Markdown globs; prefix with `!` to exclude files.               |
+| `root`         | `..`                           | Project folder, resolved from the Storybook config directory.   |
+| `generatedDir` | `storybook-markdown-generated` | Disposable output folder under the working directory.           |
+| `stylesheet`   | None                           | Custom stylesheet path.                                         |
+| `manifests`    | `false`                        | Include original Markdown in Storybook documentation manifests. |
+| `tagFields`    | `[]`                           | Additional frontmatter fields displayed as tags.                |
+| `presentation` | None                           | Module exporting `Layout` and/or `MarkdownRenderer`.            |
 
 Globs and customization paths start from your project folder (the parent of `.storybook` by default). Keep the config and local files inside that folder. Restart Storybook after changing options.
 
 `generatedDir` must be a visible folder name using letters, digits, hyphens, or underscores. Hidden folders, nested paths, `node_modules`, and `storybook-static` are unsupported. Ignore the folder in Git; the addon manages its contents.
 
+### Docs names and metadata tags
+
+```ts
+const config: StorybookConfig = {
+  framework: '@storybook/react-vite',
+  docs: { defaultName: 'Reference' },
+  stories: ['../src/**/*.stories.@(ts|tsx|js|jsx)', '../docs/**/*.mdx'],
+  addons: [
+    '@storybook/addon-docs',
+    {
+      name: 'storybook-addon-md',
+      options: {
+        patterns: ['src/**/*.md', 'docs/**/*.md'],
+        tagFields: ['category', 'subcategory'],
+      },
+    },
+  ],
+};
+```
+
+`tagFields` adds string values and string array items from those fields to the existing tags. Missing fields, blank strings, and non-string values are ignored. Labels are deduplicated by exact value across documents, tags, configured fields, and status; status takes precedence and retains its original `data-status`. Metadata is not modified. Consumers can remove adapters that only copied these fields into `tags`.
+
+### Node parsing and CI checks
+
+Use the Node-only `storybook-addon-md/node` export. It shares discovery's parser and story resolution without loading Storybook or browser code:
+
+```ts
+import { readMarkdown, parseMarkdown, resolveStoryAssociations } from 'storybook-addon-md/node';
+
+const root = process.cwd();
+const document = await readMarkdown('src/Button.metadata.md', root);
+
+if (!document.body.includes('## When to use')) {
+  throw new Error(`${document.file}: missing When to use section`);
+}
+
+const parsed = parseMarkdown('---\ntags: [Actions]\n---\n## Overview', 'virtual.md');
+const stories = await resolveStoryAssociations(document.file, document.metadata, root);
+```
+
+`readMarkdown(file, root)` accepts a root-relative or absolute `.md` path and returns `{ file, original, body, metadata, stories }`. `file` and resolved `stories` are absolute paths. `original` is the complete unchanged source; `body` excludes frontmatter and normalizes BOM/CRLF just as discovery does.
+
+`parseMarkdown(text, source)` returns `{ body, metadata }` and validates YAML, lowercase keys, title, tags, status, and story-reference value shapes. `source` labels errors. `resolveStoryAssociations(file, metadata, root)` takes parsed metadata and absolute paths, checks relative references, the four supported story extensions, file existence and root boundaries, and missing or ambiguous `.metadata.md` siblings. Explicit references take precedence. These functions throw source-specific errors; consumers can add their own template checks using `body` and metadata.
+
+This is not a separate validation framework. These functions do not check local assets, duplicate sidebar titles, or whether stories match the consuming Storybook's globs; discovery/build still performs the relevant integration checks. Filesystem dependencies are confined to Node entry points, never the runtime export.
+
+## Documentation manifests and MCP
+
+Manifest support is opt-in. Set `manifests: true` in this addon's options and enable Storybook's `features.componentsManifest`:
+
+```ts
+const config: StorybookConfig = {
+  framework: '@storybook/react-vite',
+  features: { componentsManifest: true },
+  stories: ['../src/**/*.stories.@(ts|tsx|js|jsx)'],
+  addons: [
+    '@storybook/addon-docs',
+    '@storybook/addon-mcp',
+    {
+      name: 'storybook-addon-md',
+      options: {
+        patterns: ['src/**/*.md', 'docs/**/*.md'],
+        manifests: true,
+      },
+    },
+  ],
+};
+```
+
+Use MCP's `docs-list` to find IDs, then `docs-show` with a component ID (for attached guidance) or standalone documentation ID.
+
+For MCP access, install `@storybook/addon-mcp@10.6.0` and connect your MCP client to `http://localhost:6006/mcp`. Its Get Documentation tool is named `docs-show` in 10.6.0. Omit that addon if you only need JSON manifests. It is not a dependency of `storybook-addon-md`.
+
+With Storybook and React Vite **10.6.0**, standalone Markdown appears in `/manifests/docs.json`, and attached Markdown appears in the component's `docs` in `/manifests/components.json`. Both development and static builds include the complete original source, including frontmatter. Development updates use the existing file watcher. Shared documents appear under each associated component; multiple documents on one page are joined in discovery order with two newlines. String `description` values supply optional summaries.
+
+Keep this addon after `@storybook/addon-docs`. Consumers can remove custom manifest presets that supplied Markdown content after enabling this option. Unrelated MDX, Autodocs, and other manifest fields are preserved. Storybook's manifest tag filtering still applies.
+
+This integration uses Storybook 10.6.0's experimental preset hook and inline (v0) manifests. Other Storybook versions and `features.experimentalDocgenServer` service-backed manifests are unsupported. Markdown links and assets remain as authored in manifest content. See [Storybook manifests](https://storybook.js.org/docs/ai/manifests) for the upstream feature.
+
 ## Styling
 
 Set `stylesheet: '.storybook/markdown.css'` to override the defaults:
@@ -139,17 +235,25 @@ See [Styling](STYLING.md) for all variables, status colors, theme switching, and
 - Links to `.md` files open the original source, not a rendered Docs page. Use a Storybook URL such as `/?path=/docs/guides-introduction--docs` for page navigation.
 - Braces and JSX-like text are treated as content. Raw HTML renders as text by default.
 - Set Storybook’s `parameters.options.storySort` for explicit sidebar ordering. See the [example preview](https://github.com/ruijdacd/storybook-addon-md/blob/main/example/.storybook/preview.ts).
-- The attached Docs entry name **Markdown** is reserved. Multiple development Storybooks sharing one config directory are unsupported.
+- Multiple development Storybooks sharing one config directory are unsupported.
 
-## Example and contributing
+## Examples and contributing
 
-Run the included Storybook with **Nub 0.7.5** and **Node 24**:
+Install dependencies with **Nub 0.7.5** and **Node 24.11+**:
 
 ```sh
 nub install
-nub run storybook
 ```
 
+Choose either example. They share stories, Markdown, and styling, with separate Storybook configurations. The MCP example sets `docs.defaultName: 'Reference'` to exercise custom docs names:
+
+| Example     | Configuration                         | Run                            | Build                         |
+| ----------- | ------------------------------------- | ------------------------------ | ----------------------------- |
+| Without MCP | [Default](example/.storybook/main.ts) | `nub run storybook` (6006)     | `nub run build-storybook`     |
+| With MCP    | [MCP](example/.storybook-mcp/main.ts) | `nub run storybook:mcp` (6007) | `nub run build-storybook:mcp` |
+
+The MCP example enables `manifests: true` and `@storybook/addon-mcp`. Connect your MCP client to `http://localhost:6007/mcp`. Static builds write to `storybook-static/` and `storybook-static-mcp/`, respectively. MCP is a development dependency for the example only; normal addon usage does not require it.
+
 Browse **Guides → Introduction**, **Components → Button**, and **Components → Toggle** for standalone, attached, and shared docs with system light/dark styling.
 
 See [Contributing](CONTRIBUTING.md) for tests and releases, or [open an issue](https://github.com/ruijdacd/storybook-addon-md/issues).

package/STYLING.md

@@ -4,105 +4,109 @@ Set these variables on `.storybook-addon-md-page` in the file configured by `sty
 
 ```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;
+  --sbmd-font-size: 1rem;
+  --sbmd-monospace-font-family: 'JetBrains Mono', monospace;
+  --sbmd-h2-size: 1.625rem;
+  --sbmd-paragraph-spacing: 1.25rem;
+  --sbmd-quote-border: 0.1875rem solid currentColor;
+  --sbmd-quote-radius: 0.5rem;
+  --sbmd-table-cell-padding: 0.75rem 1rem;
+  --sbmd-tag-radius: 0.375rem;
 }
 ```
 
+Default lengths use `rem`, preserving their original sizes at a 16px root font size and scaling with the document root font size. Set `--sbmd-monospace-font-family` to customize inline code and fenced code blocks; it defaults to Storybook’s monospace theme font.
+
 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`                 |
+| 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-monospace-font-family`    | `font-family` (Markdown code) |
+| `--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.
+These styles target Markdown content and its title/chips. Story canvases, props controls, and syntax-highlighting colors 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.
 
 ## Customization
 
@@ -114,11 +118,12 @@ Set `stylesheet: '.storybook/markdown.css'` in the addon options, then define yo
 
 ```css
 .storybook-addon-md-page {
-  --sbmd-font-size: 16px;
+  --sbmd-font-size: 1rem;
+  --sbmd-monospace-font-family: 'JetBrains Mono', monospace;
   --sbmd-line-height: 1.8;
   --sbmd-heading-color: currentColor;
-  --sbmd-tag-radius: 6px;
-  --sbmd-tag-border: 1px solid currentColor;
+  --sbmd-tag-radius: 0.375rem;
+  --sbmd-tag-border: 0.0625rem solid currentColor;
 }
 ```
 
@@ -136,7 +141,7 @@ Status chips share the tag variables. Use `data-status` to map values to your th
 .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;
+  --sbmd-tag-border: 0.0625rem solid currentColor;
 }
 ```
 
@@ -173,9 +178,9 @@ export function MarkdownRenderer(document: MarkdownDocument) {
 }
 ```
 
-`MarkdownRenderer` receives `{ markdown, metadata, source }`: processed Markdown with resolved asset URLs, preserved frontmatter, and the source path relative to the project folder.
+`MarkdownRenderer` receives `{ markdown, metadata, source, heading? }`: processed Markdown with resolved asset URLs, preserved frontmatter, and the source path relative to the project folder.
 
-`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.
+`Layout` receives `{ documents, title, attached, children, examples, heading, tagFields }`. A standalone leading H1 is extracted in the default pipeline and supplied as the rendered `heading` node; render it instead of your fallback title. The remaining Markdown is supplied through `children`, while source files and manifests stay intact. `tagFields` lists configured metadata fields for tag display. 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.
 
 Customization paths are relative to the project folder and must stay inside it. Missing files produce source-specific errors. Styling and presentation are independent options.
 

package/dist/content-CKQsa_HK.d.ts

@@ -0,0 +1,44 @@
+import { t as MarkdownOptions } from "./index-BzM0tjFM.js";
+//#region src/content.d.ts
+interface ContentOptions extends MarkdownOptions {
+  root: string;
+  output: string;
+  docsName?: string;
+}
+interface Frontmatter extends Record<string, unknown> {
+  title?: string;
+  stories?: string | string[];
+  tags?: string[];
+  status?: string;
+}
+type DiscoveredDocument = Awaited<ReturnType<typeof discover>>[number];
+declare function parseMarkdown(text: string, source: string): {
+  body: string;
+  metadata: Frontmatter;
+};
+declare function resolveStoryAssociations(file: string, metadata: Frontmatter, root: string): Promise<string[]>;
+declare function discover({ root, patterns, output }: ContentOptions): Promise<{
+  markdown: string;
+  assets: {
+    file: string;
+    suffix: string;
+    token: string;
+  }[];
+  heading: string | undefined;
+  file: string;
+  original: string;
+  body: string;
+  source: string;
+  title: string;
+  metadata: Frontmatter;
+  stories: string[];
+}[]>;
+declare function readMarkdown(file: string, root: string): Promise<{
+  file: string;
+  original: string;
+  body: string;
+  metadata: Frontmatter;
+  stories: string[];
+}>;
+//#endregion
+export { readMarkdown as a, parseMarkdown as i, DiscoveredDocument as n, resolveStoryAssociations as o, Frontmatter as r, ContentOptions as t };