storybook-addon-md 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # storybook-addon-md
 
+## 0.9.0
+
+### Minor Changes
+
+- 990c4b9: Rendered links now behave correctly on their own. Docs links keep the absolute manager URL and navigate through the Storybook channel on a plain click, so the preview no longer reloads; modified clicks and non-primary buttons fall through to the browser. External links open in a new tab with `rel="noopener noreferrer"`, both kinds carry a `data-link` attribute, and explicit `target` or `rel` attributes are preserved. `Anchor` is exported from `storybook-addon-md/runtime` for custom renderers.
+
+  Docs links no longer set `target="_top"`. Stylesheets or tests that relied on that attribute should target `[data-link="docs"]` instead.
+
+## 0.8.0
+
+### Minor Changes
+
+- 298284c: Add an opt-in `links` option that rewrites relative Markdown links instead of bundling their targets as assets.
+
+  - `links.documents` (default `true` when `links` is set) turns links to other discovered documents into ordinary links to their Docs page in the Storybook manager.
+  - `links.repository` turns links to other files or folders inside root into `<repository>/<relative path>` links, so source files are no longer copied into the bundle and folder links no longer fail discovery.
+
+  Images, image reference definitions, manifests, and the default behavior without `links` are unchanged.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -159,6 +159,7 @@ Invalid frontmatter, missing or ambiguous story references, and missing local as
 | `manifests`    | `false`                        | Include original Markdown in Storybook documentation manifests. |
 | `tagFields`    | `[]`                           | Additional frontmatter fields displayed as tags.                |
 | `presentation` | None                           | Module exporting `Layout` and/or `MarkdownRenderer`.            |
+| `links`        | None                           | Rewrite relative links to Docs pages and repository files.      |
 
 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.
 
@@ -186,6 +187,32 @@ const config: StorybookConfig = {
 
 `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`.
 
+### Relative links
+
+By default every relative link is bundled as an asset, so a link to another Markdown file opens its raw source. Set `links` to rewrite relative links instead:
+
+```ts
+{
+  name: 'storybook-addon-md',
+  options: {
+    patterns: ['src/**/*.md', 'docs/**/*.md'],
+    links: {
+      documents: true,
+      repository: 'https://github.com/acme/design-system/blob/main',
+    },
+  },
+}
+```
+
+| Field        | Default | Behavior                                                                                                       |
+| ------------ | ------- | -------------------------------------------------------------------------------------------------------------- |
+| `documents`  | `true`  | Links to discovered Markdown documents become ordinary links to their Docs page in the manager.                |
+| `repository` | None    | Links to other files or folders inside the project folder become `<repository>/<path relative to root>` links. |
+
+Rendered links behave correctly without a click handler in your Layout. Docs links keep the absolute manager URL as `href`, so copying, middle-clicking, and opening in a new tab work as usual, and a plain left click asks the manager to navigate without reloading the preview. Modified clicks fall through to the browser. Absolute `http:` and `https:` links, including every `repository` link, open in a new tab with `rel="noopener noreferrer"`. Fragment links are left untouched, and explicit `target` or `rel` attributes from a custom renderer are never overridden.
+
+Fragments and query strings are preserved. Attached documents link to their story file's Docs page using the CSF `title`; when the story file has no explicit title, the link falls back to the `story:<path>` key and will not resolve until a title is set. Images and image reference definitions remain bundled assets, and manifests keep the original Markdown. Relative links to files outside root, or to missing files, still fail the build. Without `links`, behavior is unchanged.
+
 ### 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:
@@ -262,7 +289,7 @@ See [Styling](STYLING.md) for all variables, status and callout colors, theme sw
 ## Links and limitations
 
 - Relative links and images resolve from the Markdown source and are included in static builds. Root-relative assets use Storybook’s `staticDirs`.
-- 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.
+- Without the `links` option, links to `.md` files open the original source, not a rendered Docs page. Set `links` or 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).
 - Multiple development Storybooks sharing one config directory are unsupported.

package/STYLING.md

@@ -90,6 +90,8 @@ Five tokens cover most of the page. Element variables fall back to them, so set
 
 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.
 
+Links carry `data-link="docs"` for Storybook Docs pages and `data-link="external"` for absolute `http:` and `https:` URLs, so a stylesheet can mark external links or hide the distinction. Fragment links and other hrefs have no `data-link`.
+
 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. The addon sets `--sbmd-callout-accent` on each callout from its type’s accent variable, and uses it for the default border and the label color. Per-type accent variables default to Storybook theme colors chosen for the light or dark base.
 
 Properties without a variable use ordinary CSS. Match the addon’s specificity for properties it sets, for example `.sbdocs-content .storybook-addon-md h2` for heading letter spacing or `.sbdocs-content .storybook-addon-md-tags` for the tag gap.
@@ -204,6 +206,18 @@ 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.
 
+`Anchor` is the link component used by `DefaultMarkdownRenderer`. It navigates the manager for Docs links, opens external links in a new tab, sets `data-link`, and keeps explicit `target` and `rel` attributes. Reuse it in a custom renderer's `overrides` so links keep the same behavior:
+
+```tsx
+import { Markdown } from '@storybook/addon-docs/blocks';
+import { Anchor } from 'storybook-addon-md/runtime';
+import type { MarkdownDocument } from 'storybook-addon-md/runtime';
+
+export function MarkdownRenderer({ markdown }: MarkdownDocument) {
+  return <Markdown options={{ overrides: { a: Anchor } }}>{markdown}</Markdown>;
+}
+```
+
 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.

package/dist/{content-CTcZAfoF.js → content-BrghNgvp.js}

@@ -17,12 +17,13 @@ const storyExtensions = [
 ];
 const slash = (value) => value.split(path.sep).join("/");
 const fail = (source, message) => /* @__PURE__ */ new Error(`[storybook-addon-md] ${source}: ${message}`);
-async function localFile(file, root, source, kind) {
+async function localFile(file, root, source, kind, directories = false) {
 	try {
 		const actual = await realpath(file);
 		const relative = path.relative(await realpath(root), actual);
 		if (relative.startsWith(`..${path.sep}`) || relative === ".." || path.isAbsolute(relative)) throw fail(source, `${kind} must be inside root: ${file}`);
-		if (!(await stat(actual)).isFile()) throw new Error("not a file");
+		const info = await stat(actual);
+		if (!info.isFile() && !(directories && info.isDirectory())) throw new Error("not a file");
 		return file;
 	} catch (error) {
 		if (error instanceof Error && error.message.startsWith("[storybook-addon-md]")) throw error;
@@ -85,12 +86,20 @@ async function resolveStoryAssociations(file, metadata, root) {
 	if (matches.length !== 1) throw Object.assign(fail(file, matches.length ? "ambiguous sibling stories; set stories explicitly" : "missing sibling story for .metadata.md; set stories explicitly or rename the Markdown file"), { dependencies: storyExtensions.map((extension) => `${base}.stories.${extension}`) });
 	return [await localFile(matches[0], root, file, "story reference")];
 }
-async function resolveAssets(body, file, root, standalone = false) {
+const imageDefinitions = (tree) => {
+	const identifiers = /* @__PURE__ */ new Set();
+	visit(tree, "imageReference", (node) => {
+		identifiers.add(node.identifier);
+	});
+	return identifiers;
+};
+async function resolveAssets(body, file, root, standalone = false, resolveLink) {
 	const tree = markdown.parse(body);
 	const nodes = [];
 	visit(tree, (node) => {
 		if (node.type === "image" || node.type === "link" || node.type === "definition") nodes.push(node);
 	});
+	const images = imageDefinitions(tree);
 	const assets = [];
 	for (const node of nodes) {
 		const url = node.url;
@@ -102,7 +111,13 @@ async function resolveAssets(body, file, root, standalone = false) {
 		} catch {
 			throw fail(file, `invalid local URL: ${url}`);
 		}
-		const asset = await localFile(path.resolve(path.dirname(file), decoded), root, file, "local asset");
+		const target = path.resolve(path.dirname(file), decoded);
+		const link = node.type === "image" || node.type === "definition" && images.has(node.identifier) || !resolveLink ? void 0 : await resolveLink(target, file);
+		if (link) {
+			node.url = `${link}${suffix}`;
+			continue;
+		}
+		const asset = await localFile(target, root, file, "local asset");
 		const token = `SBMDASSET${assets.length}END`;
 		if (body.includes(token)) throw fail(file, `reserved asset token in content: ${token}`);
 		assets.push({
@@ -124,7 +139,7 @@ async function resolveAssets(body, file, root, standalone = false) {
 		heading
 	};
 }
-async function discover({ root, patterns, output }) {
+async function discover({ root, patterns, output, links, docsName }) {
 	if (!Array.isArray(patterns) || !patterns.length || patterns.some((item) => typeof item !== "string" || !item || path.isAbsolute(item) || item.split("/").includes(".."))) throw fail(root, "patterns must be a non-empty array of globs relative to root");
 	const files = await glob(patterns, {
 		cwd: root,
@@ -139,9 +154,8 @@ async function discover({ root, patterns, output }) {
 			...path.relative(root, output).startsWith("..") ? [] : [`${slash(path.relative(root, output))}/**`]
 		]
 	});
-	return Promise.all(files.sort().filter((file) => file.endsWith(".md")).map(async (file) => {
+	const documents = await Promise.all(files.sort().filter((file) => file.endsWith(".md")).map(async (file) => {
 		const { original, body, metadata, stories } = await readMarkdown(file, root);
-		const content = await resolveAssets(body, file, root, !stories.length);
 		return {
 			file,
 			original,
@@ -149,10 +163,34 @@ async function discover({ root, patterns, output }) {
 			source: slash(path.relative(root, file)),
 			title: metadata.title ?? `Documentation/${slash(path.relative(root, file)).replace(/\.md$/, "")}`,
 			metadata,
-			stories,
-			...content
+			stories
 		};
 	}));
+	const resolveLink = links ? await linkResolver(links, documents, root, docsName) : void 0;
+	return Promise.all(documents.map(async (document) => ({
+		...document,
+		...await resolveAssets(document.body, document.file, root, !document.stories.length, resolveLink)
+	})));
+}
+async function docsId(document, root, docsName, titles) {
+	const { toId } = await import("storybook/internal/csf");
+	if (!document.stories.length) return toId(document.title, docsName);
+	const [story] = document.stories;
+	if (!titles.has(story)) titles.set(story, import("storybook/internal/csf-tools").then(({ readCsf }) => readCsf(story, { makeTitle: (title) => title })).then((csf) => csf.parse().meta).catch(() => void 0));
+	const meta = await titles.get(story);
+	return meta?.title ? toId(meta.id ?? meta.title, docsName) : `story:${slash(path.relative(root, story))}`;
+}
+async function linkResolver(links, documents, root, docsName = "Docs") {
+	const paths = /* @__PURE__ */ new Map();
+	const titles = /* @__PURE__ */ new Map();
+	if (links.documents !== false) for (const document of documents) paths.set(document.file, `?path=/docs/${await docsId(document, root, docsName, titles)}`);
+	const repository = links.repository?.replace(/\/+$/, "");
+	return async (target, source) => {
+		const page = paths.get(target);
+		if (page || !repository) return page;
+		await localFile(target, root, source, "link target", true);
+		return `${repository}/${slash(path.relative(root, target))}`;
+	};
 }
 async function readMarkdown(file, root) {
 	root = path.resolve(root);

package/dist/{content-CKQsa_HK.d.ts → content-CwjmOiRK.d.ts}

@@ -1,4 +1,4 @@
-import { t as MarkdownOptions } from "./index-BzM0tjFM.js";
+import { n as MarkdownOptions } from "./index-D3ynUvxB.js";
 //#region src/content.d.ts
 interface ContentOptions extends MarkdownOptions {
   root: string;
@@ -17,7 +17,7 @@ declare function parseMarkdown(text: string, source: string): {
   metadata: Frontmatter;
 };
 declare function resolveStoryAssociations(file: string, metadata: Frontmatter, root: string): Promise<string[]>;
-declare function discover({ root, patterns, output }: ContentOptions): Promise<{
+declare function discover({ root, patterns, output, links, docsName }: ContentOptions): Promise<{
   markdown: string;
   assets: {
     file: string;

package/dist/{index-BzM0tjFM.d.ts → index-D3ynUvxB.d.ts}

@@ -1,4 +1,8 @@
 //#region src/index.d.ts
+interface LinkOptions {
+  documents?: boolean;
+  repository?: string;
+}
 interface MarkdownOptions {
   tagFields?: string[];
   manifests?: boolean;
@@ -7,6 +11,7 @@ interface MarkdownOptions {
   stylesheet?: string;
   root?: string;
   presentation?: string;
+  links?: LinkOptions;
 }
 //#endregion
-export { MarkdownOptions as t };
+export { MarkdownOptions as n, LinkOptions as t };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { t as MarkdownOptions } from "./index-BzM0tjFM.js";
-export { MarkdownOptions };
+import { n as MarkdownOptions, t as LinkOptions } from "./index-D3ynUvxB.js";
+export { LinkOptions, MarkdownOptions };

package/dist/node.d.ts

@@ -1,2 +1,2 @@
-import { a as readMarkdown, i as parseMarkdown, o as resolveStoryAssociations, r as Frontmatter } from "./content-CKQsa_HK.js";
+import { a as readMarkdown, i as parseMarkdown, o as resolveStoryAssociations, r as Frontmatter } from "./content-CwjmOiRK.js";
 export { type Frontmatter, parseMarkdown, readMarkdown, resolveStoryAssociations };

package/dist/node.js

@@ -1,2 +1,2 @@
-import { a as readMarkdown, i as parseMarkdown, o as resolveStoryAssociations } from "./content-CTcZAfoF.js";
+import { a as readMarkdown, i as parseMarkdown, o as resolveStoryAssociations } from "./content-BrghNgvp.js";
 export { parseMarkdown, readMarkdown, resolveStoryAssociations };

package/dist/preset.d.ts

@@ -1,5 +1,5 @@
-import { t as MarkdownOptions } from "./index-BzM0tjFM.js";
-import { n as DiscoveredDocument, t as ContentOptions } from "./content-CKQsa_HK.js";
+import { n as MarkdownOptions } from "./index-D3ynUvxB.js";
+import { n as DiscoveredDocument, t as ContentOptions } from "./content-CwjmOiRK.js";
 import { StorybookConfigRaw } from "storybook/internal/types";
 import { UserConfig } from "vite";
 //#region src/preset.d.ts

package/dist/preset.js

@@ -1,4 +1,4 @@
-import { n as fail, r as localFile, s as slash, t as discover } from "./content-CTcZAfoF.js";
+import { n as fail, r as localFile, s as slash, t as discover } from "./content-BrghNgvp.js";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { watch } from "chokidar";
@@ -133,6 +133,8 @@ function settings(options) {
 	const root = path.resolve(configDir, options.root ?? "..");
 	const generatedDir = options.generatedDir ?? "storybook-markdown-generated";
 	if (options.tagFields !== void 0 && (!Array.isArray(options.tagFields) || options.tagFields.some((field) => typeof field !== "string" || !/^[a-z][a-z0-9_-]*$/.test(field)))) throw fail(configDir, "tagFields must be an array of lowercase frontmatter field names");
+	const { links } = options;
+	if (links !== void 0 && (typeof links !== "object" || links === null || Array.isArray(links) || Object.keys(links).some((key) => !["documents", "repository"].includes(key)) || links.documents !== void 0 && typeof links.documents !== "boolean" || links.repository !== void 0 && (typeof links.repository !== "string" || !/^https?:\/\/\S+$/.test(links.repository)))) throw fail(configDir, "links must be an object with an optional documents boolean and an optional repository URL");
 	if ("exclude" in options) throw fail(configDir, "exclude has been removed; use negative globs in patterns, such as !docs/private/**");
 	if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(generatedDir) || ["node_modules", "storybook-static"].includes(generatedDir)) throw fail(configDir, "generatedDir must be a visible folder name containing only letters, digits, hyphens or underscores");
 	return {
@@ -141,7 +143,11 @@ function settings(options) {
 		patterns: options.patterns,
 		tagFields: options.tagFields,
 		stylesheet: options.stylesheet ? path.resolve(root, options.stylesheet) : void 0,
-		presentation: options.presentation ? path.resolve(root, options.presentation) : void 0
+		presentation: options.presentation ? path.resolve(root, options.presentation) : void 0,
+		links: links ? {
+			documents: links.documents ?? true,
+			repository: links.repository?.replace(/\/+$/, "")
+		} : void 0
 	};
 }
 async function stories(existing = [], options) {

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import { ComponentType, ReactNode } from "react";
+import { ComponentProps, ComponentType, ReactNode } from "react";
 //#region src/types.d.ts
 interface MarkdownDocument {
   source: string;
@@ -21,6 +21,7 @@ interface Presentation {
 }
 //#endregion
 //#region src/runtime.d.ts
+export declare function Anchor({ href, target, rel, ...props }: ComponentProps<'a'>): import("react").JSX.Element;
 export declare function DefaultMarkdownRenderer({ markdown }: MarkdownDocument): import("react").JSX.Element;
 export declare function DefaultLayout({ documents, title, attached, children, examples, heading, tagFields }: LayoutProps): import("react").JSX.Element;
 export declare function Documentation({ documents, title, attached, presentation, tagFields }: {

package/dist/runtime.js

@@ -1,4 +1,6 @@
 import { Children, cloneElement, isValidElement } from "react";
+import { NAVIGATE_URL } from "storybook/internal/core-events";
+import { addons } from "storybook/preview-api";
 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";
@@ -34,6 +36,37 @@ function Blockquote({ children, ...props }) {
 		}), content]
 	});
 }
+function Anchor({ href, target, rel, ...props }) {
+	if (href?.startsWith("?path=")) {
+		const navigate = (event) => {
+			props.onClick?.(event);
+			if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || target && target !== "_self") return;
+			event.preventDefault();
+			addons.getChannel().emit(NAVIGATE_URL, href);
+		};
+		return /* @__PURE__ */ jsx("a", {
+			...props,
+			href: new URL(href, new URL("./", window.location.href)).href,
+			target,
+			rel,
+			"data-link": "docs",
+			onClick: navigate
+		});
+	}
+	if (href && /^https?:\/\//i.test(href)) return /* @__PURE__ */ jsx("a", {
+		...props,
+		href,
+		target: target ?? "_blank",
+		rel: rel ?? "noopener noreferrer",
+		"data-link": "external"
+	});
+	return /* @__PURE__ */ jsx("a", {
+		...props,
+		href,
+		target,
+		rel
+	});
+}
 function DefaultMarkdownRenderer({ markdown }) {
 	return /* @__PURE__ */ jsx(Markdown, {
 		options: {
@@ -41,7 +74,7 @@ function DefaultMarkdownRenderer({ markdown }) {
 			overrides: {
 				code: CodeOrSourceMdx,
 				...HeadersMdx,
-				a: "a",
+				a: Anchor,
 				blockquote: Blockquote
 			}
 		},
@@ -120,4 +153,4 @@ function Documentation({ documents, title, attached = false, presentation = {},
 	});
 }
 //#endregion
-export { DefaultLayout, DefaultMarkdownRenderer, Documentation };
+export { Anchor, DefaultLayout, DefaultMarkdownRenderer, Documentation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storybook-addon-md",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Discover ordinary Markdown and render it in Storybook Docs.",
   "keywords": [
     "docs",