coder · tracyjohnsonux · Aug 26, 2026 · Aug 25, 2026 · Aug 25, 2026 · Aug 26, 2026
diff --git a/site/src/components/SettingsHeader/SettingsHeader.tsx b/site/src/components/SettingsHeader/SettingsHeader.tsx
@@ -1,7 +1,6 @@
 import { cva, type VariantProps } from "class-variance-authority";
-import { SquareArrowOutUpRightIcon } from "lucide-react";
 import type { FC, PropsWithChildren, ReactNode } from "react";
-import { Button } from "#/components/Button/Button";
+import { Link } from "#/components/Link/Link";
 import { cn } from "#/utils/cn";
 
 type SettingsHeaderProps = Readonly<
@@ -26,20 +25,22 @@ export const SettingsHeader: FC<SettingsHeaderProps> = ({
 };
 
 type SettingsHeaderDocsLinkProps = Readonly<
-	PropsWithChildren<{ href: string }>
+	PropsWithChildren<{
+		href: string;
+		context?: string;
+	}>
 >;
 export const SettingsHeaderDocsLink: FC<SettingsHeaderDocsLinkProps> = ({
 	href,
-	children = "Read the docs",
+	context,
+	children = "View docs",
 }) => {
 	return (
-		<Button asChild variant="outline">
-			<a href={href} target="_blank" rel="noreferrer">
-				<SquareArrowOutUpRightIcon />
-				{children}
-				<span className="sr-only"> (link opens in new tab)</span>
-			</a>
-		</Button>
+		<Link href={href} target="_blank" rel="noreferrer">
+			{children}
+			{context && <span className="sr-only"> {context}</span>}
+			<span className="sr-only"> (opens in new tab)</span>
+		</Link>
 	);
 };
 

diff --git a/site/src/pages/AISettingsPage/GatewayKeysPage/GatewayKeysPageView.stories.tsx b/site/src/pages/AISettingsPage/GatewayKeysPage/GatewayKeysPageView.stories.tsx
@@ -83,7 +83,7 @@ export const Paywall: Story = {
 		const cta = canvas.getByRole("link", { name: "Start trial for free" });
 		await expect(cta).toHaveAttribute("href", "/deployment/premium");
 		await expect(
-			canvas.getByRole("link", { name: /Read the docs/ }),
+			canvas.getByRole("link", { name: /View docs/ }),
 		).toHaveAttribute(
 			"href",
 			docs("/ai-coder/ai-gateway/standalone#create-a-gateway-key"),

diff --git a/site/src/pages/AISettingsPage/GatewayKeysPage/GatewayKeysPageView.tsx b/site/src/pages/AISettingsPage/GatewayKeysPage/GatewayKeysPageView.tsx
@@ -47,25 +47,21 @@ export const GatewayKeysPageView: FC<GatewayKeysPageViewProps> = ({
 		<div>
 			<SettingsHeader
 				actions={
-					<div className="flex flex-row gap-2 items-center">
-						<SettingsHeaderDocsLink
-							href={docs(
-								"/ai-coder/ai-gateway/standalone#create-a-gateway-key",
-							)}
-						/>
-						{!showPaywall && (
-							<Button variant="outline" onClick={onCreateKey}>
-								<PlusIcon />
-								Create key
-							</Button>
-						)}
-					</div>
+					!showPaywall && (
+						<Button variant="outline" onClick={onCreateKey}>
+							<PlusIcon />
+							Create key
+						</Button>
+					)
 				}
 			>
 				<SettingsHeaderTitle>AI Gateway Keys</SettingsHeaderTitle>
 				<SettingsHeaderDescription>
 					Keys authenticate standalone AI Gateway replicas to this deployment.
-					The key value is shown only once when created.
+					The key value is shown only once when created.{" "}
+					<SettingsHeaderDocsLink
+						href={docs("/ai-coder/ai-gateway/standalone#create-a-gateway-key")}
+					/>
 				</SettingsHeaderDescription>
 			</SettingsHeader>
 

diff --git a/site/src/pages/AuditPage/AuditPageView.stories.tsx b/site/src/pages/AuditPage/AuditPageView.stories.tsx
@@ -103,7 +103,7 @@ export const NotVisible: Story = {
 		const cta = canvas.getByRole("link", { name: "Start trial for free" });
 		await expect(cta).toHaveAttribute("href", "/deployment/premium");
 		await expect(
-			canvas.getByRole("link", { name: /Read the docs/ }),
+			canvas.getByRole("link", { name: /View docs/ }),
 		).toHaveAttribute("href", docs("/admin/security/audit-logs"));
 	},
 };

diff --git a/site/src/pages/AuditPage/AuditPageView.tsx b/site/src/pages/AuditPage/AuditPageView.tsx
@@ -51,18 +51,17 @@ export const AuditPageView: FC<AuditPageViewProps> = ({
 
 	return (
 		<Margins className="pb-12">
-			<PageHeader
-				actions={
-					<SettingsHeaderDocsLink href={docs("/admin/security/audit-logs")} />
-				}
-			>
+			<PageHeader>
 				<PageHeaderTitle>
 					<div className="flex flex-row gap-2 items-center">
 						<span>Audit</span>
 						<AuditHelpPopover />
 					</div>
 				</PageHeaderTitle>
-				<PageHeaderSubtitle>View events in your audit log.</PageHeaderSubtitle>
+				<PageHeaderSubtitle>
+					View events in your audit log.{" "}
+					<SettingsHeaderDocsLink href={docs("/admin/security/audit-logs")} />
+				</PageHeaderSubtitle>
 			</PageHeader>
 
 			{isAuditLogVisible ? (

diff --git a/site/src/pages/ConnectionLogPage/ConnectionLogPageView.stories.tsx b/site/src/pages/ConnectionLogPage/ConnectionLogPageView.stories.tsx
@@ -102,7 +102,7 @@ export const NotVisible: Story = {
 		const cta = canvas.getByRole("link", { name: "Start trial for free" });
 		await expect(cta).toHaveAttribute("href", "/deployment/premium");
 		await expect(
-			canvas.getByRole("link", { name: /Read the docs/ }),
+			canvas.getByRole("link", { name: /View docs/ }),
 		).toHaveAttribute("href", docs("/admin/monitoring/connection-logs"));
 	},
 };

diff --git a/site/src/pages/ConnectionLogPage/ConnectionLogPageView.tsx b/site/src/pages/ConnectionLogPage/ConnectionLogPageView.tsx
@@ -50,21 +50,18 @@ export const ConnectionLogPageView: FC<ConnectionLogPageViewProps> = ({
 
 	return (
 		<Margins className="pb-12">
-			<PageHeader
-				actions={
-					<SettingsHeaderDocsLink
-						href={docs("/admin/monitoring/connection-logs")}
-					/>
-				}
-			>
+			<PageHeader>
 				<PageHeaderTitle>
 					<div className="flex flex-row gap-2 items-center">
 						<span>Connection Log</span>
 						<ConnectionLogHelpPopover />
 					</div>
 				</PageHeaderTitle>
 				<PageHeaderSubtitle>
-					View workspace connection events.
+					View workspace connection events.{" "}
+					<SettingsHeaderDocsLink
+						href={docs("/admin/monitoring/connection-logs")}
+					/>
 				</PageHeaderSubtitle>
 			</PageHeader>
 

diff --git a/...rc/pages/DeploymentSettingsPage/AIGovernanceSettingsPage/AIGovernanceSettingsPageView.tsx b/...rc/pages/DeploymentSettingsPage/AIGovernanceSettingsPage/AIGovernanceSettingsPageView.tsx
@@ -29,16 +29,13 @@ export const AIGovernanceSettingsPageView: FC<
 			</SettingsHeader>
 
 			<div>
-				<SettingsHeader
-					actions={
-						<SettingsHeaderDocsLink href={docs("/ai-coder/ai-governance")} />
-					}
-				>
+				<SettingsHeader>
 					<SettingsHeaderTitle hierarchy="secondary" level="h2">
 						AI Gateway
 					</SettingsHeaderTitle>
 					<SettingsHeaderDescription>
-						Monitor and manage AI requests across your deployment.
+						Monitor and manage AI requests across your deployment.{" "}
+						<SettingsHeaderDocsLink href={docs("/ai-coder/ai-governance")} />
 					</SettingsHeaderDescription>
 				</SettingsHeader>
 

diff --git a/...ages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.stories.tsx b/...ages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.stories.tsx
@@ -58,7 +58,7 @@ export const NotEntitled: Story = {
 		const cta = canvas.getByRole("link", { name: "Start trial for free" });
 		await expect(cta).toHaveAttribute("href", "/deployment/premium");
 		await expect(
-			canvas.getByRole("link", { name: /Read the docs/ }),
+			canvas.getByRole("link", { name: /View docs/ }),
 		).toHaveAttribute("href", docs("/admin/setup/appearance"));
 		await expect(
 			canvas.queryByRole("form", { name: "Appearance settings" }),

diff --git a/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx b/site/src/pages/DeploymentSettingsPage/AppearanceSettingsPage/AppearanceSettingsPageView.tsx
@@ -49,14 +49,11 @@ export const AppearanceSettingsPageView: FC<
 
 	return (
 		<div>
-			<SettingsHeader
-				actions={
-					<SettingsHeaderDocsLink href={docs("/admin/setup/appearance")} />
-				}
-			>
+			<SettingsHeader>
 				<SettingsHeaderTitle>Appearance</SettingsHeaderTitle>
 				<SettingsHeaderDescription>
-					Customize the look and feel of your Coder deployment.
+					Customize the look and feel of your Coder deployment.{" "}
+					<SettingsHeaderDocsLink href={docs("/admin/setup/appearance")} />
 				</SettingsHeaderDescription>
 			</SettingsHeader>
 

diff --git a/.../DeploymentSettingsPage/ExternalAuthSettingsPage/ExternalAuthSettingsPageView.stories.tsx b/.../DeploymentSettingsPage/ExternalAuthSettingsPage/ExternalAuthSettingsPageView.stories.tsx
@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect, within } from "storybook/test";
+import { docs } from "#/utils/docs";
 import { ExternalAuthSettingsPageView } from "./ExternalAuthSettingsPageView";
 
 const meta: Meta<typeof ExternalAuthSettingsPageView> = {
@@ -49,6 +50,9 @@ export const Page: Story = {
 		await expect(
 			canvas.getByRole("link", { name: "Start trial for free" }),
 		).toHaveAttribute("href", "/deployment/premium");
+		await expect(
+			canvas.getByRole("link", { name: /View docs/ }),
+		).toHaveAttribute("href", docs("/admin/external-auth"));
 	},
 };
 

diff --git a/...rc/pages/DeploymentSettingsPage/ExternalAuthSettingsPage/ExternalAuthSettingsPageView.tsx b/...rc/pages/DeploymentSettingsPage/ExternalAuthSettingsPage/ExternalAuthSettingsPageView.tsx
@@ -33,13 +33,12 @@ export const ExternalAuthSettingsPageView: FC<
 > = ({ config, isEntitled, canViewPremium }) => {
 	return (
 		<>
-			<SettingsHeader
-				actions={<SettingsHeaderDocsLink href={docs("/admin/external-auth")} />}
-			>
+			<SettingsHeader>
 				<SettingsHeaderTitle>External Authentication</SettingsHeaderTitle>
 				<SettingsHeaderDescription>
 					Coder integrates with GitHub, GitLab, BitBucket, Azure Repos, and
-					OpenID Connect to authenticate developers with external services.
+					OpenID Connect to authenticate developers with external services.{" "}
+					<SettingsHeaderDocsLink href={docs("/admin/external-auth")} />
 				</SettingsHeaderDescription>
 			</SettingsHeader>
 

diff --git a/site/src/pages/DeploymentSettingsPage/IdpOrgSyncPage/IdpOrgSyncPage.tsx b/site/src/pages/DeploymentSettingsPage/IdpOrgSyncPage/IdpOrgSyncPage.tsx
@@ -70,19 +70,15 @@ const IdpOrgSyncPage: FC = () => {
 
 			<div>
 				<SettingsHeader
-					actions={
-						<div className="flex flex-row gap-2 items-center">
-							<SettingsHeaderDocsLink
-								href={docs("/admin/users/idp-sync#organization-sync")}
-							/>
-							<ExportPolicyButton syncSettings={settingsQuery.data} />
-						</div>
-					}
+					actions={<ExportPolicyButton syncSettings={settingsQuery.data} />}
 				>
 					<SettingsHeaderTitle>Organization IdP Sync</SettingsHeaderTitle>
 					<SettingsHeaderDescription>
 						Automatically assign users to an organization based on their IdP
-						claims.
+						claims.{" "}
+						<SettingsHeaderDocsLink
+							href={docs("/admin/users/idp-sync#organization-sync")}
+						/>
 					</SettingsHeaderDescription>
 				</SettingsHeader>
 				{!isIdpSyncEnabled ? (

diff --git a/.../src/pages/DeploymentSettingsPage/NetworkSettingsPage/NetworkSettingsPageView.stories.tsx b/.../src/pages/DeploymentSettingsPage/NetworkSettingsPage/NetworkSettingsPageView.stories.tsx
@@ -1,5 +1,7 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
 import type { SerpentGroup } from "#/api/typesGenerated";
+import { docs } from "#/utils/docs";
 import { NetworkSettingsPageView } from "./NetworkSettingsPageView";
 
 const group: SerpentGroup = {
@@ -67,4 +69,18 @@ const meta: Meta<typeof NetworkSettingsPageView> = {
 export default meta;
 type Story = StoryObj<typeof NetworkSettingsPageView>;
 
-export const Page: Story = {};
+export const Page: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		const docsLinks = canvas.getAllByRole("link", { name: /View docs/ });
+		await expect(docsLinks).toHaveLength(2);
+		await expect(docsLinks[0]).toHaveAttribute(
+			"href",
+			docs("/admin/networking"),
+		);
+		await expect(docsLinks[1]).toHaveAttribute(
+			"href",
+			docs("/admin/networking/port-forwarding"),
+		);
+	},
+};
diff --git a/site/src/pages/DeploymentSettingsPage/NetworkSettingsPage/NetworkSettingsPageView.tsx b/site/src/pages/DeploymentSettingsPage/NetworkSettingsPage/NetworkSettingsPageView.tsx
@@ -27,12 +27,14 @@ export const NetworkSettingsPageView: FC<NetworkSettingsPageViewProps> = ({
 }) => (
 	<div className="flex flex-col gap-12">
 		<div>
-			<SettingsHeader
-				actions={<SettingsHeaderDocsLink href={docs("/admin/networking")} />}
-			>
+			<SettingsHeader>
 				<SettingsHeaderTitle>Network</SettingsHeaderTitle>
 				<SettingsHeaderDescription>
-					Configure your deployment connectivity.
+					Configure your deployment connectivity.{" "}
+					<SettingsHeaderDocsLink
+						href={docs("/admin/networking")}
+						context="about deployment networking"
+					/>
 				</SettingsHeaderDescription>
 			</SettingsHeader>
 
@@ -44,19 +46,17 @@ export const NetworkSettingsPageView: FC<NetworkSettingsPageViewProps> = ({
 		</div>
 
 		<div>
-			<SettingsHeader
-				actions={
-					<SettingsHeaderDocsLink
-						href={docs("/admin/networking/port-forwarding")}
-					/>
-				}
-			>
+			<SettingsHeader>
 				<SettingsHeaderTitle level="h2" hierarchy="secondary">
 					Port Forwarding
 				</SettingsHeaderTitle>
 				<SettingsHeaderDescription>
 					Port forwarding lets developers securely access processes on their
-					Coder workspace from a local machine.
+					Coder workspace from a local machine.{" "}
+					<SettingsHeaderDocsLink
+						href={docs("/admin/networking/port-forwarding")}
+						context="about port forwarding"
+					/>
 				</SettingsHeaderDescription>
 			</SettingsHeader>
 

diff --git a/site/src/pages/DeploymentSettingsPage/NotificationsPage/NotificationEvents.stories.tsx b/site/src/pages/DeploymentSettingsPage/NotificationsPage/NotificationEvents.stories.tsx
@@ -1,9 +1,10 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { spyOn, userEvent, within } from "storybook/test";
+import { expect, spyOn, userEvent, within } from "storybook/test";
 import { API } from "#/api/api";
 import { selectTemplatesByGroup } from "#/api/queries/notifications";
 import type { DeploymentValues } from "#/api/typesGenerated";
 import { MockSystemNotificationTemplates } from "#/testHelpers/entities";
+import { docs } from "#/utils/docs";
 import { NotificationEvents } from "./NotificationEvents";
 import { baseMeta } from "./storybookUtils";
 
@@ -36,6 +37,15 @@ export const SMTPNotConfigured: Story = {
 			},
 		} as DeploymentValues,
 	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			canvas.getByRole("link", { name: /View docs/ }),
+		).toHaveAttribute(
+			"href",
+			docs("/admin/monitoring/notifications#smtp-email"),
+		);
+	},
 };
 
 export const WebhookNotConfigured: Story = {
@@ -53,6 +63,12 @@ export const WebhookNotConfigured: Story = {
 			},
 		} as DeploymentValues,
 	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			canvas.getByRole("link", { name: /View docs/ }),
+		).toHaveAttribute("href", docs("/admin/monitoring/notifications#webhook"));
+	},
 };
 
 export const ChangeMethod: Story = {