storybook-addon-md 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # storybook-addon-md
 
+## 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

@@ -93,30 +93,63 @@ Without a title, `docs/Introduction.md` appears at `Documentation/docs/Introduct
 
 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. |
+| `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.
 
+## 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,
+      },
+    },
+  ],
+};
+```
+
+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:
@@ -141,15 +174,23 @@ See [Styling](STYLING.md) for all variables, status colors, theme switching, and
 - 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.
 
-## 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:
+
+| 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;
 }
 ```
 

package/dist/index.d.ts

@@ -1,7 +1,10 @@
+//#region src/index.d.ts
 export interface MarkdownOptions {
-    generatedDir?: string;
-    patterns: string[];
-    stylesheet?: string;
-    root?: string;
-    presentation?: string;
+  manifests?: boolean;
+  generatedDir?: string;
+  patterns: string[];
+  stylesheet?: string;
+  root?: string;
+  presentation?: string;
 }
+//#endregion

package/dist/preset.d.ts

@@ -1,22 +1,56 @@
-import type { UserConfig } from 'vite';
-import type { MarkdownOptions } from './index.js';
-import type { ContentOptions } from './content.js';
+import { MarkdownOptions } from "./index.js";
+import { StorybookConfigRaw } from "storybook/internal/types";
+import { UserConfig } from "vite";
+//#region src/content.d.ts
+interface ContentOptions extends MarkdownOptions {
+  root: string;
+  output: 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 discover({ root, patterns, output }: ContentOptions): Promise<{
+  markdown: string;
+  assets: {
+    file: string;
+    suffix: string;
+    token: string;
+  }[];
+  file: string;
+  original: string;
+  source: string;
+  title: string;
+  metadata: Frontmatter;
+  stories: string[];
+}[]>;
+//#endregion
+//#region src/preset.d.ts
 type PresetOptions = MarkdownOptions & {
-    configDir: string;
+  configDir: string;
 };
 type StoryEntry = string | {
-    directory: string;
-    files?: string;
-    titlePrefix?: string;
+  directory: string;
+  files?: string;
+  titlePrefix?: string;
 };
 export declare function stories(existing: StoryEntry[] | undefined, options: PresetOptions): Promise<StoryEntry[]>;
-export declare function watchDocumentation(config: ContentOptions, { onError, onUpdate, }?: {
-    onError?: (error: Error) => void;
-    onUpdate?: () => void;
+export declare function watchDocumentation(config: ContentOptions, { onError, onUpdate }?: {
+  onError?: (error: Error) => void;
+  onUpdate?: (documents: DiscoveredDocument[]) => void;
 }): {
-    ready: Promise<void>;
-    close(): Promise<void>;
+  ready: Promise<void>;
+  close(): Promise<void>;
 };
 export declare function viteFinal(config: UserConfig, options: PresetOptions): Promise<UserConfig>;
 export declare function webpackFinal(): void;
-export {};
+export declare const experimental_manifests: (manifests: NonNullable<StorybookConfigRaw["experimental_manifests"]> | undefined, options: Pick<PresetOptions, "configDir" | "manifests">) => Promise<({
+  components?: import("storybook/internal/types").ComponentsManifest;
+} & Record<string, unknown>) | {
+  components?: import("storybook/internal/types").ComponentsManifest;
+  docs?: Record<string, unknown> | undefined;
+}>;
+//#endregion