storybook-addon-md 0.8.0 → 0.9.0

package/CHANGELOG.md

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

package/README.md

@@ -204,10 +204,12 @@ By default every relative link is bundled as an asset, so a link to another Mark
 }
 ```
 
-| 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.           |
+| 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.
 

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/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,16 +36,35 @@ function Blockquote({ children, ...props }) {
 		}), content]
 	});
 }
-function Anchor({ href, target, ...props }) {
-	if (!href?.startsWith("?path=")) return /* @__PURE__ */ jsx("a", {
+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: target ?? "_blank",
+		rel: rel ?? "noopener noreferrer",
+		"data-link": "external"
 	});
 	return /* @__PURE__ */ jsx("a", {
 		...props,
-		href: new URL(href, new URL("./", window.location.href)).href,
-		target: target ?? "_top"
+		href,
+		target,
+		rel
 	});
 }
 function DefaultMarkdownRenderer({ markdown }) {
@@ -132,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.8.0",
+  "version": "0.9.0",
   "description": "Discover ordinary Markdown and render it in Storybook Docs.",
   "keywords": [
     "docs",