Spike: versioned docs for Stacklok Enterprise

docs/theme-preview.mdx

@@ -30,10 +30,10 @@ By default level 2-3 headings generate the TOC on the top right
 
 ### Level 3 heading
 
-Some text within a section. [Here is a link](/theme-preview.mdx).
+Some text within a section. [Here is a link](./theme-preview.mdx).
 
 And here is some `inline code` to show how it looks, even some
-[`inline code with a link`](/theme-preview.mdx).
+[`inline code with a link`](./theme-preview.mdx).
 
 #### Level 4 heading
 
@@ -190,7 +190,7 @@ Stacklok Enterprise includes turnkey integrations for common identity providers.
 Instead of manually configuring OIDC, use the built-in Okta or Entra ID
 integration to map IdP groups directly to ToolHive roles and policy sets.
 
-[Learn more about Stacklok Enterprise](/toolhive/enterprise).
+[Learn more about Stacklok Enterprise](./toolhive/enterprise.mdx).
 
 :::
 

docs/toolhive/index.mdx

@@ -17,6 +17,7 @@ import ThemedImage from '@theme/ThemedImage';
   }}
   title='ToolHive logo'
   height={'120'}
+  style={{ 'margin-top': '1rem' }}
 />
 <br />
 

docs/toolhive/reference/crds/index.mdx

@@ -16,10 +16,12 @@ references.
 
 <div style={{display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))', gap: '1rem', margin: '1rem 0'}}>
 
+{/* Use relative hrefs so cards resolve to the correct version when this page is snapshotted into a versioned build. */}
+
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/mcpserver',
+    href: './mcpserver',
     label: 'MCPServer',
     description: 'Containerized MCP server managed by the operator.',
   }}
@@ -28,7 +30,7 @@ references.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/mcpremoteproxy',
+    href: './mcpremoteproxy',
     label: 'MCPRemoteProxy',
     description: 'Proxy a remote MCP server through the operator.',
   }}
@@ -37,7 +39,7 @@ references.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/mcpserverentry',
+    href: './mcpserverentry',
     label: 'MCPServerEntry',
     description: 'Declare a remote MCP server as a group member.',
   }}
@@ -46,7 +48,7 @@ references.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/virtualmcpserver',
+    href: './virtualmcpserver',
     label: 'VirtualMCPServer',
     description: 'Aggregate multiple backends into a single vMCP endpoint.',
   }}
@@ -55,7 +57,7 @@ references.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/mcpregistry',
+    href: './mcpregistry',
     label: 'MCPRegistry',
     description: 'Deploy a ToolHive Registry Server.',
   }}
@@ -70,7 +72,7 @@ references.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/mcpgroup',
+    href: './mcpgroup',
     label: 'MCPGroup',
     description: 'Group backend workloads for shared configuration.',
   }}
@@ -79,7 +81,7 @@ references.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/mcpoidcconfig',
+    href: './mcpoidcconfig',
     label: 'MCPOIDCConfig',
     description: 'Shared OIDC authentication settings.',
   }}
@@ -88,7 +90,7 @@ references.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/mcpexternalauthconfig',
+    href: './mcpexternalauthconfig',
     label: 'MCPExternalAuthConfig',
     description: 'External authentication to upstream services.',
   }}
@@ -97,7 +99,7 @@ references.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/mcptelemetryconfig',
+    href: './mcptelemetryconfig',
     label: 'MCPTelemetryConfig',
     description: 'Shared OpenTelemetry tracing, metrics, and logging.',
   }}
@@ -106,7 +108,7 @@ references.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/mcptoolconfig',
+    href: './mcptoolconfig',
     label: 'MCPToolConfig',
     description: 'Tool filtering and renaming rules.',
   }}
@@ -115,7 +117,7 @@ references.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/virtualmcpcompositetooldefinition',
+    href: './virtualmcpcompositetooldefinition',
     label: 'VirtualMCPCompositeToolDefinition',
     description: 'Composite tool workflow for a VirtualMCPServer.',
   }}
@@ -124,7 +126,7 @@ references.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds/embeddingserver',
+    href: './embeddingserver',
     label: 'EmbeddingServer',
     description: 'Local embedding model for the vMCP optimizer.',
   }}

docs/toolhive/reference/index.mdx

@@ -13,10 +13,12 @@ tutorials, see the individual product sections.
 
 <div style={{display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))', gap: '1rem', margin: '1rem 0'}}>
 
+{/* Use relative hrefs so cards resolve to the correct version when this page is snapshotted into a versioned build. */}
+
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/client-compatibility',
+    href: './client-compatibility',
     label: 'Client compatibility',
     description: 'Supported AI clients and how they connect to ToolHive.',
   }}
@@ -25,7 +27,7 @@ tutorials, see the individual product sections.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/authz-policy-reference',
+    href: './authz-policy-reference',
     label: 'Authorization policies',
     description:
       'Reference for ToolHive authorization policy structure and syntax.',
@@ -35,7 +37,7 @@ tutorials, see the individual product sections.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/cli/thv',
+    href: './cli/thv',
     label: 'CLI reference',
     description: 'Detailed reference for all ToolHive CLI commands and flags.',
   }}
@@ -44,7 +46,7 @@ tutorials, see the individual product sections.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/api',
+    href: './api',
     label: 'API reference',
     description: 'Reference documentation for the ToolHive REST API.',
   }}
@@ -53,7 +55,7 @@ tutorials, see the individual product sections.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/crds',
+    href: './crds',
     label: 'Kubernetes CRD reference',
     description: 'Reference for Kubernetes Operator custom resources.',
   }}
@@ -62,7 +64,7 @@ tutorials, see the individual product sections.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/registry-api',
+    href: './registry-api',
     label: 'Registry Server API reference',
     description: 'REST API reference for the ToolHive Registry Server.',
   }}
@@ -71,7 +73,7 @@ tutorials, see the individual product sections.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/registry-schema-upstream',
+    href: './registry-schema-upstream',
     label: 'Upstream registry JSON schema',
     description: 'JSON schema for the upstream MCP registry format.',
   }}
@@ -80,7 +82,7 @@ tutorials, see the individual product sections.
 <DocCard
   item={{
     type: 'link',
-    href: '/toolhive/reference/registry-schema-toolhive',
+    href: './registry-schema-toolhive',
     label: 'ToolHive registry JSON schema (legacy)',
     description:
       'Reference for the legacy ToolHive registry format, which is no longer accepted; migrate with `thv registry convert`.',

docusaurus.config.ts

@@ -186,6 +186,24 @@ const config: Config = {
               },
             ],
           ],
+          lastVersion: 'current',
+          versions: {
+            current: {
+              label: 'Latest (OSS)',
+            },
+            '1.1': {
+              label: 'Enterprise 1.1',
+              path: 'enterprise/1.1',
+              banner: 'none',
+              noIndex: true,
+            },
+            '1.0': {
+              label: 'Enterprise 1.0',
+              path: 'enterprise/1.0',
+              banner: 'none',
+              noIndex: true,
+            },
+          },
         },
         blog: {
           blogTitle: 'ToolHive Updates and Announcements',
@@ -257,28 +275,34 @@ const config: Config = {
           position: 'left',
           items: [
             {
+              type: 'doc',
+              docId: 'toolhive/index',
               label: 'Home',
-              href: '/toolhive',
             },
             {
+              type: 'doc',
+              docId: 'toolhive/guides-ui/index',
               label: 'ToolHive UI',
-              to: 'toolhive/guides-ui',
             },
             {
+              type: 'doc',
+              docId: 'toolhive/guides-cli/index',
               label: 'ToolHive CLI',
-              to: 'toolhive/guides-cli',
             },
             {
+              type: 'doc',
+              docId: 'toolhive/guides-k8s/index',
               label: 'Kubernetes Operator',
-              to: 'toolhive/guides-k8s',
             },
             {
+              type: 'doc',
+              docId: 'toolhive/guides-vmcp/index',
               label: 'Virtual MCP Server',
-              to: 'toolhive/guides-vmcp',
             },
             {
-              label: 'ToolHive Registry',
-              to: 'toolhive/guides-registry',
+              type: 'doc',
+              docId: 'toolhive/guides-registry/index',
+              label: 'Registry Server',
             },
           ],
         },
@@ -288,28 +312,34 @@ const config: Config = {
           position: 'left',
           items: [
             {
+              type: 'doc',
+              docId: 'toolhive/reference/cli/thv',
               label: 'ToolHive CLI commands',
-              to: 'toolhive/reference/cli/thv',
             },
             {
+              type: 'doc',
+              docId: 'toolhive/reference/api',
               label: 'ToolHive API',
-              to: 'toolhive/reference/api',
             },
             {
+              type: 'doc',
+              docId: 'toolhive/reference/crds/index',
               label: 'ToolHive Operator CRD',
-              to: 'toolhive/reference/crds',
             },
             {
+              type: 'doc',
+              docId: 'toolhive/reference/registry-api',
               label: 'ToolHive Registry Server API',
-              to: 'toolhive/reference/registry-api',
             },
             {
+              type: 'doc',
+              docId: 'toolhive/reference/registry-schema-toolhive',
               label: 'ToolHive registry schema',
-              to: 'toolhive/reference/registry-schema-toolhive',
             },
             {
+              type: 'doc',
+              docId: 'toolhive/reference/registry-schema-upstream',
               label: 'Upstream registry schema',
-              to: 'toolhive/reference/registry-schema-upstream',
             },
           ],
         },
@@ -319,9 +349,16 @@ const config: Config = {
           position: 'left',
         },
         {
-          to: 'toolhive/enterprise',
+          type: 'doc',
+          docId: 'toolhive/enterprise',
           label: 'Enterprise',
           position: 'left',
+          className: 'navbar-doc-link',
+        },
+        {
+          type: 'docsVersionDropdown',
+          position: 'right',
+          className: 'version-dropdown',
         },
         {
           href: 'https://github.com/stacklok',

eslint.config.mjs

@@ -55,7 +55,7 @@ export default [
 
   // Config for _partials with JSX props
   {
-    files: ['docs/**/_partials/*.mdx'],
+    files: ['docs/**/_partials/*.mdx', 'versioned_docs/**/_partials/*.mdx'],
     rules: {
       'no-unused-expressions': 'off',
       '@typescript-eslint/no-unused-expressions': 'off',