storybook-addon-md 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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

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,6 +101,8 @@ 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.
@@ -113,12 +127,59 @@ Invalid frontmatter, missing or ambiguous story references, and missing local as
 | `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`:
@@ -142,6 +203,8 @@ const config: StorybookConfig = {
 };
 ```
 
+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.
@@ -172,7 +235,7 @@ 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.
 
 ## Examples and contributing
 
@@ -182,7 +245,7 @@ Install dependencies with **Nub 0.7.5** and **Node 24.11+**:
 nub install
 ```
 
-Choose either example. They share stories, Markdown, and styling, with separate Storybook configurations:
+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                         |
 | ----------- | ------------------------------------- | ------------------------------ | ----------------------------- |

package/STYLING.md

@@ -178,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 };

package/dist/content-CTcZAfoF.js

@@ -0,0 +1,174 @@
+import path from "node:path";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { glob } from "tinyglobby";
+import { isMap, parseDocument } from "yaml";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkStringify from "remark-stringify";
+import { visit } from "unist-util-visit";
+//#region src/content.ts
+const markdown = unified().use(remarkParse).use(remarkGfm).use(remarkStringify);
+const storyExtensions = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js"
+];
+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) {
+	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");
+		return file;
+	} catch (error) {
+		if (error instanceof Error && error.message.startsWith("[storybook-addon-md]")) throw error;
+		throw Object.assign(fail(source, `missing ${kind}: ${file}`), { dependency: file });
+	}
+}
+function parseMarkdown(text, source) {
+	const normalized = text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+	if (!normalized.startsWith("---\n")) return {
+		body: normalized,
+		metadata: {}
+	};
+	const end = /^---\s*$/gm;
+	end.lastIndex = 4;
+	const closing = end.exec(normalized);
+	if (!closing) throw fail(source, "frontmatter must end with ---");
+	const yaml = parseDocument(normalized.slice(4, closing.index), { uniqueKeys: true });
+	if (yaml.errors.length) throw fail(source, `invalid frontmatter: ${yaml.errors[0].message}`);
+	if (yaml.warnings.length) throw fail(source, `invalid frontmatter: ${yaml.warnings[0].message}`);
+	if (yaml.contents && !isMap(yaml.contents)) throw fail(source, "frontmatter must be a mapping");
+	let metadata;
+	try {
+		metadata = yaml.toJS({ maxAliasCount: 50 }) ?? {};
+		JSON.stringify(metadata, (_, value) => {
+			if (typeof value === "number" && !Number.isFinite(value)) throw new Error("metadata numbers must be finite");
+			return value;
+		});
+	} catch (error) {
+		throw fail(source, `invalid frontmatter: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (typeof metadata !== "object" || Array.isArray(metadata)) throw fail(source, "frontmatter must be a mapping");
+	for (const key of Object.keys(metadata)) if (!/^[a-z][a-z0-9_-]*$/.test(key)) throw fail(source, `frontmatter keys must be lowercase: ${key}`);
+	if ("title" in metadata && (typeof metadata.title !== "string" || !metadata.title.trim())) throw fail(source, "title must be a non-empty string");
+	if ("status" in metadata && (typeof metadata.status !== "string" || !metadata.status.trim())) throw fail(source, "status must be a non-empty string");
+	if ("tags" in metadata && (!Array.isArray(metadata.tags) || metadata.tags.some((tag) => typeof tag !== "string" || !tag.trim()))) throw fail(source, "tags must be an array of non-empty strings");
+	if ("stories" in metadata) {
+		const references = Array.isArray(metadata.stories) ? metadata.stories : [metadata.stories];
+		if (!references.length || references.some((ref) => typeof ref !== "string" || !ref.trim())) throw fail(source, "stories must be a relative path or a non-empty array of relative paths");
+	}
+	return {
+		body: normalized.slice(closing.index + closing[0].length).replace(/^\n/, ""),
+		metadata
+	};
+}
+async function resolveStoryAssociations(file, metadata, root) {
+	if ("stories" in metadata) {
+		const references = Array.isArray(metadata.stories) ? metadata.stories : [metadata.stories];
+		return Promise.all([...new Set(references)].map(async (ref) => {
+			if (path.isAbsolute(ref) || !/\.stories\.[jt]sx?$/.test(ref)) throw fail(file, `stories must reference a relative .stories.js, .jsx, .ts, or .tsx file: ${ref}`);
+			return localFile(path.resolve(path.dirname(file), ref), root, file, "story reference");
+		}));
+	}
+	if (!file.endsWith(".metadata.md")) return [];
+	const base = file.slice(0, -12);
+	const matches = [];
+	for (const extension of storyExtensions) {
+		const candidate = `${base}.stories.${extension}`;
+		if (await stat(candidate).then((value) => value.isFile(), () => false)) matches.push(candidate);
+	}
+	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 tree = markdown.parse(body);
+	const nodes = [];
+	visit(tree, (node) => {
+		if (node.type === "image" || node.type === "link" || node.type === "definition") nodes.push(node);
+	});
+	const assets = [];
+	for (const node of nodes) {
+		const url = node.url;
+		if (!url || /^(?:[a-z][a-z\d+.-]*:|\/|#|\?)/i.test(url)) continue;
+		const [, pathname, suffix = ""] = /^([^?#]*)(.*)$/.exec(url);
+		let decoded;
+		try {
+			decoded = decodeURIComponent(pathname);
+		} catch {
+			throw fail(file, `invalid local URL: ${url}`);
+		}
+		const asset = await localFile(path.resolve(path.dirname(file), decoded), 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({
+			file: asset,
+			suffix,
+			token
+		});
+		node.url = token;
+	}
+	const first = tree.children[0];
+	const heading = standalone && first?.type === "heading" && first.depth === 1 ? markdown.stringify({
+		...tree,
+		children: [first, ...tree.children.filter((node) => node.type === "definition")]
+	}) : void 0;
+	if (heading) tree.children.shift();
+	return {
+		markdown: markdown.stringify(tree),
+		assets,
+		heading
+	};
+}
+async function discover({ root, patterns, output }) {
+	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,
+		absolute: true,
+		onlyFiles: true,
+		expandDirectories: false,
+		followSymbolicLinks: false,
+		ignore: [
+			"**/node_modules/**",
+			"**/.git/**",
+			"**/storybook-static/**",
+			...path.relative(root, output).startsWith("..") ? [] : [`${slash(path.relative(root, output))}/**`]
+		]
+	});
+	return 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,
+			body,
+			source: slash(path.relative(root, file)),
+			title: metadata.title ?? `Documentation/${slash(path.relative(root, file)).replace(/\.md$/, "")}`,
+			metadata,
+			stories,
+			...content
+		};
+	}));
+}
+async function readMarkdown(file, root) {
+	root = path.resolve(root);
+	file = path.resolve(root, file);
+	if (!file.endsWith(".md")) throw fail(file, "Markdown file must have a .md extension");
+	await localFile(file, root, file, "Markdown file");
+	const original = await readFile(file, "utf8");
+	const { body, metadata } = parseMarkdown(original, file);
+	const stories = await resolveStoryAssociations(file, metadata, root);
+	return {
+		file,
+		original,
+		body,
+		metadata,
+		stories
+	};
+}
+//#endregion
+export { readMarkdown as a, parseMarkdown as i, fail as n, resolveStoryAssociations as o, localFile as r, slash as s, discover as t };

package/dist/index-BzM0tjFM.d.ts

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

package/dist/index.d.ts

@@ -1,10 +1,2 @@
-//#region src/index.d.ts
-export interface MarkdownOptions {
-  manifests?: boolean;
-  generatedDir?: string;
-  patterns: string[];
-  stylesheet?: string;
-  root?: string;
-  presentation?: string;
-}
-//#endregion
+import { t as MarkdownOptions } from "./index-BzM0tjFM.js";
+export { MarkdownOptions };

package/dist/node.d.ts

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

package/dist/node.js

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

package/dist/preset.d.ts

@@ -1,36 +1,15 @@
-import { MarkdownOptions } from "./index.js";
+import { t as MarkdownOptions } from "./index-BzM0tjFM.js";
+import { n as DiscoveredDocument, t as ContentOptions } from "./content-CKQsa_HK.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;
+  presets?: {
+    apply: (name: 'docs') => Promise<{
+      defaultName?: string;
+    }>;
+  };
 };
 type StoryEntry = string | {
   directory: string;

package/dist/preset.js

@@ -1,158 +1,9 @@
+import { n as fail, r as localFile, s as slash, t as discover } from "./content-CTcZAfoF.js";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { watch } from "chokidar";
 import picomatch from "picomatch";
-import { mkdir, readFile, readdir, realpath, stat, unlink, writeFile } from "node:fs/promises";
-import { glob } from "tinyglobby";
-import { isMap, parseDocument } from "yaml";
-import { unified } from "unified";
-import remarkParse from "remark-parse";
-import remarkGfm from "remark-gfm";
-import remarkStringify from "remark-stringify";
-import { visit } from "unist-util-visit";
-//#region src/content.ts
-const markdown = unified().use(remarkParse).use(remarkGfm).use(remarkStringify);
-const storyExtensions = [
-	"tsx",
-	"ts",
-	"jsx",
-	"js"
-];
-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) {
-	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");
-		return file;
-	} catch (error) {
-		if (error instanceof Error && error.message.startsWith("[storybook-addon-md]")) throw error;
-		throw Object.assign(fail(source, `missing ${kind}: ${file}`), { dependency: file });
-	}
-}
-function parseMarkdown(text, source) {
-	const normalized = text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
-	if (!normalized.startsWith("---\n")) return {
-		body: normalized,
-		metadata: {}
-	};
-	const end = /^---\s*$/gm;
-	end.lastIndex = 4;
-	const closing = end.exec(normalized);
-	if (!closing) throw fail(source, "frontmatter must end with ---");
-	const yaml = parseDocument(normalized.slice(4, closing.index), { uniqueKeys: true });
-	if (yaml.errors.length) throw fail(source, `invalid frontmatter: ${yaml.errors[0].message}`);
-	if (yaml.warnings.length) throw fail(source, `invalid frontmatter: ${yaml.warnings[0].message}`);
-	if (yaml.contents && !isMap(yaml.contents)) throw fail(source, "frontmatter must be a mapping");
-	let metadata;
-	try {
-		metadata = yaml.toJS({ maxAliasCount: 50 }) ?? {};
-		JSON.stringify(metadata, (_, value) => {
-			if (typeof value === "number" && !Number.isFinite(value)) throw new Error("metadata numbers must be finite");
-			return value;
-		});
-	} catch (error) {
-		throw fail(source, `invalid frontmatter: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	if (typeof metadata !== "object" || Array.isArray(metadata)) throw fail(source, "frontmatter must be a mapping");
-	for (const key of Object.keys(metadata)) if (!/^[a-z][a-z0-9_-]*$/.test(key)) throw fail(source, `frontmatter keys must be lowercase: ${key}`);
-	if ("title" in metadata && (typeof metadata.title !== "string" || !metadata.title.trim())) throw fail(source, "title must be a non-empty string");
-	if ("status" in metadata && (typeof metadata.status !== "string" || !metadata.status.trim())) throw fail(source, "status must be a non-empty string");
-	if ("tags" in metadata && (!Array.isArray(metadata.tags) || metadata.tags.some((tag) => typeof tag !== "string" || !tag.trim()))) throw fail(source, "tags must be an array of non-empty strings");
-	if ("stories" in metadata) {
-		const references = Array.isArray(metadata.stories) ? metadata.stories : [metadata.stories];
-		if (!references.length || references.some((ref) => typeof ref !== "string" || !ref.trim())) throw fail(source, "stories must be a relative path or a non-empty array of relative paths");
-	}
-	return {
-		body: normalized.slice(closing.index + closing[0].length).replace(/^\n/, ""),
-		metadata
-	};
-}
-async function associations(file, metadata, root) {
-	if ("stories" in metadata) {
-		const references = Array.isArray(metadata.stories) ? metadata.stories : [metadata.stories];
-		return Promise.all([...new Set(references)].map(async (ref) => {
-			if (path.isAbsolute(ref) || !/\.stories\.[jt]sx?$/.test(ref)) throw fail(file, `stories must reference a relative .stories.js, .jsx, .ts, or .tsx file: ${ref}`);
-			return localFile(path.resolve(path.dirname(file), ref), root, file, "story reference");
-		}));
-	}
-	if (!file.endsWith(".metadata.md")) return [];
-	const base = file.slice(0, -12);
-	const matches = [];
-	for (const extension of storyExtensions) {
-		const candidate = `${base}.stories.${extension}`;
-		if (await stat(candidate).then((value) => value.isFile(), () => false)) matches.push(candidate);
-	}
-	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) {
-	const tree = markdown.parse(body);
-	const nodes = [];
-	visit(tree, (node) => {
-		if (node.type === "image" || node.type === "link" || node.type === "definition") nodes.push(node);
-	});
-	const assets = [];
-	for (const node of nodes) {
-		const url = node.url;
-		if (!url || /^(?:[a-z][a-z\d+.-]*:|\/|#|\?)/i.test(url)) continue;
-		const [, pathname, suffix = ""] = /^([^?#]*)(.*)$/.exec(url);
-		let decoded;
-		try {
-			decoded = decodeURIComponent(pathname);
-		} catch {
-			throw fail(file, `invalid local URL: ${url}`);
-		}
-		const asset = await localFile(path.resolve(path.dirname(file), decoded), 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({
-			file: asset,
-			suffix,
-			token
-		});
-		node.url = token;
-	}
-	return {
-		markdown: markdown.stringify(tree),
-		assets
-	};
-}
-async function discover({ root, patterns, output }) {
-	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,
-		absolute: true,
-		onlyFiles: true,
-		expandDirectories: false,
-		followSymbolicLinks: false,
-		ignore: [
-			"**/node_modules/**",
-			"**/.git/**",
-			"**/storybook-static/**",
-			`${slash(path.relative(root, output))}/**`
-		]
-	});
-	return Promise.all(files.sort().filter((file) => file.endsWith(".md")).map(async (file) => {
-		await localFile(file, root, file, "Markdown file");
-		const original = await readFile(file, "utf8");
-		const { body, metadata } = parseMarkdown(original, file);
-		const stories = await associations(file, metadata, root);
-		const content = await resolveAssets(body, file, root);
-		return {
-			file,
-			original,
-			source: slash(path.relative(root, file)),
-			title: metadata.title ?? `Documentation/${slash(path.relative(root, file)).replace(/\.md$/, "")}`,
-			metadata,
-			stories,
-			...content
-		};
-	}));
-}
-//#endregion
+import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
 //#region src/generator.ts
 const attribute = (value) => value.replace(/[&"<>\r\n]/g, (character) => `&#${character.charCodeAt(0)};`);
 const id = (value) => createHash("sha256").update(value).digest("hex").slice(0, 16);
@@ -171,8 +22,8 @@ async function writeChanged(file, content) {
 }
 function documentModule(document, output) {
 	const imports = document.assets.map((asset, index) => `import asset${index} from ${JSON.stringify(`${specifier(output, assetPath(asset.file, output))}?url&no-inline`)};`);
-	const expression = document.assets.reduce((value, asset, index) => `${value}.split(${JSON.stringify(asset.token)}).join(asset${index}.replace('?no-inline', '') + ${JSON.stringify(asset.suffix)})`, JSON.stringify(document.markdown));
-	return `${imports.join("\n")}\nexport default { source: ${JSON.stringify(document.source)}, metadata: JSON.parse(${JSON.stringify(JSON.stringify(document.metadata))}), markdown: ${expression} };\n`;
+	const expression = (markdown) => document.assets.reduce((value, asset, index) => `${value}.split(${JSON.stringify(asset.token)}).join(asset${index}.replace('?no-inline', '') + ${JSON.stringify(asset.suffix)})`, JSON.stringify(markdown));
+	return `${imports.join("\n")}\nexport default { source: ${JSON.stringify(document.source)}, metadata: JSON.parse(${JSON.stringify(JSON.stringify(document.metadata))}), markdown: ${expression(document.markdown)}, heading: ${document.heading ? expression(document.heading) : "undefined"} };\n`;
 }
 async function generate(options) {
 	const { output, root, presentation, stylesheet } = options;
@@ -219,8 +70,8 @@ async function generate(options) {
 		if (group.story) imports.push(`import * as ComponentStories from ${JSON.stringify(specifier(output, group.story))};`);
 		if (presentation) imports.push(`import * as presentation from ${JSON.stringify(specifier(output, presentation))};`);
 		if (stylesheet) imports.push(`import ${JSON.stringify(specifier(output, stylesheet))};`);
-		const meta = group.story ? "<Meta of={ComponentStories} name=\"Markdown\" />" : `<Meta title="${attribute(group.title)}" />`;
-		files.set(pageFile(key), `${imports.join("\n")}\n\n${meta}\n\n<Documentation documents={[${group.documents.map((_, index) => `document${index}`).join(", ")}]} attached={${Boolean(group.story)}} title={${JSON.stringify(group.title ?? "")}}${presentation ? " presentation={presentation}" : ""} />\n`);
+		const meta = group.story ? `<Meta of={ComponentStories} name="${attribute(options.docsName ?? "Docs")}" />` : `<Meta title="${attribute(group.title)}" />`;
+		files.set(pageFile(key), `${imports.join("\n")}\n\n${meta}\n\n<Documentation documents={[${group.documents.map((_, index) => `document${index}`).join(", ")}]} attached={${Boolean(group.story)}} title={${JSON.stringify(group.title ?? "")}} tagFields={${JSON.stringify(options.tagFields ?? [])}}${presentation ? " presentation={presentation}" : ""} />\n`);
 	}
 	files.set("status.js", "export {};\n");
 	await mkdir(output, { recursive: true });
@@ -281,12 +132,14 @@ function settings(options) {
 	const configDir = path.resolve(options.configDir);
 	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");
 	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 {
 		root,
 		output: path.join(process.cwd(), generatedDir, createHash("sha256").update(configDir).digest("hex").slice(0, 12)),
 		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
 	};
@@ -294,7 +147,11 @@ function settings(options) {
 async function stories(existing = [], options) {
 	const key = path.resolve(options.configDir);
 	if (!sessions.has(key)) {
-		const config = settings(options);
+		const docs = await options.presets?.apply("docs");
+		const config = {
+			...settings(options),
+			docsName: docs?.defaultName ?? "Docs"
+		};
 		sessions.set(key, {
 			config,
 			ready: generate(config)

package/dist/runtime.d.ts

@@ -3,6 +3,7 @@ import { ComponentType, ReactNode } from "react";
 interface MarkdownDocument {
   source: string;
   markdown: string;
+  heading?: string;
   metadata: Record<string, unknown>;
 }
 interface LayoutProps {
@@ -11,6 +12,8 @@ interface LayoutProps {
   attached: boolean;
   children: ReactNode;
   examples: ReactNode;
+  heading?: ReactNode;
+  tagFields?: string[];
 }
 interface Presentation {
   Layout?: ComponentType<LayoutProps>;
@@ -19,12 +22,13 @@ interface Presentation {
 //#endregion
 //#region src/runtime.d.ts
 export declare function DefaultMarkdownRenderer({ markdown }: MarkdownDocument): import("react").JSX.Element;
-export declare function DefaultLayout({ documents, title, attached, children, examples }: LayoutProps): import("react").JSX.Element;
-export declare function Documentation({ documents, title, attached, presentation }: {
+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 }: {
   documents: MarkdownDocument[];
   title: string;
   attached?: boolean;
   presentation?: Presentation;
+  tagFields?: string[];
 }): import("react").JSX.Element;
 //#endregion
 export type { LayoutProps, MarkdownDocument, Presentation };

package/dist/runtime.js

@@ -15,18 +15,21 @@ function DefaultMarkdownRenderer({ markdown }) {
 		children: markdown
 	});
 }
-function DefaultLayout({ documents, title, attached, children, examples }) {
-	const tags = [...new Set(documents.flatMap(({ metadata }) => Array.isArray(metadata.tags) ? metadata.tags : []))];
+function DefaultLayout({ documents, title, attached, children, examples, heading, tagFields = [] }) {
+	const tags = [...new Set(documents.flatMap(({ metadata }) => ["tags", ...tagFields].flatMap((field) => {
+		const value = metadata[field];
+		return (Array.isArray(value) ? value : [value]).filter((item) => typeof item === "string" && Boolean(item.trim()));
+	})))];
 	const statuses = [...new Set(documents.flatMap(({ metadata }) => typeof metadata.status === "string" ? [metadata.status] : []))];
 	return /* @__PURE__ */ jsxs(Fragment, { children: [
 		/* @__PURE__ */ jsx("div", {
 			className: "storybook-addon-md-title",
-			children: attached ? /* @__PURE__ */ jsx(Title, {}) : /* @__PURE__ */ jsx("h1", { children: title.split("/").at(-1) })
+			children: attached ? /* @__PURE__ */ jsx(Title, {}) : heading ?? /* @__PURE__ */ jsx("h1", { children: title.split("/").at(-1) })
 		}),
 		(tags.length > 0 || statuses.length > 0) && /* @__PURE__ */ jsxs("ul", {
 			className: "storybook-addon-md-tags",
 			"aria-label": "Documentation tags",
-			children: [tags.map((tag) => /* @__PURE__ */ jsx("li", {
+			children: [tags.filter((tag) => !statuses.includes(tag)).map((tag) => /* @__PURE__ */ jsx("li", {
 				className: "storybook-addon-md-tag",
 				children: tag
 			}, `tag:${tag}`)), statuses.map((status) => /* @__PURE__ */ jsx("li", {
@@ -39,7 +42,7 @@ function DefaultLayout({ documents, title, attached, children, examples }) {
 		examples
 	] });
 }
-function Documentation({ documents, title, attached = false, presentation = {} }) {
+function Documentation({ documents, title, attached = false, presentation = {}, tagFields = [] }) {
 	const theme = useTheme();
 	const defaults = {
 		"--sbmd-native-color": theme.color.defaultText,
@@ -51,6 +54,11 @@ function Documentation({ documents, title, attached = false, presentation = {} }
 	};
 	const Layout = presentation.Layout ?? DefaultLayout;
 	const Renderer = presentation.MarkdownRenderer ?? DefaultMarkdownRenderer;
+	const first = documents[0];
+	const heading = !attached && first?.heading ? /* @__PURE__ */ jsx(Renderer, {
+		...first,
+		markdown: first.heading
+	}) : void 0;
 	return /* @__PURE__ */ jsx("div", {
 		className: "storybook-addon-md-page",
 		style: defaults,
@@ -63,6 +71,8 @@ function Documentation({ documents, title, attached = false, presentation = {} }
 				/* @__PURE__ */ jsx(Controls, {}),
 				/* @__PURE__ */ jsx(Stories, { includePrimary: false })
 			] }) : null,
+			heading,
+			tagFields,
 			children: documents.map((document) => /* @__PURE__ */ jsx("div", {
 				className: "storybook-addon-md",
 				children: /* @__PURE__ */ jsx(Renderer, { ...document })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storybook-addon-md",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Discover ordinary Markdown and render it in Storybook Docs.",
   "keywords": [
     "docs",
@@ -36,6 +36,10 @@
       "types": "./dist/runtime.d.ts",
       "default": "./dist/runtime.js"
     },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "node": "./dist/node.js"
+    },
     "./package.json": "./package.json",
     "./styles.css": "./dist/styles.css"
   },