Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(docs): URL-hash deep-link for active tab on every Tabs block (#2067)

Abrahamcbd28c5cc555
diff --git a/docs/src/components/tabs.test.ts b/docs/src/components/tabs.test.ts
new file mode 100644
index 000000000..e6fac8c55
--- /dev/null
+++ b/docs/src/components/tabs.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, test } from 'bun:test';
+import { composeTabId, slugifyTabId } from './tabs.tsx';
+
+describe('slugifyTabId', () => {
+ test('lowercases ASCII letters', () => {
+ expect(slugifyTabId('MacOS')).toBe('macos');
+ });
+
+ test('replaces a single space with a dash', () => {
+ expect(slugifyTabId('macOS app')).toBe('macos-app');
+ });
+
+ test('collapses runs of non-alphanumeric chars into a single dash', () => {
+ expect(slugifyTabId('Web app (Linux)')).toBe('web-app-linux');
+ });
+
+ test('drops middle-dot and other Unicode separators (PRD-7162 trigger label)', () => {
+ expect(slugifyTabId('Web app (Linux · Intel Mac)')).toBe('web-app-linux-intel-mac');
+ });
+
+ test('strips combining diacritics via NFKD decomposition (café → cafe)', () => {
+ expect(slugifyTabId('Café')).toBe('cafe');
+ });
+
+ test('trims leading and trailing dashes', () => {
+ expect(slugifyTabId(' hello ')).toBe('hello');
+ expect(slugifyTabId('!!?weird??!!')).toBe('weird');
+ });
+
+ test('returns empty string for all-non-alphanumeric input', () => {
+ expect(slugifyTabId('!!!')).toBe('');
+ expect(slugifyTabId('···')).toBe('');
+ expect(slugifyTabId('')).toBe('');
+ });
+
+ test('preserves digits and mixes them with letters', () => {
+ expect(slugifyTabId('v1.2.3 release')).toBe('v1-2-3-release');
+ });
+
+ test('idempotent — slugify(slugify(x)) === slugify(x)', () => {
+ const cases = [
+ 'macOS app',
+ 'Web app (Linux · Intel Mac)',
+ 'Café',
+ 'v1.2.3 release',
+ ' edge case ',
+ ];
+ for (const c of cases) {
+ const once = slugifyTabId(c);
+ expect(slugifyTabId(once)).toBe(once);
+ }
+ });
+});
+
+describe('composeTabId (groupId-prefix URL composition)', () => {
+ test('groupId + label → prefixed slug (the docs quickstart shape)', () => {
+ expect(composeTabId('macOS app', 'ok-install')).toBe('ok-install-macos-app');
+ expect(composeTabId('Web app (Linux · Intel Mac)', 'ok-install')).toBe(
+ 'ok-install-web-app-linux-intel-mac',
+ );
+ });
+
+ test('no groupId → bare label slug (no leading dash, no prefix)', () => {
+ expect(composeTabId('macOS app', undefined)).toBe('macos-app');
+ expect(composeTabId('macOS app', '')).toBe('macos-app');
+ });
+
+ test('groupId itself is slugified before prefixing', () => {
+ expect(composeTabId('macOS app', 'My Install')).toBe('my-install-macos-app');
+ });
+
+ test('label missing or unslugable → null (caller falls back to positional id)', () => {
+ expect(composeTabId(undefined, 'ok-install')).toBeNull();
+ expect(composeTabId('', 'ok-install')).toBeNull();
+ expect(composeTabId(' ', 'ok-install')).toBeNull();
+ expect(composeTabId('!!!', 'ok-install')).toBeNull();
+ });
+
+ test('groupId that slugs to empty falls back to bare label (not "-label")', () => {
+ expect(composeTabId('macOS app', '!!!')).toBe('macos-app');
+ });
+
+ test('idempotent — composeTabId(composeTabId(label), groupId) preserves the result when re-fed', () => {
+ const composed = composeTabId('macOS app', 'ok-install');
+ expect(composed).toBe('ok-install-macos-app');
+ expect(slugifyTabId(composed ?? '')).toBe(composed);
+ });
+});
diff --git a/docs/src/components/tabs.tsx b/docs/src/components/tabs.tsx
new file mode 100644
index 000000000..b58677dc3
--- /dev/null
+++ b/docs/src/components/tabs.tsx
@@ -0,0 +1,77 @@
+'use client';
+
+import {
+ Tab as FumadocsTab,
+ Tabs as FumadocsTabs,
+ type TabProps,
+ type TabsProps,
+} from 'fumadocs-ui/components/tabs';
+import * as React from 'react';
+
+export function slugifyTabId(input: string): string {
+ return input
+ .normalize('NFKD')
+ .replace(/[̀-ͯ]/g, '')
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, '-')
+ .replace(/^-+|-+$/g, '');
+}
+
+export function composeTabId(
+ label: string | undefined,
+ groupId: string | undefined,
+): string | null {
+ const labelSlug = label ? slugifyTabId(label) : '';
+ if (!labelSlug) return null;
+ const groupSlug = groupId ? slugifyTabId(groupId) : '';
+ return groupSlug ? `${groupSlug}-${labelSlug}` : labelSlug;
+}
+
+interface TabsDeepLinkCtx {
+ items: readonly string[] | undefined;
+ groupId: string | undefined;
+ collection: string[];
+}
+
+const TabsDeepLinkContext = React.createContext<TabsDeepLinkCtx | null>(null);
+
+export function Tabs({
+ items,
+ groupId,
+ updateAnchor = true,
+ children,
+ ...rest
+}: TabsProps): React.JSX.Element {
+ const [collection] = React.useState<string[]>(() => []);
+ const ctx: TabsDeepLinkCtx = { items, groupId, collection };
+ return (
+ <TabsDeepLinkContext.Provider value={ctx}>
+ <FumadocsTabs items={items} groupId={groupId} updateAnchor={updateAnchor} {...rest}>
+ {children}
+ </FumadocsTabs>
+ </TabsDeepLinkContext.Provider>
+ );
+}
+
+export function Tab({ id: explicitId, ...rest }: TabProps): React.JSX.Element {
+ const key = React.useId();
+ const ctx = React.use(TabsDeepLinkContext);
+ React.useEffect(() => {
+ if (!ctx) return;
+ return () => {
+ const idx = ctx.collection.indexOf(key);
+ if (idx !== -1) ctx.collection.splice(idx, 1);
+ };
+ }, [ctx, key]);
+ let index = -1;
+ if (ctx) {
+ if (!ctx.collection.includes(key)) ctx.collection.push(key);
+ index = ctx.collection.indexOf(key);
+ }
+ let resolvedId = explicitId;
+ if (resolvedId === undefined && ctx && index >= 0) {
+ const label = ctx.items?.[index];
+ resolvedId = composeTabId(label, ctx.groupId) ?? `tab-${index + 1}`;
+ }
+ return <FumadocsTab id={resolvedId} {...rest} />;
+}
diff --git a/docs/src/mdx-components.tsx b/docs/src/mdx-components.tsx
index e13847db4..2e6cfa279 100644
--- a/docs/src/mdx-components.tsx
+++ b/docs/src/mdx-components.tsx
@@ -2,7 +2,6 @@ import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { ImageZoom } from 'fumadocs-ui/components/image-zoom';
import { Step, Steps } from 'fumadocs-ui/components/steps';
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import defaultMdxComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';
@@ -13,6 +12,7 @@ import { DownloadButton } from '@/components/download-button';
import { McpInstall } from '@/components/mcp-install';
import { Mermaid } from '@/components/mermaid';
import { LayerStack, WhereToStart } from '@/components/overview-blocks';
+import { Tab, Tabs } from '@/components/tabs';
import { VerifyExec } from '@/components/verify-exec';
export function getMDXComponents(): MDXComponents {