feat: insert docs version segment for all internal link shapes (#2419)

Author: danielroe

nuxt.config.ts

@@ -2,7 +2,7 @@ import { createResolver } from 'nuxt/kit'
 import { parseMdc } from './helpers/mdc-parser.mjs'
 import { agentHowToCall, agentWhenToUse } from './shared/utils/agents'
 import { CLI_DOCS_PREFIX, CLI_DOCS_REFS, CLI_DOCS_REPO } from './shared/utils/cli-docs'
-import { CURRENT_DOCS_VERSION, EXCLUDED_DOC_VERSIONS } from './shared/utils/docs'
+import { CURRENT_DOCS_VERSION, DOCS_COLLECTION_VERSIONS, EXCLUDED_DOC_VERSIONS, insertDocsVersion } from './shared/utils/docs'
 
 const { resolve } = createResolver(import.meta.url)
 
@@ -441,7 +441,6 @@ export default defineNuxtConfig({
     '/docs/5.x/getting-started/directory-structure': { redirect: '/docs/4.x/directory-structure', prerender: false },
     '/docs/4.x/guide/going-further/modules': { redirect: '/docs/4.x/guide/modules', prerender: false },
     '/docs/5.x/guide/going-further/modules': { redirect: '/docs/4.x/guide/modules', prerender: false },
-    '/docs/4.x/guide/modules/module-dependencies': { redirect: '/docs/5.x/guide/modules/module-dependencies', prerender: false },
     '/docs/4.x/guide/concepts/rendering-modes': { redirect: '/docs/4.x/guide/concepts/rendering', prerender: false },
     '/docs/5.x/guide/concepts/rendering-modes': { redirect: '/docs/4.x/guide/concepts/rendering', prerender: false },
     '/docs/4.x/guide/directory-structure/nuxt.config': { redirect: '/docs/4.x/directory-structure/nuxt-config', prerender: false },
@@ -539,27 +538,9 @@ export default defineNuxtConfig({
         const base = `https://raw.githubusercontent.com/${CLI_DOCS_REPO}/${CLI_DOCS_REFS[collection]}`
         file.body = file.body.replaceAll(/(!\[[^\]]*\]\()\/(?!\/)/g, `$1${base}/`)
       }
-      if (file.id.startsWith('docsv5/')) {
-        file.body = file.body.replaceAll(/\(\/docs\/(?!\d\.x)/g, '(/docs/5.x/')
-        // Pages that only exist on main (5.x) but are linked as /docs/4.x/* from
-        // the 5.x docs. Left unrewritten they 404, which fails the prerender now
-        // that the crawler is on. Only paths whose 5.x counterpart exists belong
-        // here — a blanket 4.x→5.x rewrite would break the ~13 links that point
-        // at pages 5.x dropped (guide/concepts/esm, going-further/internals, …).
-        for (const path of [
-          'guide/modules/module-dependencies',
-          'guide/best-practices/accessibility',
-          'guide/concepts/server-components',
-          'guide/recipes/mostly-static-sites'
-        ]) {
-          file.body = file.body.replaceAll(`/docs/4.x/${path}`, `/docs/5.x/${path}`)
-        }
-      }
-      if (file.id.startsWith('docsv4/')) {
-        file.body = file.body.replaceAll(/\(\/docs\/(?!\d\.x)/g, '(/docs/4.x/')
-      }
-      if (file.id.startsWith('docsv3/')) {
-        file.body = file.body.replaceAll(/\(\/docs\/(?!\d\.x)/g, '(/docs/3.x/')
+      const docsVersion = DOCS_COLLECTION_VERSIONS[collection]
+      if (docsVersion) {
+        file.body = insertDocsVersion(file.body, docsVersion)
       }
     },
     'content:file:afterParse': async ({ file, content }) => {

shared/utils/docs.ts

@@ -7,13 +7,27 @@
 //   - nuxt.config.ts (agentDiscovery)     → excluded versions never negotiate markdown, MCP server card docs link
 //   - server/plugins/agent-discovery.ts   → generated /raw/index.md links to versioned docs
 //   - app/middleware/docs-version.global.ts → unversioned `/docs/*` redirect target
+//   - nuxt.config.ts (content:file:beforeParse) → version segment inserted into internal docs links
+//     via DOCS_COLLECTION_VERSIONS, whose keys must match the collection names in content.config.ts
 //
 // When Nuxt 5 ships: move `'5.x'` from EXCLUDED_DOC_VERSIONS into
 // SUPPORTED_DOC_VERSIONS and bump CURRENT_DOCS_VERSION.
 export const SUPPORTED_DOC_VERSIONS = ['3.x', '4.x'] as const
 export const EXCLUDED_DOC_VERSIONS = ['5.x'] as const
 export const CURRENT_DOCS_VERSION: (typeof SUPPORTED_DOC_VERSIONS)[number] = '4.x'
 
+// Content collection id (the first segment of `file.id`) → docs version.
+export const DOCS_COLLECTION_VERSIONS: Record<string, string | undefined> = Object.fromEntries(
+  [...SUPPORTED_DOC_VERSIONS, ...EXCLUDED_DOC_VERSIONS].map(version => [`docsv${version.split('.')[0]}`, version])
+)
+
+// Docs sources write internal links unversioned so a docs PR can be
+// cherry-picked between release branches unchanged. The URL-opening delimiter
+// is what keeps `/assets/docs/…` and external `…/docs/…` URLs out of scope.
+export function insertDocsVersion(body: string, version: string) {
+  return body.replaceAll(/(["'(=])\/docs\/(?!\d\.x)/g, `$1/docs/${version}/`)
+}
+
 const escape = (v: string) => v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
 // `^/docs/(?:3\.x|4\.x)(?:/|$)` — matches versioned doc paths only.

test/unit/docs.spec.ts

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { DOCS_COLLECTION_VERSIONS, insertDocsVersion } from '../../shared/utils/docs'
+
+describe('DOCS_COLLECTION_VERSIONS', () => {
+  it('should key on collections declared in content.config.ts', () => {
+    const config = readFileSync(fileURLToPath(new URL('../../content.config.ts', import.meta.url)), 'utf8')
+    const collections = [...config.matchAll(/^ {4}(\w+): defineCollection\(/gm)].map(match => match[1])
+    expect(collections).toContain('docsv4')
+    for (const collection of Object.keys(DOCS_COLLECTION_VERSIONS)) {
+      expect(collections).toContain(collection)
+    }
+  })
+})
+
+describe('insertDocsVersion', () => {
+  it('should version markdown links', () => {
+    expect(insertDocsVersion('see [intro](/docs/getting-started/introduction)', '5.x'))
+      .toBe('see [intro](/docs/5.x/getting-started/introduction)')
+  })
+
+  it('should version quoted and unquoted MDC props', () => {
+    expect(insertDocsVersion('::read-more{to="/docs/api/composables/use-fetch"}\n::', '3.x'))
+      .toBe('::read-more{to="/docs/3.x/api/composables/use-fetch"}\n::')
+    expect(insertDocsVersion(':read-more{to=\'/docs/api\'}', '4.x'))
+      .toBe(':read-more{to=\'/docs/4.x/api\'}')
+    expect(insertDocsVersion('::card{link="/docs/guide"}\n::', '4.x'))
+      .toBe('::card{link="/docs/4.x/guide"}\n::')
+    expect(insertDocsVersion(':read-more{to=/docs/getting-started/data-fetching}', '4.x'))
+      .toBe(':read-more{to=/docs/4.x/getting-started/data-fetching}')
+  })
+
+  it('should leave already-versioned links alone', () => {
+    const body = '[a](/docs/3.x/guide) and ::read-more{to="/docs/4.x/api"}'
+    expect(insertDocsVersion(body, '5.x')).toBe(body)
+  })
+
+  it('should not rewrite asset paths, external docs URLs or prose', () => {
+    const body = [
+      '![diagram](/assets/docs/guide/rendering.svg)',
+      '<img src="/assets/docs/getting-started/nuxt.png">',
+      '[MDN](https://developer.mozilla.org/en-US/docs/Web/API/fetch)',
+      'see https://chrome.com/docs/lighthouse and /assets/docs/foo.png',
+      'use relative paths without the domain: `/docs/getting-started/installation`'
+    ].join('\n')
+    expect(insertDocsVersion(body, '5.x')).toBe(body)
+  })
+})