From 156bbcbf3b3ef9aa3216ac2d63956eaa37575189 Mon Sep 17 00:00:00 2001
From: Max Farrell <maxffarrell@gmail.com>
Date: Wed, 13 May 2026 23:13:27 -0500
Subject: [PATCH 1/2] feat(docs): add clickable anchor links to MDX headings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Port of shadcn-ui/ui@bc2db187 — wraps h1–h6 MDX components with a
HeadingAnchor component that renders a clickable `#` link on hover,
leveraging the existing rehype-slug-generated IDs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/src/lib/components/markdown/h1.svelte    | 14 ++++++++---
 docs/src/lib/components/markdown/h2.svelte    | 13 ++++++++--
 docs/src/lib/components/markdown/h3.svelte    | 13 ++++++++--
 docs/src/lib/components/markdown/h4.svelte    | 18 +++++++++++---
 docs/src/lib/components/markdown/h5.svelte    | 18 +++++++++++---
 docs/src/lib/components/markdown/h6.svelte    | 18 +++++++++++---
 .../components/markdown/heading-anchor.svelte | 24 +++++++++++++++++++
 7 files changed, 102 insertions(+), 16 deletions(-)
 create mode 100644 docs/src/lib/components/markdown/heading-anchor.svelte

diff --git a/docs/src/lib/components/markdown/h1.svelte b/docs/src/lib/components/markdown/h1.svelte
index 6252cb19d..de960c8a2 100644
--- a/docs/src/lib/components/markdown/h1.svelte
+++ b/docs/src/lib/components/markdown/h1.svelte
@@ -1,10 +1,18 @@
 <script lang="ts">
 	import type { HTMLAttributes } from "svelte/elements";
 	import { cn } from "$lib/utils/styles.js";
+	import HeadingAnchor from "./heading-anchor.svelte";
 
-	let { class: className, children, ...restProps }: HTMLAttributes<HTMLHeadingElement> = $props();
+	let {
+		class: className,
+		children,
+		id,
+		...restProps
+	}: HTMLAttributes<HTMLHeadingElement> = $props();
 </script>
 
-<h1 class={cn("mt-2 scroll-m-20 text-4xl font-bold", className)} {...restProps}>
-	{@render children?.()}
+<h1 class={cn("mt-2 scroll-m-20 text-4xl font-bold", className)} {id} {...restProps}>
+	<HeadingAnchor {id}>
+		{@render children?.()}
+	</HeadingAnchor>
 </h1>
diff --git a/docs/src/lib/components/markdown/h2.svelte b/docs/src/lib/components/markdown/h2.svelte
index 7850db518..b3e20b063 100644
--- a/docs/src/lib/components/markdown/h2.svelte
+++ b/docs/src/lib/components/markdown/h2.svelte
@@ -1,8 +1,14 @@
 <script lang="ts">
 	import type { HTMLAttributes } from "svelte/elements";
 	import { cn } from "$lib/utils/styles.js";
+	import HeadingAnchor from "./heading-anchor.svelte";
 
-	let { class: className, children, ...restProps }: HTMLAttributes<HTMLHeadingElement> = $props();
+	let {
+		class: className,
+		children,
+		id,
+		...restProps
+	}: HTMLAttributes<HTMLHeadingElement> = $props();
 </script>
 
 <h2
@@ -10,7 +16,10 @@
 		"mt-12 scroll-m-[70px] text-[27px] font-semibold tracking-[-0.01em] first:mt-0",
 		className
 	)}
+	{id}
 	{...restProps}
 >
-	{@render children?.()}
+	<HeadingAnchor {id}>
+		{@render children?.()}
+	</HeadingAnchor>
 </h2>
diff --git a/docs/src/lib/components/markdown/h3.svelte b/docs/src/lib/components/markdown/h3.svelte
index b05d2a54b..f9fd63c8d 100644
--- a/docs/src/lib/components/markdown/h3.svelte
+++ b/docs/src/lib/components/markdown/h3.svelte
@@ -1,13 +1,22 @@
 <script lang="ts">
 	import type { HTMLAttributes } from "svelte/elements";
 	import { cn } from "$lib/utils/styles.js";
+	import HeadingAnchor from "./heading-anchor.svelte";
 
-	let { class: className, children, ...restProps }: HTMLAttributes<HTMLHeadingElement> = $props();
+	let {
+		class: className,
+		children,
+		id,
+		...restProps
+	}: HTMLAttributes<HTMLHeadingElement> = $props();
 </script>
 
 <h3
 	class={cn("mt-12 scroll-m-[70px] text-xl font-semibold tracking-tight", className)}
+	{id}
 	{...restProps}
 >
-	{@render children?.()}
+	<HeadingAnchor {id}>
+		{@render children?.()}
+	</HeadingAnchor>
 </h3>
diff --git a/docs/src/lib/components/markdown/h4.svelte b/docs/src/lib/components/markdown/h4.svelte
index f924d8274..50cdcee77 100644
--- a/docs/src/lib/components/markdown/h4.svelte
+++ b/docs/src/lib/components/markdown/h4.svelte
@@ -1,10 +1,22 @@
 <script lang="ts">
 	import type { HTMLAttributes } from "svelte/elements";
 	import { cn } from "$lib/utils/styles.js";
+	import HeadingAnchor from "./heading-anchor.svelte";
 
-	let { class: className, children, ...restProps }: HTMLAttributes<HTMLHeadingElement> = $props();
+	let {
+		class: className,
+		children,
+		id,
+		...restProps
+	}: HTMLAttributes<HTMLHeadingElement> = $props();
 </script>
 
-<h4 class={cn("-mb-2 mt-8 scroll-m-20 text-lg font-bold tracking-tight", className)} {...restProps}>
-	{@render children?.()}
+<h4
+	class={cn("-mb-2 mt-8 scroll-m-20 text-lg font-bold tracking-tight", className)}
+	{id}
+	{...restProps}
+>
+	<HeadingAnchor {id}>
+		{@render children?.()}
+	</HeadingAnchor>
 </h4>
diff --git a/docs/src/lib/components/markdown/h5.svelte b/docs/src/lib/components/markdown/h5.svelte
index b17c1b55c..e4f9a5438 100644
--- a/docs/src/lib/components/markdown/h5.svelte
+++ b/docs/src/lib/components/markdown/h5.svelte
@@ -1,10 +1,22 @@
 <script lang="ts">
 	import type { HTMLAttributes } from "svelte/elements";
 	import { cn } from "$lib/utils/styles.js";
+	import HeadingAnchor from "./heading-anchor.svelte";
 
-	let { class: className, children, ...restProps }: HTMLAttributes<HTMLHeadingElement> = $props();
+	let {
+		class: className,
+		children,
+		id,
+		...restProps
+	}: HTMLAttributes<HTMLHeadingElement> = $props();
 </script>
 
-<h5 class={cn("mt-8 scroll-m-20 text-lg font-semibold tracking-tight", className)} {...restProps}>
-	{@render children?.()}
+<h5
+	class={cn("mt-8 scroll-m-20 text-lg font-semibold tracking-tight", className)}
+	{id}
+	{...restProps}
+>
+	<HeadingAnchor {id}>
+		{@render children?.()}
+	</HeadingAnchor>
 </h5>
diff --git a/docs/src/lib/components/markdown/h6.svelte b/docs/src/lib/components/markdown/h6.svelte
index 98b5f3d7a..3a2621181 100644
--- a/docs/src/lib/components/markdown/h6.svelte
+++ b/docs/src/lib/components/markdown/h6.svelte
@@ -1,10 +1,22 @@
 <script lang="ts">
 	import type { HTMLAttributes } from "svelte/elements";
 	import { cn } from "$lib/utils/styles.js";
+	import HeadingAnchor from "./heading-anchor.svelte";
 
-	let { class: className, children, ...restProps }: HTMLAttributes<HTMLHeadingElement> = $props();
+	let {
+		class: className,
+		children,
+		id,
+		...restProps
+	}: HTMLAttributes<HTMLHeadingElement> = $props();
 </script>
 
-<h6 class={cn("mt-8 scroll-m-20 text-base font-semibold tracking-tight", className)} {...restProps}>
-	{@render children?.()}
+<h6
+	class={cn("mt-8 scroll-m-20 text-base font-semibold tracking-tight", className)}
+	{id}
+	{...restProps}
+>
+	<HeadingAnchor {id}>
+		{@render children?.()}
+	</HeadingAnchor>
 </h6>
diff --git a/docs/src/lib/components/markdown/heading-anchor.svelte b/docs/src/lib/components/markdown/heading-anchor.svelte
new file mode 100644
index 000000000..911e60bfb
--- /dev/null
+++ b/docs/src/lib/components/markdown/heading-anchor.svelte
@@ -0,0 +1,24 @@
+<script lang="ts">
+	import type { Snippet } from "svelte";
+
+	let {
+		id,
+		children,
+	}: {
+		id?: string;
+		children?: Snippet;
+	} = $props();
+</script>
+
+{#if id}
+	<a class="group no-underline" href="#{id}">
+		<span class="underline-offset-4 group-hover:underline">
+			{@render children?.()}
+		</span>
+		<span aria-hidden="true" class="ml-2 text-muted-foreground opacity-0 group-hover:opacity-100">
+			#
+		</span>
+	</a>
+{:else}
+	{@render children?.()}
+{/if}

From 61c44ec0d6d66d1de90b6fe0dadd51ba601c2f0d Mon Sep 17 00:00:00 2001
From: Max Farrell <maxffarrell@gmail.com>
Date: Wed, 13 May 2026 23:47:14 -0500
Subject: [PATCH 2/2] fix(docs): resolve type error in heading components for
 id prop
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

HTMLAttributes<HTMLHeadingElement> types id as string | null | undefined,
but HeadingAnchor expects string | undefined — coerce null to undefined.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/src/lib/components/markdown/h1.svelte | 2 +-
 docs/src/lib/components/markdown/h2.svelte | 2 +-
 docs/src/lib/components/markdown/h3.svelte | 2 +-
 docs/src/lib/components/markdown/h4.svelte | 2 +-
 docs/src/lib/components/markdown/h5.svelte | 2 +-
 docs/src/lib/components/markdown/h6.svelte | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/src/lib/components/markdown/h1.svelte b/docs/src/lib/components/markdown/h1.svelte
index de960c8a2..19dd868e1 100644
--- a/docs/src/lib/components/markdown/h1.svelte
+++ b/docs/src/lib/components/markdown/h1.svelte
@@ -12,7 +12,7 @@
 </script>
 
 <h1 class={cn("mt-2 scroll-m-20 text-4xl font-bold", className)} {id} {...restProps}>
-	<HeadingAnchor {id}>
+	<HeadingAnchor id={id ?? undefined}>
 		{@render children?.()}
 	</HeadingAnchor>
 </h1>
diff --git a/docs/src/lib/components/markdown/h2.svelte b/docs/src/lib/components/markdown/h2.svelte
index b3e20b063..6f70f2385 100644
--- a/docs/src/lib/components/markdown/h2.svelte
+++ b/docs/src/lib/components/markdown/h2.svelte
@@ -19,7 +19,7 @@
 	{id}
 	{...restProps}
 >
-	<HeadingAnchor {id}>
+	<HeadingAnchor id={id ?? undefined}>
 		{@render children?.()}
 	</HeadingAnchor>
 </h2>
diff --git a/docs/src/lib/components/markdown/h3.svelte b/docs/src/lib/components/markdown/h3.svelte
index f9fd63c8d..a9f515c94 100644
--- a/docs/src/lib/components/markdown/h3.svelte
+++ b/docs/src/lib/components/markdown/h3.svelte
@@ -16,7 +16,7 @@
 	{id}
 	{...restProps}
 >
-	<HeadingAnchor {id}>
+	<HeadingAnchor id={id ?? undefined}>
 		{@render children?.()}
 	</HeadingAnchor>
 </h3>
diff --git a/docs/src/lib/components/markdown/h4.svelte b/docs/src/lib/components/markdown/h4.svelte
index 50cdcee77..7f0ae4170 100644
--- a/docs/src/lib/components/markdown/h4.svelte
+++ b/docs/src/lib/components/markdown/h4.svelte
@@ -16,7 +16,7 @@
 	{id}
 	{...restProps}
 >
-	<HeadingAnchor {id}>
+	<HeadingAnchor id={id ?? undefined}>
 		{@render children?.()}
 	</HeadingAnchor>
 </h4>
diff --git a/docs/src/lib/components/markdown/h5.svelte b/docs/src/lib/components/markdown/h5.svelte
index e4f9a5438..516933552 100644
--- a/docs/src/lib/components/markdown/h5.svelte
+++ b/docs/src/lib/components/markdown/h5.svelte
@@ -16,7 +16,7 @@
 	{id}
 	{...restProps}
 >
-	<HeadingAnchor {id}>
+	<HeadingAnchor id={id ?? undefined}>
 		{@render children?.()}
 	</HeadingAnchor>
 </h5>
diff --git a/docs/src/lib/components/markdown/h6.svelte b/docs/src/lib/components/markdown/h6.svelte
index 3a2621181..69efa8842 100644
--- a/docs/src/lib/components/markdown/h6.svelte
+++ b/docs/src/lib/components/markdown/h6.svelte
@@ -16,7 +16,7 @@
 	{id}
 	{...restProps}
 >
-	<HeadingAnchor {id}>
+	<HeadingAnchor id={id ?? undefined}>
 		{@render children?.()}
 	</HeadingAnchor>
 </h6>