diff --git a/astro.config.mjs b/astro.config.mjs
index 1ab6cd27..5118c6a9 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -7,23 +7,26 @@ import { defineConfig } from "astro/config";
 import astroInference from "astro-inference";
 import pagefind from "astro-pagefind";
 import baseConfig from "./astro.base.config.mjs";
+import { rehypeCodeCopy } from "./src/lib/rehype-code-copy.mjs";
 import { remarkReadingTime } from "./src/lib/remark-reading-time.mjs";
 
+const markdownProcessor = () =>
+	unified({
+		remarkPlugins: [remarkReadingTime],
+		rehypePlugins: [rehypeCodeCopy],
+	});
+
 // https://astro.build/config
 export default defineConfig({
 	site: "https://fastify.dev",
 	base: baseConfig.base,
 	outDir: "./build",
 	markdown: {
-		processor: unified({
-			remarkPlugins: [remarkReadingTime],
-		}),
+		processor: markdownProcessor(),
 	},
 	integrations: [
 		mdx({
-			processor: unified({
-				remarkPlugins: [remarkReadingTime],
-			}),
+			processor: markdownProcessor(),
 		}),
 		sitemap(),
 		pagefind(),
diff --git a/src/assets/icons/check.svg b/src/assets/icons/check.svg
new file mode 100644
index 00000000..90a705f4
--- /dev/null
+++ b/src/assets/icons/check.svg
@@ -0,0 +1,13 @@
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="1.75"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M20 6 9 17l-5-5" />
+</svg>
diff --git a/src/assets/icons/copy.svg b/src/assets/icons/copy.svg
new file mode 100644
index 00000000..6ca50be3
--- /dev/null
+++ b/src/assets/icons/copy.svg
@@ -0,0 +1,14 @@
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="1.75"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <rect width="14" height="14" x="8" y="8" rx="2" />
+  <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />
+</svg>
diff --git a/src/components/CodeTabs.astro b/src/components/CodeTabs.astro
index 5edb2004..f3638e86 100644
--- a/src/components/CodeTabs.astro
+++ b/src/components/CodeTabs.astro
@@ -1,6 +1,6 @@
 ---
 import { Code } from "astro:components";
-import Icon from "~/components/Icon.astro";
+import CopyButton from "~/components/CopyButton.astro";
 
 interface Tab {
 	label: string;
@@ -14,90 +14,81 @@ interface Props {
 }
 const { tabs, title, id } = Astro.props;
 ---
-<div class="overflow-hidden rounded-xl border border-border bg-surface" data-codetabs>
-  <div class="flex items-center justify-between border-b border-border bg-surface-2 px-2">
-    <div class="flex" role="tablist" aria-label={title}>
-      {tabs.map((tab, i) => (
-        <button
-          type="button"
-          role="tab"
-          id={`${id}-tab-${i}`}
-          aria-selected={i === 0 ? 'true' : 'false'}
-          aria-controls={`${id}-panel-${i}`}
-          data-tab={i}
-          class:list={[
-            'relative px-4 py-2.5 font-mono text-xs transition-colors',
-            i === 0 ? 'text-amber' : 'text-muted hover:text-fg',
-          ]}
-        >
-          {tab.label}
-          <span
-            data-tab-underline
-            class:list={['absolute inset-x-2 -bottom-px h-px', i === 0 ? 'bg-amber' : 'bg-transparent']}
-          ></span>
-        </button>
-      ))}
-    </div>
-    <button
-      type="button"
-      data-copy
-      class="mr-1 flex items-center gap-1.5 rounded-md px-2.5 py-1.5 font-mono text-xs text-muted transition-colors hover:text-fg"
-      aria-label="Copy code"
-    >
-      <Icon name="copy" size={14} />
-      <span data-copy-label>Copy</span>
-    </button>
-  </div>
+<div class="overflow-hidden rounded-xl border border-border bg-surface" data-codetabs data-copy-root={id}>
+	<div class="flex items-center justify-between border-b border-border bg-surface-2 px-2">
+		<div class="flex" role="tablist" aria-label={title}>
+			{tabs.map((tab, i) => (
+				<button
+					type="button"
+					role="tab"
+					id={`${id}-tab-${i}`}
+					aria-selected={i === 0 ? "true" : "false"}
+					aria-controls={`${id}-panel-${i}`}
+					data-tab={i}
+					class:list={[
+						"relative px-4 py-2.5 font-mono text-xs transition-colors",
+						i === 0 ? "text-amber" : "text-muted hover:text-fg",
+					]}
+				>
+					{tab.label}
+					<span
+						data-tab-underline
+						class:list={[
+							"absolute inset-x-2 -bottom-px h-px",
+							i === 0 ? "bg-amber" : "bg-transparent",
+						]}
+					/>
+				</button>
+			))}
+		</div>
+		<CopyButton
+			variant="label-swap"
+			ariaLabel="Copy code"
+			textSelector="[data-panel]:not(.hidden) [data-raw]"
+			class="mr-1 px-2.5 py-1.5 font-mono text-xs text-muted hover:text-fg"
+		/>
+	</div>
 
-  {tabs.map((tab, i) => (
-    <div
-      role="tabpanel"
-      id={`${id}-panel-${i}`}
-      aria-labelledby={`${id}-tab-${i}`}
-      data-panel={i}
-      class:list={['overflow-x-auto p-4 text-sm', i === 0 ? '' : 'hidden']}
-    >
-      <div class="hidden" data-raw set:text={tab.code}></div>
-      <Code code={tab.code} lang={tab.lang as any} themes={{ light: "github-light", dark: "github-dark" }} defaultColor="dark" />
-    </div>
-  ))}
+	{tabs.map((tab, i) => (
+		<div
+			role="tabpanel"
+			id={`${id}-panel-${i}`}
+			aria-labelledby={`${id}-tab-${i}`}
+			data-panel={i}
+			class:list={["overflow-x-auto p-4 text-sm", i === 0 ? "" : "hidden"]}
+		>
+			<div class="hidden" data-raw set:text={tab.code} />
+			<Code
+				code={tab.code}
+				lang={tab.lang as any}
+				themes={{ light: "github-light", dark: "github-dark" }}
+				defaultColor="dark"
+			/>
+		</div>
+	))}
 </div>
 
 <script>
-  document.querySelectorAll('[data-codetabs]').forEach((root) => {
-    const tabs = root.querySelectorAll<HTMLButtonElement>('[data-tab]');
-    const panels = root.querySelectorAll<HTMLElement>('[data-panel]');
-    const underlines = root.querySelectorAll<HTMLElement>('[data-tab-underline]');
+	document.querySelectorAll("[data-codetabs]").forEach((root) => {
+		const tabs = root.querySelectorAll<HTMLButtonElement>("[data-tab]");
+		const panels = root.querySelectorAll<HTMLElement>("[data-panel]");
+		const underlines = root.querySelectorAll<HTMLElement>("[data-tab-underline]");
 
-    tabs.forEach((tab) => {
-      tab.addEventListener('click', () => {
-        const idx = tab.dataset.tab;
-        tabs.forEach((t, i) => {
-          const active = String(i) === idx;
-          t.setAttribute('aria-selected', active ? 'true' : 'false');
-          t.classList.toggle('text-amber', active);
-          t.classList.toggle('text-muted', !active);
-          underlines[i]?.classList.toggle('bg-amber', active);
-          underlines[i]?.classList.toggle('bg-transparent', !active);
-        });
-        panels.forEach((p, i) => {
-          p.classList.toggle('hidden', String(i) !== idx);
-        });
-      });
-    });
-
-    const copyBtn = root.querySelector<HTMLButtonElement>('[data-copy]');
-    const label = root.querySelector('[data-copy-label]');
-    copyBtn?.addEventListener('click', async () => {
-      const visible = root.querySelector<HTMLElement>('[data-panel]:not(.hidden)');
-      const raw = visible?.querySelector('[data-raw]')?.textContent ?? '';
-      try {
-        await navigator.clipboard.writeText(raw);
-        if (label) {
-          label.textContent = 'Copied';
-          setTimeout(() => (label.textContent = 'Copy'), 1600);
-        }
-      } catch (e) {}
-    });
-  });
+		tabs.forEach((tab) => {
+			tab.addEventListener("click", () => {
+				const idx = tab.dataset.tab;
+				tabs.forEach((t, i) => {
+					const active = String(i) === idx;
+					t.setAttribute("aria-selected", active ? "true" : "false");
+					t.classList.toggle("text-amber", active);
+					t.classList.toggle("text-muted", !active);
+					underlines[i]?.classList.toggle("bg-amber", active);
+					underlines[i]?.classList.toggle("bg-transparent", !active);
+				});
+				panels.forEach((p, i) => {
+					p.classList.toggle("hidden", String(i) !== idx);
+				});
+			});
+		});
+	});
 </script>
diff --git a/src/components/CopyButton.astro b/src/components/CopyButton.astro
new file mode 100644
index 00000000..ab393d65
--- /dev/null
+++ b/src/components/CopyButton.astro
@@ -0,0 +1,56 @@
+---
+import CheckIcon from "~/assets/icons/check.svg";
+import CopyIcon from "~/assets/icons/copy.svg";
+
+interface Props {
+	text?: string;
+	textSelector?: string;
+	variant?: "icon-swap" | "label-swap";
+	copyLabel?: string;
+	copiedLabel?: string;
+	ariaLabel?: string;
+	class?: string;
+}
+
+const {
+	text,
+	textSelector,
+	variant = "icon-swap",
+	copyLabel = "Copy",
+	copiedLabel = "Copied",
+	ariaLabel = "Copy code",
+	class: className = "",
+} = Astro.props;
+---
+
+<button
+	type="button"
+	data-copy-btn
+	data-copy-text={text}
+	data-copy-target={textSelector}
+	data-copy-label={copyLabel}
+	data-copied-label={copiedLabel}
+	aria-label={ariaLabel}
+	class:list={[
+		"inline-flex items-center gap-1.5 rounded-md transition-colors",
+		className,
+	]}
+>
+	{
+		variant === "icon-swap" ? (
+			<>
+				<span data-copy-idle>
+					<CopyIcon width={14} height={14} aria-hidden="true" />
+				</span>
+				<span data-copy-done class="hidden text-amber">
+					<CheckIcon width={14} height={14} aria-hidden="true" />
+				</span>
+			</>
+		) : (
+			<>
+				<CopyIcon width={14} height={14} aria-hidden="true" />
+				<span data-copy-label-text>{copyLabel}</span>
+			</>
+		)
+	}
+</button>
diff --git a/src/components/DocsShell.astro b/src/components/DocsShell.astro
index 1fdc934f..dc1ad9b2 100644
--- a/src/components/DocsShell.astro
+++ b/src/components/DocsShell.astro
@@ -1,6 +1,7 @@
 ---
 import { getCollection } from "astro:content";
 import type { MarkdownHeading } from "astro";
+import CopyButton from "~/components/CopyButton.astro";
 import DocsNav from "~/components/DocsNav.astro";
 import Icon from "~/components/Icon.astro";
 import TableOfContents from "~/components/TableOfContents.astro";
@@ -293,6 +294,13 @@ const markdownUrl = withBase(`/docs/${markdownSlug}.md`);
   </div>
 </div>
 
+<template data-docs-copy-template>
+  <CopyButton
+    ariaLabel="Copy code to clipboard"
+    class="docs-copy-btn"
+  />
+</template>
+
 <script>
   import { afterVersion, withBase } from "~/lib/href";
 
@@ -349,4 +357,19 @@ const markdownUrl = withBase(`/docs/${markdownSlug}.md`);
 
     for (const heading of headings) observer.observe(heading);
   }
+
+  const copyTemplate = document.querySelector<HTMLTemplateElement>(
+    "[data-docs-copy-template]",
+  );
+  const copySource =
+    copyTemplate?.content.querySelector<HTMLButtonElement>("[data-copy-btn]");
+  if (copySource) {
+    document
+      .querySelectorAll<HTMLElement>("article.prose-fastify .docs-pre-wrap")
+      .forEach((wrapper) => {
+        if (wrapper.querySelector(":scope > [data-copy-btn]")) return;
+        const button = copySource.cloneNode(true);
+        if (button instanceof HTMLButtonElement) wrapper.appendChild(button);
+      });
+  }
 </script>
diff --git a/src/components/Icon.astro b/src/components/Icon.astro
index 42422743..71c1cec6 100644
--- a/src/components/Icon.astro
+++ b/src/components/Icon.astro
@@ -7,9 +7,7 @@ import {
 	AlertTriangle,
 	ArrowRight,
 	Braces,
-	Check,
 	Clock,
-	Copy,
 	ExternalLink,
 	FileText,
 	Heart,
@@ -45,8 +43,6 @@ const lucide: Record<string, any> = {
 	search: Search,
 	sun: Sun,
 	moon: Moon,
-	copy: Copy,
-	check: Check,
 	external: ExternalLink,
 	menu: Menu,
 	close: X,
diff --git a/src/components/InstallCommand.astro b/src/components/InstallCommand.astro
index 90ccf789..00599834 100644
--- a/src/components/InstallCommand.astro
+++ b/src/components/InstallCommand.astro
@@ -1,41 +1,18 @@
 ---
-import Icon from "~/components/Icon.astro";
+import CopyButton from "~/components/CopyButton.astro";
 
 interface Props {
 	command?: string;
 }
 const { command = "npm install fastify" } = Astro.props;
 ---
-<div class="inline-flex items-center gap-3 rounded-lg border border-white/10 bg-[#0c0f13] px-4 py-3 font-mono text-sm shadow-sm" data-install>
-  <span class="select-none text-amber">$</span>
-  <code class="text-[#c7cdd4]" data-install-cmd>{command}</code>
-  <button
-    type="button"
-    data-install-copy
-    class="ml-2 rounded-md border border-white/10 p-1.5 text-[#8b95a1] transition-colors hover:text-white"
-    aria-label="Copy install command"
-  >
-    <span data-install-idle><Icon name="copy" size={14} /></span>
-    <span data-install-done class="hidden text-amber"><Icon name="check" size={14} /></span>
-  </button>
+<div class="inline-flex items-center gap-3 rounded-lg border border-white/10 bg-[#0c0f13] px-4 py-3 font-mono text-sm shadow-sm" data-install data-copy-root>
+	<span class="select-none text-amber">$</span>
+	<code class="text-[#c7cdd4]">{command}</code>
+	<CopyButton
+		text={command}
+		variant="icon-swap"
+		ariaLabel="Copy install command"
+		class="ml-2 rounded-md border border-white/10 p-1.5 text-[#8b95a1] hover:text-white"
+	/>
 </div>
-
-<script>
-  document.querySelectorAll('[data-install]').forEach((root) => {
-    const btn = root.querySelector('[data-install-copy]');
-    const cmd = root.querySelector('[data-install-cmd]')?.textContent ?? '';
-    const idle = root.querySelector('[data-install-idle]');
-    const done = root.querySelector('[data-install-done]');
-    btn?.addEventListener('click', async () => {
-      try {
-        await navigator.clipboard.writeText(cmd);
-        idle?.classList.add('hidden');
-        done?.classList.remove('hidden');
-        setTimeout(() => {
-          idle?.classList.remove('hidden');
-          done?.classList.add('hidden');
-        }, 1600);
-      } catch (e) {}
-    });
-  });
-</script>
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 8cbf5da1..c9b8d905 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -79,9 +79,12 @@ const jsonLd = JSON.stringify({
 
     <script>
       import { formatSiUnit } from 'format-si-unit';
+      import { initCopyButtons } from '~/lib/copy';
       import { getRepoStars } from '~/services/github';
       import { getMonthlyDownloads } from '~/services/npm';
 
+      initCopyButtons();
+
       const applyTheme = (theme: string) => {
         if (theme === 'light') {
           document.documentElement.setAttribute('data-theme', 'light');
diff --git a/src/lib/copy.ts b/src/lib/copy.ts
new file mode 100644
index 00000000..304c5a8a
--- /dev/null
+++ b/src/lib/copy.ts
@@ -0,0 +1,89 @@
+const COPY_REVERT_MS = 1600;
+const COPY_BTN_SELECTOR = "[data-copy-btn]";
+const resetTimers = new WeakMap<HTMLButtonElement, number>();
+
+let initialized = false;
+let announcer: HTMLElement | null = null;
+
+function resolveCopyText(button: HTMLButtonElement): string {
+	const literal = button.getAttribute("data-copy-text");
+	if (literal !== null) return literal;
+
+	const root = button.closest<HTMLElement>("[data-copy-root]");
+	const targetSelector = button.getAttribute("data-copy-target");
+	if (root && targetSelector) {
+		return root.querySelector<HTMLElement>(targetSelector)?.textContent ?? "";
+	}
+
+	const code =
+		root?.querySelector<HTMLElement>("pre code") ??
+		root?.querySelector<HTMLElement>("pre") ??
+		root?.querySelector<HTMLElement>("code");
+	return code?.textContent ?? "";
+}
+
+function getAnnouncer(): HTMLElement {
+	if (announcer) return announcer;
+
+	announcer = document.createElement("span");
+	announcer.className = "sr-only";
+	announcer.setAttribute("aria-live", "polite");
+	announcer.setAttribute("aria-atomic", "true");
+	document.body.appendChild(announcer);
+	return announcer;
+}
+
+function announce(message: string): void {
+	const region = getAnnouncer();
+	region.textContent = "";
+	window.requestAnimationFrame(() => {
+		region.textContent = message;
+	});
+}
+
+function showCopied(button: HTMLButtonElement): void {
+	const idle = button.querySelector<HTMLElement>("[data-copy-idle]");
+	const done = button.querySelector<HTMLElement>("[data-copy-done]");
+	const label = button.querySelector<HTMLElement>("[data-copy-label-text]");
+	const copyLabel = button.dataset.copyLabel ?? "Copy";
+	const copiedLabel = button.dataset.copiedLabel ?? "Copied";
+
+	const currentTimer = resetTimers.get(button);
+	if (currentTimer !== undefined) window.clearTimeout(currentTimer);
+
+	idle?.classList.add("hidden");
+	done?.classList.remove("hidden");
+	if (label) label.textContent = copiedLabel;
+	announce(copiedLabel);
+
+	const timer = window.setTimeout(() => {
+		idle?.classList.remove("hidden");
+		done?.classList.add("hidden");
+		if (label) label.textContent = copyLabel;
+		resetTimers.delete(button);
+	}, COPY_REVERT_MS);
+	resetTimers.set(button, timer);
+}
+
+async function handleCopyClick(event: MouseEvent): Promise<void> {
+	if (!(event.target instanceof Element)) return;
+	const button = event.target.closest<HTMLButtonElement>(COPY_BTN_SELECTOR);
+	if (!button) return;
+
+	const text = resolveCopyText(button);
+	if (!text) return;
+
+	try {
+		await navigator.clipboard.writeText(text);
+		showCopied(button);
+	} catch (_) {
+		// Clipboard access can be denied by the browser or user.
+	}
+}
+
+export function initCopyButtons(): void {
+	if (initialized) return;
+	initialized = true;
+	getAnnouncer();
+	document.addEventListener("click", handleCopyClick);
+}
diff --git a/src/lib/rehype-code-copy.mjs b/src/lib/rehype-code-copy.mjs
new file mode 100644
index 00000000..6e0744d4
--- /dev/null
+++ b/src/lib/rehype-code-copy.mjs
@@ -0,0 +1,51 @@
+function hasClass(node, className) {
+	const classes = node.properties?.className;
+	return Array.isArray(classes) && classes.includes(className);
+}
+
+function countLines(node) {
+	let highlightedLines = 0;
+	let text = "";
+
+	const walk = (current) => {
+		if (current.type === "text") {
+			text += current.value;
+			return;
+		}
+		if (current.type !== "element") return;
+		if (hasClass(current, "line")) highlightedLines += 1;
+		for (const child of current.children) walk(child);
+	};
+
+	walk(node);
+	if (highlightedLines > 0) return highlightedLines;
+	return text.replace(/\n$/, "").split("\n").length;
+}
+
+function wrapCodeBlocks(parent) {
+	for (let index = 0; index < parent.children.length; index += 1) {
+		const child = parent.children[index];
+		if (child.type !== "element") continue;
+
+		if (child.tagName === "pre") {
+			const lineCount = countLines(child);
+			parent.children[index] = {
+				type: "element",
+				tagName: "div",
+				properties: {
+					className: ["docs-pre-wrap"],
+					dataCopyRoot: "",
+					dataCodeLines: lineCount <= 1 ? "single" : "multiple",
+				},
+				children: [child],
+			};
+			continue;
+		}
+
+		wrapCodeBlocks(child);
+	}
+}
+
+export function rehypeCodeCopy() {
+	return wrapCodeBlocks;
+}
diff --git a/src/styles/prose.css b/src/styles/prose.css
index 7567d4d2..f9351b64 100644
--- a/src/styles/prose.css
+++ b/src/styles/prose.css
@@ -163,3 +163,47 @@
 	/* biome-ignore lint/complexity/noImportantStyles: override Shiki inline styles */
 	background: var(--shiki-light-bg) !important;
 }
+
+/* Keep the copy button visible while the inner <pre> scrolls horizontally. */
+.prose-fastify .docs-pre-wrap {
+	position: relative;
+	margin: 1.5rem 0;
+}
+.prose-fastify .docs-pre-wrap pre {
+	margin: 0;
+}
+.docs-copy-btn {
+	position: absolute;
+	top: 0.5rem;
+	right: 0.5rem;
+	z-index: 10;
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	padding: 0.375rem;
+	border-radius: 0.375rem;
+	color: #8b95a1;
+	background: rgba(12, 15, 19, 0.6);
+	border: 1px solid rgba(255, 255, 255, 0.08);
+	transition:
+		color 0.15s,
+		background 0.15s,
+		border-color 0.15s;
+	cursor: pointer;
+}
+.docs-copy-btn:hover {
+	color: #fff;
+	background: rgba(12, 15, 19, 0.85);
+	border-color: rgba(255, 255, 255, 0.15);
+}
+.docs-copy-btn:focus-visible {
+	outline: 2px solid var(--amber);
+	outline-offset: 2px;
+}
+.docs-copy-btn [data-copy-done] {
+	color: var(--amber);
+}
+.docs-pre-wrap[data-code-lines="single"] .docs-copy-btn {
+	top: 50%;
+	transform: translateY(-50%);
+}