Skip to content

Commit 5f68065

Browse files
danbarrclaude
danbarr
and
claude
committed
Use relative DocCard hrefs on reference index pages
Absolute hrefs jump out of the active version when these landing pages are rendered in a versioned build. Relative hrefs resolve against the current page URL, keeping readers in their version. Also update the CRD page generator template to emit the same pattern plus a rationale comment, so regenerations stay consistent. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 11f30d1 commit 5f68065

5 files changed

Lines changed: 45 additions & 37 deletions

File tree

‎docs/toolhive/reference/crds/index.mdx‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,12 @@ references.
1616

1717
<div style={{display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))', gap: '1rem', margin: '1rem 0'}}>
1818

19+
{/* Use relative hrefs so cards resolve to the correct version when this page is snapshotted into a versioned build. */}
20+
1921
<DocCard
2022
item={{
2123
type: 'link',
22-
href: '/toolhive/reference/crds/mcpserver',
24+
href: './mcpserver',
2325
label: 'MCPServer',
2426
description: 'Containerized MCP server managed by the operator.',
2527
}}
@@ -28,7 +30,7 @@ references.
2830
<DocCard
2931
item={{
3032
type: 'link',
31-
href: '/toolhive/reference/crds/mcpremoteproxy',
33+
href: './mcpremoteproxy',
3234
label: 'MCPRemoteProxy',
3335
description: 'Proxy a remote MCP server through the operator.',
3436
}}
@@ -37,7 +39,7 @@ references.
3739
<DocCard
3840
item={{
3941
type: 'link',
40-
href: '/toolhive/reference/crds/mcpserverentry',
42+
href: './mcpserverentry',
4143
label: 'MCPServerEntry',
4244
description: 'Declare a remote MCP server as a group member.',
4345
}}
@@ -46,7 +48,7 @@ references.
4648
<DocCard
4749
item={{
4850
type: 'link',
49-
href: '/toolhive/reference/crds/virtualmcpserver',
51+
href: './virtualmcpserver',
5052
label: 'VirtualMCPServer',
5153
description: 'Aggregate multiple backends into a single vMCP endpoint.',
5254
}}
@@ -55,7 +57,7 @@ references.
5557
<DocCard
5658
item={{
5759
type: 'link',
58-
href: '/toolhive/reference/crds/mcpregistry',
60+
href: './mcpregistry',
5961
label: 'MCPRegistry',
6062
description: 'Deploy a ToolHive Registry Server.',
6163
}}
@@ -70,7 +72,7 @@ references.
7072
<DocCard
7173
item={{
7274
type: 'link',
73-
href: '/toolhive/reference/crds/mcpgroup',
75+
href: './mcpgroup',
7476
label: 'MCPGroup',
7577
description: 'Group backend workloads for shared configuration.',
7678
}}
@@ -79,7 +81,7 @@ references.
7981
<DocCard
8082
item={{
8183
type: 'link',
82-
href: '/toolhive/reference/crds/mcpoidcconfig',
84+
href: './mcpoidcconfig',
8385
label: 'MCPOIDCConfig',
8486
description: 'Shared OIDC authentication settings.',
8587
}}
@@ -88,7 +90,7 @@ references.
8890
<DocCard
8991
item={{
9092
type: 'link',
91-
href: '/toolhive/reference/crds/mcpexternalauthconfig',
93+
href: './mcpexternalauthconfig',
9294
label: 'MCPExternalAuthConfig',
9395
description: 'External authentication to upstream services.',
9496
}}
@@ -97,7 +99,7 @@ references.
9799
<DocCard
98100
item={{
99101
type: 'link',
100-
href: '/toolhive/reference/crds/mcptelemetryconfig',
102+
href: './mcptelemetryconfig',
101103
label: 'MCPTelemetryConfig',
102104
description: 'Shared OpenTelemetry tracing, metrics, and logging.',
103105
}}
@@ -106,7 +108,7 @@ references.
106108
<DocCard
107109
item={{
108110
type: 'link',
109-
href: '/toolhive/reference/crds/mcptoolconfig',
111+
href: './mcptoolconfig',
110112
label: 'MCPToolConfig',
111113
description: 'Tool filtering and renaming rules.',
112114
}}
@@ -115,7 +117,7 @@ references.
115117
<DocCard
116118
item={{
117119
type: 'link',
118-
href: '/toolhive/reference/crds/virtualmcpcompositetooldefinition',
120+
href: './virtualmcpcompositetooldefinition',
119121
label: 'VirtualMCPCompositeToolDefinition',
120122
description: 'Composite tool workflow for a VirtualMCPServer.',
121123
}}
@@ -124,7 +126,7 @@ references.
124126
<DocCard
125127
item={{
126128
type: 'link',
127-
href: '/toolhive/reference/crds/embeddingserver',
129+
href: './embeddingserver',
128130
label: 'EmbeddingServer',
129131
description: 'Local embedding model for the vMCP optimizer.',
130132
}}

‎docs/toolhive/reference/index.mdx‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,12 @@ tutorials, see the individual product sections.
1313

1414
<div style={{display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))', gap: '1rem', margin: '1rem 0'}}>
1515

16+
{/* Use relative hrefs so cards resolve to the correct version when this page is snapshotted into a versioned build. */}
17+
1618
<DocCard
1719
item={{
1820
type: 'link',
19-
href: '/toolhive/reference/client-compatibility',
21+
href: './client-compatibility',
2022
label: 'Client compatibility',
2123
description: 'Supported AI clients and how they connect to ToolHive.',
2224
}}
@@ -25,7 +27,7 @@ tutorials, see the individual product sections.
2527
<DocCard
2628
item={{
2729
type: 'link',
28-
href: '/toolhive/reference/authz-policy-reference',
30+
href: './authz-policy-reference',
2931
label: 'Authorization policies',
3032
description:
3133
'Reference for ToolHive authorization policy structure and syntax.',
@@ -35,7 +37,7 @@ tutorials, see the individual product sections.
3537
<DocCard
3638
item={{
3739
type: 'link',
38-
href: '/toolhive/reference/cli/thv',
40+
href: './cli/thv',
3941
label: 'CLI reference',
4042
description: 'Detailed reference for all ToolHive CLI commands and flags.',
4143
}}
@@ -44,7 +46,7 @@ tutorials, see the individual product sections.
4446
<DocCard
4547
item={{
4648
type: 'link',
47-
href: '/toolhive/reference/api',
49+
href: './api',
4850
label: 'API reference',
4951
description: 'Reference documentation for the ToolHive REST API.',
5052
}}
@@ -53,7 +55,7 @@ tutorials, see the individual product sections.
5355
<DocCard
5456
item={{
5557
type: 'link',
56-
href: '/toolhive/reference/crds',
58+
href: './crds',
5759
label: 'Kubernetes CRD reference',
5860
description: 'Reference for Kubernetes Operator custom resources.',
5961
}}
@@ -62,7 +64,7 @@ tutorials, see the individual product sections.
6264
<DocCard
6365
item={{
6466
type: 'link',
65-
href: '/toolhive/reference/registry-api',
67+
href: './registry-api',
6668
label: 'Registry Server API reference',
6769
description: 'REST API reference for the ToolHive Registry Server.',
6870
}}
@@ -71,7 +73,7 @@ tutorials, see the individual product sections.
7173
<DocCard
7274
item={{
7375
type: 'link',
74-
href: '/toolhive/reference/registry-schema-upstream',
76+
href: './registry-schema-upstream',
7577
label: 'Upstream registry JSON schema',
7678
description: 'JSON schema for the upstream MCP registry format.',
7779
}}
@@ -80,7 +82,7 @@ tutorials, see the individual product sections.
8082
<DocCard
8183
item={{
8284
type: 'link',
83-
href: '/toolhive/reference/registry-schema-toolhive',
85+
href: './registry-schema-toolhive',
8486
label: 'ToolHive registry JSON schema (legacy)',
8587
description:
8688
'Reference for the legacy ToolHive registry format, which is no longer accepted; migrate with `thv registry convert`.',

‎scripts/generate-crd-pages.mjs‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -194,25 +194,29 @@ function kindsByGroup() {
194194

195195
function renderLandingPage() {
196196
const grouped = kindsByGroup();
197-
const sections = groupOrder.map((group) => {
197+
const sections = groupOrder.map((group, index) => {
198198
const label = groupLabels[group];
199199
const cards = grouped[group]
200200
.map(
201201
(item) => `<DocCard
202202
item={{
203203
type: 'link',
204-
href: '/toolhive/reference/crds/${item.slug}',
204+
href: './${item.slug}',
205205
label: '${item.kind}',
206206
description: '${item.summary.replace(/'/g, "\\'")}',
207207
}}
208208
/>`
209209
)
210210
.join('\n\n');
211+
const rationale =
212+
index === 0
213+
? `{/* Use relative hrefs so cards resolve to the correct version when this page is snapshotted into a versioned build. */}\n\n`
214+
: '';
211215
return `## ${label}
212216
213217
<div style={{display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))', gap: '1rem', margin: '1rem 0'}}>
214218
215-
${cards}
219+
${rationale}${cards}
216220
217221
</div>`;
218222
});

‎versioned_docs/version-1.0/toolhive/reference/index.mdx‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ tutorials, see the individual product sections.
1616
<DocCard
1717
item={{
1818
type: 'link',
19-
href: '/toolhive/reference/client-compatibility',
19+
href: './client-compatibility',
2020
label: 'Client compatibility',
2121
description: 'Supported AI clients and how they connect to ToolHive.',
2222
}}
@@ -25,7 +25,7 @@ tutorials, see the individual product sections.
2525
<DocCard
2626
item={{
2727
type: 'link',
28-
href: '/toolhive/reference/cli/thv',
28+
href: './cli/thv',
2929
label: 'CLI reference',
3030
description: 'Detailed reference for all ToolHive CLI commands and flags.',
3131
}}
@@ -34,7 +34,7 @@ tutorials, see the individual product sections.
3434
<DocCard
3535
item={{
3636
type: 'link',
37-
href: '/toolhive/reference/api',
37+
href: './api',
3838
label: 'API reference',
3939
description: 'Reference documentation for the ToolHive REST API.',
4040
}}
@@ -43,7 +43,7 @@ tutorials, see the individual product sections.
4343
<DocCard
4444
item={{
4545
type: 'link',
46-
href: '/toolhive/reference/crd-spec',
46+
href: './crd-spec',
4747
label: 'Kubernetes CRD reference',
4848
description: 'Reference for Kubernetes Operator custom resources.',
4949
}}
@@ -52,7 +52,7 @@ tutorials, see the individual product sections.
5252
<DocCard
5353
item={{
5454
type: 'link',
55-
href: '/toolhive/reference/registry-api',
55+
href: './registry-api',
5656
label: 'Registry Server API reference',
5757
description: 'REST API reference for the ToolHive Registry Server.',
5858
}}
@@ -61,7 +61,7 @@ tutorials, see the individual product sections.
6161
<DocCard
6262
item={{
6363
type: 'link',
64-
href: '/toolhive/reference/registry-schema-upstream',
64+
href: './registry-schema-upstream',
6565
label: 'Upstream registry JSON schema',
6666
description: 'JSON schema for the upstream MCP registry format.',
6767
}}
@@ -70,7 +70,7 @@ tutorials, see the individual product sections.
7070
<DocCard
7171
item={{
7272
type: 'link',
73-
href: '/toolhive/reference/registry-schema-toolhive',
73+
href: './registry-schema-toolhive',
7474
label: 'ToolHive registry JSON schema',
7575
description: 'The JSON schema for the ToolHive registry (legacy format).',
7676
}}

‎versioned_docs/version-1.1/toolhive/reference/index.mdx‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ tutorials, see the individual product sections.
1616
<DocCard
1717
item={{
1818
type: 'link',
19-
href: '/toolhive/reference/client-compatibility',
19+
href: './client-compatibility',
2020
label: 'Client compatibility',
2121
description: 'Supported AI clients and how they connect to ToolHive.',
2222
}}
@@ -25,7 +25,7 @@ tutorials, see the individual product sections.
2525
<DocCard
2626
item={{
2727
type: 'link',
28-
href: '/toolhive/reference/cli/thv',
28+
href: './cli/thv',
2929
label: 'CLI reference',
3030
description: 'Detailed reference for all ToolHive CLI commands and flags.',
3131
}}
@@ -34,7 +34,7 @@ tutorials, see the individual product sections.
3434
<DocCard
3535
item={{
3636
type: 'link',
37-
href: '/toolhive/reference/api',
37+
href: './api',
3838
label: 'API reference',
3939
description: 'Reference documentation for the ToolHive REST API.',
4040
}}
@@ -43,7 +43,7 @@ tutorials, see the individual product sections.
4343
<DocCard
4444
item={{
4545
type: 'link',
46-
href: '/toolhive/reference/crd-spec',
46+
href: './crd-spec',
4747
label: 'Kubernetes CRD reference',
4848
description: 'Reference for Kubernetes Operator custom resources.',
4949
}}
@@ -52,7 +52,7 @@ tutorials, see the individual product sections.
5252
<DocCard
5353
item={{
5454
type: 'link',
55-
href: '/toolhive/reference/registry-api',
55+
href: './registry-api',
5656
label: 'Registry Server API reference',
5757
description: 'REST API reference for the ToolHive Registry Server.',
5858
}}
@@ -61,7 +61,7 @@ tutorials, see the individual product sections.
6161
<DocCard
6262
item={{
6363
type: 'link',
64-
href: '/toolhive/reference/registry-schema-upstream',
64+
href: './registry-schema-upstream',
6565
label: 'Upstream registry JSON schema',
6666
description: 'JSON schema for the upstream MCP registry format.',
6767
}}
@@ -70,7 +70,7 @@ tutorials, see the individual product sections.
7070
<DocCard
7171
item={{
7272
type: 'link',
73-
href: '/toolhive/reference/registry-schema-toolhive',
73+
href: './registry-schema-toolhive',
7474
label: 'ToolHive registry JSON schema',
7575
description: 'The JSON schema for the ToolHive registry (legacy format).',
7676
}}

0 commit comments

Comments
 (0)