storybook-addon-md 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # storybook-addon-md
 
+## 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,30 @@ 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, opened in the top frame. |
+| `repository` | None    | Links to other files or folders inside the project folder become `<repository>/<path relative to root>` links.           |
+
+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 +287,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/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.js

@@ -34,6 +34,18 @@ function Blockquote({ children, ...props }) {
 		}), content]
 	});
 }
+function Anchor({ href, target, ...props }) {
+	if (!href?.startsWith("?path=")) return /* @__PURE__ */ jsx("a", {
+		...props,
+		href,
+		target
+	});
+	return /* @__PURE__ */ jsx("a", {
+		...props,
+		href: new URL(href, new URL("./", window.location.href)).href,
+		target: target ?? "_top"
+	});
+}
 function DefaultMarkdownRenderer({ markdown }) {
 	return /* @__PURE__ */ jsx(Markdown, {
 		options: {
@@ -41,7 +53,7 @@ function DefaultMarkdownRenderer({ markdown }) {
 			overrides: {
 				code: CodeOrSourceMdx,
 				...HeadersMdx,
-				a: "a",
+				a: Anchor,
 				blockquote: Blockquote
 			}
 		},

package/package.json

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