[larbish]

Warning

Draft for tracking what blocks Docus from moving to Nuxt Content v4. It's not meant to be merged. v4 is installed from local tarballs in .content-v4/ (git-excluded), so git-triggered builds fail. Previews are deployed from a local build with vercel build && vercel deploy --prebuilt.

Preview: https://docus-kwyzk3nyw-nuxtlabs.vercel.app

This PR replaces @nuxt/content v3 with the Nuxt Content v4 POC (@nuxt/content4, nuxt/content-v4-temp@dbac272) through a pnpm override, without upgrading any other dependency. The checklists below are everything still missing upstream for Docus to run on v4 without any change on its side. Build-time workarounds live in layer/modules/content-v4.ts, which does nothing on v3.

This PR won't be merged, it's just here to try the compatibility mode of Nuxt Content v4

Nuxt Content v4

To define

• [V4 fix or V4 Breaking change] Components in components/content/ aren't resolved, because v3 registered that folder globally without a prefix and v4 doesn't. :assistant-demo rendered as a raw <assistant-demo> tag → content-v4.ts

• [V4 fix or V4 Breaking change] #build/content/components.mjs now only re-exports the app's own and global components. That drops the Nuxt UI components written in markdown (::u-page-hero, ::u-page-card, ::u-button…): they render as raw tags, the landing page breaks, and only 34 of 194 routes get prerendered. The workaround re-exports every component and loads them on demand → content-v4.ts

• [V4 fix or V4 Breaking change] Links in content are unstyled, because ContentRenderer hardcodes a: NuxtLink, which bypasses Nuxt UI's ProseA. External links also lose v3's rel="nofollow" → DocsContentLink.vue, [...slug].vue, landing.vue

• [V4 fix or V4 Breaking change] Frontmatter fields outside the schema are no longer under meta, so sitemap: false and modifiedAt were ignored → urls.ts

V4 fix

• [V4 fix] @sqlite.org/sqlite-wasm isn't a dependency, but the default hybrid mode needs it (v3 shipped it) → layer/package.json

• [Improve test to reproduce on Vercel] Runtime content queries hang on serverless. The server fetches its own snapshot (/__nuxt_content/snapshot/<name>.json), which on Vercel only exists on the CDN, so the request reaches v4's /__nuxt_content/** handler and waits on itself until the 300 s timeout. mode: 'server-only' doesn't help: with a v3 content.config.ts the server instance is hard-coded to mode: 'hybrid', and server-only also stops the public snapshot from being generated → content-snapshot.ts, content-v4.ts ·

Tested on: nuxt/content-v4-temp#13

• [v4 fix] body is a bare node array instead of v3's { type: 'minimark', value, toc }, so the page TOC is empty. The workaround rebuilds the TOC from the nodes the way @nuxtjs/mdc did → toc.ts, DocsAsideRight.vue

Fixed on: nuxt/content-v4-temp#15

• [v4 fix] .navigation.yml files are ignored, because the YAML plugin isn't registered in v3 mode, so folder titles and icons are lost. The workaround reads them at build time and merges them back into the navigation → content-v4.ts, navigation.ts ·

Fixed on: nuxt/content-v4-temp#11

• [V4 fix] queryCollection(event, 'missing') throws immediately instead of returning a rejected promise, so /api/__sitemap__/urls returned 500 at runtime when a collection doesn't exist → urls.ts

• [V4 fix] Only Markdown files are read in v3 mode. .yml/.json files are skipped without a warning, because the yaml()/json() plugins aren't registered, and .csv has no plugin at all. So v3 data collections in those formats come back empty. Docus doesn't define any, but users extending it can, and the .navigation.yml workaround above only patches the navigation.

Fixed on: nuxt/content-v4-temp#11

• [V4 fix] The server bundle hard-codes the build machine's absolute content path (/Users/…/docs/content) as a fallback source. It's unused while the snapshot loads, but if the snapshot ever fails to load, collections would likely come back empty instead of throwing an error. The local path also ships in the deployed function.

Benchmark

• [Benchmark this later] Initial JS stays above v3: 412 KB vs 277 KB gzipped on a docs page, 366 KB vs 249 KB on the landing page.

Docus

• [Docus usecase: just add shiki as deps] Code highlighting (nuxt/content-v4-temp#7, merged) makes shiki an optional peer that it only looks for in the app's own dependencies, so in a layer setup even nuxt prepare crashes with Cannot resolve module "shiki". The workaround is a local fix that makes it a regular dependency resolved from the module → pnpm-workspace.yaml (locally patched tarball)

• [Docus will remove it] No @nuxt/content/preview (field/group), so nuxt.schema.ts failed to load. The workaround is a local copy of v3's helpers → preview.ts, nuxt.schema.ts

comark / comark-content

• [V4 fix: investigate into comark-content hub] "Edit this page" links broke, because stem is now relative to the collection folder and extension is .md instead of md → content-v4.ts, [...slug].vue ·

Tested on: nuxt/content-v4-temp#12

• [Comark content fix] The SQL plugin of comark-content doesn't coordinate index builds: concurrent first queries of a collection each rebuild its table, and one can drop it while another reads, so pages, navigation or prev/next links come back missing. v4's latest comark-content build (pkg.pr.new 6708f9b) still needs the patch from nuxt/content-v4-temp, so a published release with the fix is needed. The patch is already applied in the repacked tarball → pnpm-workspace.yaml

Fixed on: https://github.com/comarkdown/comark-content/pull/133

• [Reproduciton test needed] With Docus on comark, agents should get markdown/comark output, which fixes the markdown/html issues (escaped attributes like class="[&>div]:*:my-0", MDC slots inside HTML tags) and the nesting problems that motivated #1449. It's blocked by a serializer bug: a code sample that itself contains indented ``` fences is written with a three-backtick fence instead of four, so it closes early and the rest of the page is parsed as code (Steps example in components.md).

nuxt-agent-discovery

• [@benjamincanac nuxt-agent-discovery fix] moduleDependencies pins @nuxt/content to ^3.0.0, so Nuxt refuses v4 → patches/nuxt-agent-discovery@0.7.0.patch

• [@benjamincanac nuxt-agent-discovery fix: should use comark-content way now for v4] The built-in Content source depends on v3 internals: #content/manifest (not generated by v4), minimark/stringify (borrowed from @nuxt/content's dependencies) and v3's body.value. On v4 it should switch to the comark adapter wired to v4's server content by itself → layer/server/agent-source.ts, layer/nuxt.config.ts

• [@benjamincanac To investigate] With a custom source, /sitemap.md and /raw/index.md aren't prerendered (they're served at runtime), so pnpm check:vercel-output fails.

Nuxt Studio

• Plugin for collection json schema to generate frontmatter form / yaml forms

• [Studio fix: inline compatibility functions] It imports #content/preview (the v3 preview API), @nuxt/content/runtime (compressTree/decompressTree) and @nuxt/content/server, none of which v4 provides, so it can't build → disabled in docs/nuxt.config.ts

Nuxt UI

• [@benjamincanac To investigate] Prose headings read runtimeConfig.public.mdc.headings.anchorLinks, which @nuxtjs/mdc sets and v4 no longer installs. Heading anchors disappeared and inline code in headings lost its size → content-v4.ts

• [@benjamincanac To investigate] Highlight themes come from @nuxtjs/mdc defaults, so v4 used the GitHub themes instead of Nuxt UI's material-theme-* → content-v4.ts

🤖 Generated with Claude Code, reviewed by @larbish before opening.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docus	Error		Oct 23, 2026 8:39am UTC