storybook-addon-md 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,10 +1,18 @@
 # storybook-addon-md
 
+## 0.5.0
+
+### Minor Changes
+
+- 76c1a71: Render GitHub-style alerts (`> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]`) as labelled callouts in Docs. Ordinary blockquotes and unrecognized markers are unchanged, Markdown and relative assets inside callouts keep working, and manifests keep the original source.
+
+  Style callouts with the new `--sbmd-callout-*` variables, including per-type accent colors, or target `.storybook-addon-md-callout[data-callout]`. Custom `MarkdownRenderer` implementations receive the original blockquote syntax and must render callouts themselves. See the [callout syntax](https://github.com/ruijdacd/storybook-addon-md#callouts) and [styling reference](https://github.com/ruijdacd/storybook-addon-md/blob/main/STYLING.md#callouts).
+
 ## 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.
+- 8bf5398: 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.
 
@@ -12,19 +20,19 @@
 
 ### 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.
+- 2052cb5: 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).
+- d3c7300: 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
 
-- 58f8a64: Remove the `exclude` option. Move exclusions into `patterns` with a leading `!`:
+- dc93b21: Remove the `exclude` option. Move exclusions into `patterns` with a leading `!`:
 
   ```ts
   patterns: ['docs/**/*.md', '!docs/private/**'];
@@ -34,7 +42,7 @@
 
 ### Patch Changes
 
-- 58f8a64: Upgrade Chokidar to v5 and replace fast-glob with tinyglobby. Keep explicit glob matching, negative-pattern exclusions, and live Markdown updates.
+- dc93b21: Upgrade Chokidar to v5 and replace fast-glob with tinyglobby. Keep explicit glob matching, negative-pattern exclusions, and live Markdown updates.
 
 ## 0.1.0
 

package/README.md

@@ -1,7 +1,12 @@
 # Storybook Markdown
 
+[![npm version](https://img.shields.io/npm/v/storybook-addon-md)](https://www.npmjs.com/package/storybook-addon-md)
+[![CI](https://github.com/ruijdacd/storybook-addon-md/actions/workflows/ci.yml/badge.svg)](https://github.com/ruijdacd/storybook-addon-md/actions/workflows/ci.yml)
+
 Write ordinary `.md` files and browse them inside Storybook. Attach documentation to component stories or create standalone pages, with no JSX, imports, or MDX wrappers to maintain.
 
+[Try the live example](https://storybook-addon-md.netlify.app/?path=/docs/guides-introduction--docs).
+
 - Discover Markdown automatically, including live additions, edits, and deletions.
 - Show component docs alongside existing examples and generated props.
 - Bundle relative images and downloads in static builds.
@@ -9,8 +14,10 @@ Write ordinary `.md` files and browse them inside Storybook. Attach documentatio
 
 ## Install
 
+We recommend [ni](https://github.com/antfu-collective/ni#readme) to install dependencies with your project's package manager. Install it first with `npm install -g @antfu/ni`, then run:
+
 ```sh
-nub add -D storybook-addon-md @storybook/addon-docs@10.6.0
+ni -D storybook-addon-md @storybook/addon-docs@10.6.0
 ```
 
 Tested with **Storybook 10.6.0**, **React Vite 10.6.0**, **Vite 7.3.6**, and **React 19.2.4**. Requires Node 22.13+. Other builders and renderers are not tested.
@@ -103,6 +110,29 @@ Without a title, `docs/Introduction.md` appears at `Documentation/docs/Introduct
 
 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.
 
+### Callouts
+
+GitHub-style alerts render as labelled callouts:
+
+```md
+> [!NOTE]
+> Additional context.
+
+> [!TIP]
+> Recommended approach.
+
+> [!IMPORTANT]
+> Information readers need to succeed.
+
+> [!WARNING]
+> Something that requires care.
+
+> [!CAUTION]
+> A risk or destructive consequence.
+```
+
+The marker must be the first line of a blockquote, on its own, and is case-insensitive. Callouts keep ordinary Markdown, including paragraphs, emphasis, links, lists, and code blocks, and relative links and images inside them resolve as usual. Blockquotes without a marker, unrecognized markers, and markers followed by text on the same line render as ordinary blockquotes. Custom titles and collapsible callouts are not supported. Source files and manifests keep the original syntax.
+
 ### Frontmatter
 
 YAML frontmatter is optional. Use lowercase field names.
@@ -225,9 +255,9 @@ Set `stylesheet: '.storybook/markdown.css'` to override the defaults:
 }
 ```
 
-Variables cover typography, spacing, links, code, tables, images, and chips. Defaults follow Storybook’s Docs theme in light and dark mode.
+Variables cover typography, spacing, links, code, tables, images, chips, and callouts. Defaults follow Storybook’s Docs theme in light and dark mode.
 
-See [Styling](STYLING.md) for all variables, status colors, theme switching, and custom layouts or Markdown renderers. The [example stylesheet](https://github.com/ruijdacd/storybook-addon-md/blob/main/example/.storybook/markdown.css) provides a complete GitHub-inspired theme.
+See [Styling](STYLING.md) for all variables, status and callout colors, theme switching, and custom layouts or Markdown renderers. The [example stylesheet](https://github.com/ruijdacd/storybook-addon-md/blob/main/example/.storybook/markdown.css) provides a complete GitHub-inspired theme.
 
 ## Links and limitations
 
@@ -254,6 +284,6 @@ Choose either example. They share stories, Markdown, and styling, with separate
 
 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.
+Browse **Guides → Introduction**, **Guides → Callouts**, **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

@@ -24,6 +24,21 @@ Use your theme selector to override colors in dark mode. The [complete example](
 | Variable                          | CSS property                  |
 | --------------------------------- | ----------------------------- |
 | `--sbmd-background`               | `background`                  |
+| `--sbmd-callout-background`       | `background`                  |
+| `--sbmd-callout-border`           | `border-inline-start`         |
+| `--sbmd-callout-caution-color`    | Caution accent color          |
+| `--sbmd-callout-color`            | `color`                       |
+| `--sbmd-callout-important-color`  | Important accent color        |
+| `--sbmd-callout-label-color`      | `color`                       |
+| `--sbmd-callout-label-margin`     | `margin-bottom`               |
+| `--sbmd-callout-label-size`       | `font-size`                   |
+| `--sbmd-callout-label-weight`     | `font-weight`                 |
+| `--sbmd-callout-margin`           | `margin`                      |
+| `--sbmd-callout-note-color`       | Note accent color             |
+| `--sbmd-callout-padding`          | `padding`                     |
+| `--sbmd-callout-radius`           | `border-radius`               |
+| `--sbmd-callout-tip-color`        | Tip accent color              |
+| `--sbmd-callout-warning-color`    | Warning accent color          |
 | `--sbmd-checkbox-color`           | `accent-color`                |
 | `--sbmd-checkbox-gap`             | `margin-inline-end`           |
 | `--sbmd-code-border`              | `border`                      |
@@ -106,6 +121,8 @@ Use your theme selector to override colors in dark mode. The [complete example](
 
 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.
 
+Callouts are `.storybook-addon-md-callout` elements with `data-callout` set to `note`, `tip`, `important`, `warning`, or `caution`, and a `.storybook-addon-md-callout-label` paragraph. Each type’s accent color sets the default border color and label color. Per-type accent variables default to Storybook theme colors chosen for the light or dark base. `--sbmd-callout-color` applies to text inside callouts; `--sbmd-callout-border` and `--sbmd-callout-label-color` replace the accent for every type.
+
 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
@@ -147,6 +164,34 @@ Status chips share the tag variables. Use `data-status` to map values to your th
 
 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()`.
 
+### Callouts
+
+Map the accent colors to your design tokens, and adjust the shared box and label styles:
+
+```css
+.storybook-addon-md-page {
+  --sbmd-callout-note-color: light-dark(#0969da, #4493f8);
+  --sbmd-callout-tip-color: light-dark(#1a7f37, #3fb950);
+  --sbmd-callout-important-color: light-dark(#8250df, #ab7df8);
+  --sbmd-callout-warning-color: light-dark(#9a6700, #d29922);
+  --sbmd-callout-caution-color: light-dark(#d1242f, #f85149);
+  --sbmd-callout-padding: 0.5rem 1rem;
+  --sbmd-callout-radius: 0.375rem;
+  --sbmd-callout-label-weight: 500;
+}
+```
+
+Use `data-callout` for anything that differs per type beyond the accent color, such as a tinted background or a different border width:
+
+```css
+.storybook-addon-md-callout[data-callout='caution'] {
+  --sbmd-callout-background: light-dark(#ffebe9, #2d1214);
+  --sbmd-callout-border: 0.375rem solid var(--sbmd-callout-caution-color);
+}
+```
+
+The label is visible text, so callouts remain distinguishable without color. The markup is static: no `role="alert"` or live region is used.
+
 ### Light and Dark Themes
 
 Use Storybook’s standard Docs theme configuration for a fixed theme:
@@ -180,6 +225,8 @@ export function MarkdownRenderer(document: MarkdownDocument) {
 
 `MarkdownRenderer` receives `{ markdown, metadata, source, heading? }`: processed Markdown with resolved asset URLs, preserved frontmatter, and the source path relative to the project folder.
 
+Callouts are rendered by `DefaultMarkdownRenderer`. A custom `MarkdownRenderer` receives them as ordinary blockquotes whose first line is the `[!NOTE]` marker, serialized as `\[!NOTE]` so that renderers treat the brackets as text. Render callouts yourself or delegate to `DefaultMarkdownRenderer`. Custom layouts are unaffected because callouts are part of `children`.
+
 `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/runtime.js

@@ -1,7 +1,39 @@
+import { Children, cloneElement, isValidElement } from "react";
 import { useTheme } from "storybook/theming";
 import { CodeOrSourceMdx, Controls, HeadersMdx, Markdown, Primary, Stories, Title } from "@storybook/addon-docs/blocks";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/runtime.tsx
+const calloutLabels = {
+	note: "Note",
+	tip: "Tip",
+	important: "Important",
+	warning: "Warning",
+	caution: "Caution"
+};
+function Blockquote({ children, ...props }) {
+	const [first, ...rest] = Children.toArray(children);
+	const paragraph = isValidElement(first) && first.type === "p" ? first : void 0;
+	const items = Children.toArray(paragraph?.props.children);
+	const split = items.findIndex((item) => typeof item !== "string");
+	const leading = items.slice(0, split === -1 ? items.length : split).join("");
+	const marker = /^\[!(note|tip|important|warning|caution)\](\n|$)/i.exec(leading);
+	if (!paragraph || !marker || !marker[2] && split !== -1) return /* @__PURE__ */ jsx("blockquote", {
+		...props,
+		children
+	});
+	const type = marker[1].toLowerCase();
+	const remainder = leading.slice(marker[0].length);
+	const trailing = split === -1 ? [] : items.slice(split);
+	const content = remainder || trailing.length ? [cloneElement(paragraph, void 0, ...remainder ? [remainder] : [], ...trailing), ...rest] : rest;
+	return /* @__PURE__ */ jsxs("div", {
+		className: "storybook-addon-md-callout",
+		"data-callout": type,
+		children: [/* @__PURE__ */ jsx("p", {
+			className: "storybook-addon-md-callout-label",
+			children: calloutLabels[type]
+		}), content]
+	});
+}
 function DefaultMarkdownRenderer({ markdown }) {
 	return /* @__PURE__ */ jsx(Markdown, {
 		options: {
@@ -9,7 +41,8 @@ function DefaultMarkdownRenderer({ markdown }) {
 			overrides: {
 				code: CodeOrSourceMdx,
 				...HeadersMdx,
-				a: "a"
+				a: "a",
+				blockquote: Blockquote
 			}
 		},
 		children: markdown
@@ -44,13 +77,19 @@ function DefaultLayout({ documents, title, attached, children, examples, heading
 }
 function Documentation({ documents, title, attached = false, presentation = {}, tagFields = [] }) {
 	const theme = useTheme();
+	const dark = theme.base === "dark";
 	const defaults = {
 		"--sbmd-native-color": theme.color.defaultText,
 		"--sbmd-native-link-color": theme.color.secondary,
 		"--sbmd-native-font-family": theme.typography.fonts.base,
 		"--sbmd-native-monospace-font-family": theme.typography.fonts.mono,
 		"--sbmd-native-border-color": theme.appBorderColor,
-		"--sbmd-native-code-background": theme.background.content
+		"--sbmd-native-code-background": theme.background.content,
+		"--sbmd-native-callout-note-color": theme.color.secondary,
+		"--sbmd-native-callout-tip-color": dark ? theme.color.positive : theme.color.positiveText,
+		"--sbmd-native-callout-important-color": dark ? `color-mix(in srgb, ${theme.color.purple}, white 45%)` : theme.color.purple,
+		"--sbmd-native-callout-warning-color": dark ? theme.color.warning : theme.color.warningText,
+		"--sbmd-native-callout-caution-color": dark ? theme.color.negative : theme.color.negativeText
 	};
 	const Layout = presentation.Layout ?? DefaultLayout;
 	const Renderer = presentation.MarkdownRenderer ?? DefaultMarkdownRenderer;

package/dist/styles.css

@@ -109,6 +109,65 @@
   background: var(--sbmd-quote-background, transparent);
 }
 
+.sbdocs-content .storybook-addon-md-callout {
+  margin: var(--sbmd-callout-margin, 1rem 0);
+  padding: var(--sbmd-callout-padding, 0.5rem 1rem);
+  border-inline-start: var(--sbmd-callout-border, 0.25rem solid var(--sbmd-native-callout-color));
+  border-radius: var(--sbmd-callout-radius, 0);
+  background: var(--sbmd-callout-background, transparent);
+}
+
+.sbdocs-content .storybook-addon-md-callout[data-callout='note'] {
+  --sbmd-native-callout-color: var(
+    --sbmd-callout-note-color,
+    var(--sbmd-native-callout-note-color)
+  );
+}
+
+.sbdocs-content .storybook-addon-md-callout[data-callout='tip'] {
+  --sbmd-native-callout-color: var(--sbmd-callout-tip-color, var(--sbmd-native-callout-tip-color));
+}
+
+.sbdocs-content .storybook-addon-md-callout[data-callout='important'] {
+  --sbmd-native-callout-color: var(
+    --sbmd-callout-important-color,
+    var(--sbmd-native-callout-important-color)
+  );
+}
+
+.sbdocs-content .storybook-addon-md-callout[data-callout='warning'] {
+  --sbmd-native-callout-color: var(
+    --sbmd-callout-warning-color,
+    var(--sbmd-native-callout-warning-color)
+  );
+}
+
+.sbdocs-content .storybook-addon-md-callout[data-callout='caution'] {
+  --sbmd-native-callout-color: var(
+    --sbmd-callout-caution-color,
+    var(--sbmd-native-callout-caution-color)
+  );
+}
+
+.sbdocs-content .storybook-addon-md-callout :is(p, li, td, th) {
+  color: var(--sbmd-callout-color, var(--sbmd-color, var(--sbmd-native-color)));
+}
+
+.sbdocs-content .storybook-addon-md .storybook-addon-md-callout-label {
+  margin: 0 0 var(--sbmd-callout-label-margin, 0.25rem);
+  color: var(--sbmd-callout-label-color, var(--sbmd-native-callout-color));
+  font-size: var(--sbmd-callout-label-size, var(--sbmd-font-size, 0.875rem));
+  font-weight: var(--sbmd-callout-label-weight, 600);
+}
+
+.sbdocs-content .storybook-addon-md-callout > .storybook-addon-md-callout-label + * {
+  margin-top: 0;
+}
+
+.sbdocs-content .storybook-addon-md-callout > :last-child {
+  margin-bottom: 0;
+}
+
 .sbdocs-content .storybook-addon-md :not(pre) > code {
   padding: var(--sbmd-inline-code-padding, 0.1875rem 0.3125rem);
   border: var(--sbmd-inline-code-border, 0.0625rem solid var(--sbmd-native-border-color));
@@ -174,7 +233,8 @@
   margin-inline-end: var(--sbmd-checkbox-gap, 0.25rem);
 }
 
-.sbdocs-content .storybook-addon-md > pre {
+.sbdocs-content .storybook-addon-md > pre,
+.sbdocs-content .storybook-addon-md-callout > pre {
   padding: 0;
   border: 0;
   white-space: normal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storybook-addon-md",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Discover ordinary Markdown and render it in Storybook Docs.",
   "keywords": [
     "docs",
@@ -14,6 +14,7 @@
     "url": "https://github.com/ruijdacd/storybook-addon-md/issues"
   },
   "license": "MIT",
+  "author": "Rui Duarte (https://github.com/ruijdacd)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ruijdacd/storybook-addon-md.git"