feat: source cli command docs from nuxt/cli (#2392)

Author: danielroe

app/components/DocsProseImg.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import { ProseImg } from '#components'
+import { CLI_DOCS_REPO } from '#shared/utils/cli-docs'
+
+const props = defineProps({
+  src: {
+    type: String,
+    default: ''
+  },
+  alt: {
+    type: String,
+    default: ''
+  },
+  width: {
+    type: [String, Number],
+    default: undefined
+  },
+  height: {
+    type: [String, Number],
+    default: undefined
+  }
+})
+
+// The CLI's terminal captures are SVGs carrying both colour schemes via
+// `prefers-color-scheme`, some animated with SMIL, and rasterising them through IPX
+// drops both. `none` keeps the URL untouched while retaining the default styling and
+// zoom, which a plain `<img>` would lose.
+const provider = computed(() => props.src.startsWith(`https://raw.githubusercontent.com/${CLI_DOCS_REPO}/`) ? 'none' : undefined)
+</script>
+
+<template>
+  <ProseImg
+    :src="src"
+    :alt="alt"
+    :width="width"
+    :height="height"
+    :provider="provider"
+  />
+</template>

app/pages/docs/[...slug].vue

@@ -4,6 +4,7 @@ import { joinURL } from 'ufo'
 import type { ContentNavigationItem } from '@nuxt/content'
 import { findPageBreadcrumb } from '@nuxt/content/utils'
 import { mapContentNavigation } from '@nuxt/ui/utils/content'
+import { DocsProseImg } from '#components'
 import { SUPPORTED_DOCS_PATH_REGEX } from '#shared/utils/docs'
 
 definePageMeta({
@@ -250,7 +251,7 @@ const noRightAside = computed(() => route.path.includes('/examples/'))
         </UPageHeader>
 
         <UPageBody>
-          <ContentRenderer v-if="page.body" :value="page" />
+          <ContentRenderer v-if="page.body" :value="page" :components="{ img: DocsProseImg }" />
           <div>
             <Feedback :page="page" />
             <USeparator class="mt-6 mb-10">

content.config.ts

@@ -1,29 +1,51 @@
 import { defineContentConfig, defineCollection, z } from '@nuxt/content'
+import { CLI_DOCS_PREFIX, CLI_DOCS_REFS, CLI_DOCS_REPO } from './shared/utils/cli-docs'
 
 const docsV3Source = {
   cwd: process.env.NUXT_V3_PATH ?? undefined,
   repository: !process.env.NUXT_V3_PATH ? 'https://github.com/nuxt/nuxt/tree/3.x' : undefined,
   include: 'docs/**/*',
-  exclude: ['docs/**/*.json'],
+  exclude: ['docs/**/*.json', 'docs/4.api/4.commands/**'],
   prefix: '/docs/3.x'
 }
 
 const docsV4Source = {
   cwd: process.env.NUXT_V4_PATH ?? undefined,
   repository: !process.env.NUXT_V4_PATH ? 'https://github.com/nuxt/nuxt/tree/4.x' : undefined,
   include: 'docs/**/*',
-  exclude: ['docs/**/*.json'],
+  exclude: ['docs/**/*.json', 'docs/4.api/4.commands/**'],
   prefix: '/docs/4.x'
 }
 
 const docsV5Source = {
   cwd: process.env.NUXT_V5_PATH ?? undefined,
   repository: !process.env.NUXT_V5_PATH ? 'https://github.com/nuxt/nuxt/tree/main' : undefined,
   include: 'docs/**/*',
-  exclude: ['docs/**/*.json'],
+  exclude: ['docs/**/*.json', 'docs/4.api/4.commands/**'],
   prefix: '/docs/5.x'
 }
 
+const cliV3Source = {
+  cwd: process.env.NUXT_CLI_PATH ?? undefined,
+  repository: !process.env.NUXT_CLI_PATH ? `https://github.com/${CLI_DOCS_REPO}/tree/${CLI_DOCS_REFS.docsv3}` : undefined,
+  include: 'docs/**/*',
+  prefix: `/docs/3.x/${CLI_DOCS_PREFIX}`
+}
+
+const cliV4Source = {
+  cwd: process.env.NUXT_CLI_PATH ?? undefined,
+  repository: !process.env.NUXT_CLI_PATH ? `https://github.com/${CLI_DOCS_REPO}/tree/${CLI_DOCS_REFS.docsv4}` : undefined,
+  include: 'docs/**/*',
+  prefix: `/docs/4.x/${CLI_DOCS_PREFIX}`
+}
+
+const cliV5Source = {
+  cwd: process.env.NUXT_CLI_PATH ?? undefined,
+  repository: !process.env.NUXT_CLI_PATH ? `https://github.com/${CLI_DOCS_REPO}/tree/${CLI_DOCS_REFS.docsv5}` : undefined,
+  include: 'docs/**/*',
+  prefix: `/docs/5.x/${CLI_DOCS_PREFIX}`
+}
+
 const examplesV3Source = {
   cwd: process.env.NUXT_EXAMPLES_PATH ?? undefined,
   repository: !process.env.NUXT_EXAMPLES_PATH ? 'https://github.com/nuxt/examples' : undefined,
@@ -214,7 +236,7 @@ export default defineContentConfig({
     }),
     docsv5: defineCollection({
       type: 'page',
-      source: [docsV5Source, examplesV5Source],
+      source: [docsV5Source, cliV5Source, examplesV5Source],
       schema: z.object({
         titleTemplate: z.string().optional(),
         links: z.array(Button),
@@ -223,7 +245,7 @@ export default defineContentConfig({
     }),
     docsv4: defineCollection({
       type: 'page',
-      source: [docsV4Source, examplesV4Source],
+      source: [docsV4Source, cliV4Source, examplesV4Source],
       schema: z.object({
         titleTemplate: z.string().optional(),
         links: z.array(Button),
@@ -232,7 +254,7 @@ export default defineContentConfig({
     }),
     docsv3: defineCollection({
       type: 'page',
-      source: [docsV3Source, examplesV3Source],
+      source: [docsV3Source, cliV3Source, examplesV3Source],
       schema: z.object({
         titleTemplate: z.string().optional(),
         links: z.array(Button),

nuxt.config.ts

@@ -1,5 +1,6 @@
 import { createResolver } from 'nuxt/kit'
 import { parseMdc } from './helpers/mdc-parser.mjs'
+import { CLI_DOCS_PREFIX, CLI_DOCS_REFS, CLI_DOCS_REPO } from './shared/utils/cli-docs'
 
 const { resolve } = createResolver(import.meta.url)
 
@@ -246,10 +247,10 @@ export default defineNuxtConfig({
     '/docs/3.x/api/kit': { redirect: '/docs/3.x/api/kit/modules', prerender: false },
     '/docs/4.x/api/kit': { redirect: '/docs/4.x/api/kit/modules', prerender: false },
     '/docs/5.x/api/kit': { redirect: '/docs/5.x/api/kit/modules', prerender: false },
-    '/docs/api/commands': { redirect: '/docs/api/commands/dev', prerender: false },
-    '/docs/3.x/api/commands': { redirect: '/docs/3.x/api/commands/dev', prerender: false },
-    '/docs/4.x/api/commands': { redirect: '/docs/4.x/api/commands/dev', prerender: false },
-    '/docs/5.x/api/commands': { redirect: '/docs/5.x/api/commands/dev', prerender: false },
+    '/docs/api/commands': { redirect: '/docs/api/commands/overview', prerender: false },
+    '/docs/3.x/api/commands': { redirect: '/docs/3.x/api/commands/overview', prerender: false },
+    '/docs/4.x/api/commands': { redirect: '/docs/4.x/api/commands/overview', prerender: false },
+    '/docs/5.x/api/commands': { redirect: '/docs/5.x/api/commands/overview', prerender: false },
     '/docs/api/advanced': { redirect: '/docs/api/advanced/hooks', prerender: false },
     '/docs/3.x/api/advanced': { redirect: '/docs/3.x/api/advanced/hooks', prerender: false },
     '/docs/4.x/api/advanced': { redirect: '/docs/4.x/api/advanced/hooks', prerender: false },
@@ -537,6 +538,15 @@ export default defineNuxtConfig({
   },
   hooks: {
     'content:file:beforeParse': async ({ file }) => {
+      // Command docs are served from `nuxt/cli`, but Content only ships the markdown,
+      // not the terminal captures committed beside it. Root-relative image sources are
+      // repo-relative, so resolve them against the ref this page was parsed from: a
+      // hardcoded ref would serve `main`'s captures on the 3.x tree.
+      const collection = file.id.split('/')[0] as keyof typeof CLI_DOCS_REFS
+      if (file.id.includes(`/${CLI_DOCS_PREFIX}/`) && CLI_DOCS_REFS[collection]) {
+        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
@@ -556,6 +566,9 @@ export default defineNuxtConfig({
       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/')
+      }
     },
     'content:file:afterParse': async ({ file, content }) => {
       if (file.id === 'index/index.yml') {
@@ -631,7 +644,11 @@ export default defineNuxtConfig({
   },
   image: {
     format: ['webp', 'jpeg', 'jpg', 'png', 'svg'],
-    provider: 'ipx'
+    provider: 'ipx',
+    // Opt-out escape hatch for images IPX must not touch, used by `DocsProseImg`.
+    providers: {
+      none: { provider: 'none' }
+    }
   },
   llms: {
     domain: 'https://nuxt.com',

patches/@nuxt__content.patch

@@ -0,0 +1,22 @@
+diff --git a/dist/module.mjs b/dist/module.mjs
+index f1516bab826818eacc9088a24df96cf4ff895502..b14f1f4579af1e502fc57e9834e88feb916222cc 100644
+--- a/dist/module.mjs
++++ b/dist/module.mjs
+@@ -2007,11 +2007,16 @@ function defineGitSource(source) {
+       const repository = source?.repository && gitUrlParse(source.repository.url);
+       if (repository) {
+         const { source: gitSource, owner, name } = repository;
+-        resolvedSource.cwd = join(rootDir, ".data", "content", `${gitSource}-${owner}-${name}-${repository.ref || "main"}`);
+         let ref;
+         if (source.repository.branch && source.repository.tag) {
+           throw new Error("Cannot specify both branch and tag for git repository. Please specify one of `branch` or `tag`.");
+         }
++        // Keyed on the resolved ref so two refs of one repo do not share a checkout.
++        // Backport of https://github.com/nuxt/content/pull/3839; drop on the next release.
++        const resolvedRef = source.repository.branch || source.repository.tag || repository.ref || "main";
++        const refKey = /^[\w.-]+$/.test(resolvedRef) ? resolvedRef : `${resolvedRef.replace(/[^\w.-]+/g, "-")}-${hash(resolvedRef).slice(0, 8)}`;
++        const refPrefix = source.repository.tag ? "tag-" : "";
++        resolvedSource.cwd = join(rootDir, ".data", "content", `${gitSource}-${owner}-${name}-${refPrefix}${refKey}`);
+         if (source.repository.branch) ref = { branch: source.repository.branch };
+         if (source.repository.tag) ref = { tag: source.repository.tag };
+         if (!source.repository?.auth && source.authBasic) {

pnpm-lock.yaml

@@ -31,3 +31,9 @@ minimumReleaseAgeExclude:
   - vue
   - '@vue/*'
   - '@nuxtjs/mdc@0.23.1'
+
+patchedDependencies:
+  # Keys the git checkout directory on the resolved ref, so the `nuxt/cli` sources on
+  # `3.x` and `main` stop overwriting each other's working tree.
+  # https://github.com/nuxt/content/pull/3839
+  '@nuxt/content': patches/@nuxt__content.patch

pnpm-workspace.yaml

@@ -0,0 +1,22 @@
+// Single source of truth for which `nuxt/cli` ref backs each docs version's
+// command reference. `3.x` is the released CLI; `main` is where v4 is developed and
+// where `@nuxt/cli-nightly` is published from, which is what `nuxt-nightly@5.x`
+// depends on, so a 5.x reader sees the CLI they actually install. Consumed by two
+// surfaces that must agree, or pages resolve their assets against a different ref
+// than they were parsed from:
+//
+//   - content.config.ts   → the `cliV*Source` collection sources
+//   - nuxt.config.ts      → `content:file:beforeParse` asset URL rewriting
+export const CLI_DOCS_REPO = 'nuxt/cli'
+
+// TODO: repoint docsv4 to `main` when the CLI v4 releases.
+export const CLI_DOCS_REFS = {
+  docsv3: '3.x',
+  docsv4: '3.x',
+  docsv5: 'main'
+} as const
+
+// Command docs live at `docs/` in `nuxt/cli` but mount under the API section of
+// each version tree, so this is both the source `prefix` and the marker that
+// identifies a CLI-sourced file inside the parse hook.
+export const CLI_DOCS_PREFIX = '4.api/4.commands'