This section documents version-specific API changes — prioritise recent major/minor releases and v2→v3 migrations.
-
BREAKING: queryContent() replaced with queryCollection() — v3 uses SQL-backed collections with explicit collection names. Migration: await queryContent(path).findOne() → await queryCollection('collectionName').path(path).first() source
-
BREAKING: fetchContentNavigation() replaced with queryCollectionNavigation() — navigation now queries a specific collection. source
-
BREAKING: searchContent() removed in favour of queryCollectionSearchSections() — full-text search API completely replaced. source
-
BREAKING: useContent() composable removed — no replacement in v3. source
-
NEW: queryCollectionItemSurroundings() — new API for getting previous/next items. queryContent().findSurround() → queryCollectionItemSurroundings('collection', targetPath) source
-
BREAKING: Document-driven mode removed — .md files no longer auto-convert to pages. Must create pages manually and use <ContentRenderer> to display content. source
-
BREAKING: Components <ContentDoc>, <ContentList>, <ContentNavigation>, <ContentQuery> dropped — all content rendering uses <ContentRenderer> component only. source
-
BREAKING: <ContentSlot> and <MDCSlot> components removed — use Vue's native <slot> with mdc-unwrap attribute instead. source
-
BREAKING: Components in components/content/ directory no longer auto-register globally — must register manually in Nuxt config. source
-
BREAKING: _dir.yml files renamed to .navigation.yml — reflects purpose of navigation metadata files. source
-
BREAKING: Document ._path renamed to .path, all _ prefixed internal fields removed or renamed — represents cleaner public API. source
-
BREAKING: NavItem type import path changed to ContentNavigationItem — import type { ContentNavigationItem } from '@nuxt/content' source
-
BREAKING: useContentHelpers() composable removed — equivalent functionality provided by query utilities. source
-
BREAKING: source option in module options removed — use content.config.ts to define collection sources instead. source
-
BREAKING: Sort order now alphabetical (not numerical) — due to SQL limitations. Check ordering documentation. source
-
BREAKING: Dot files no longer ignored by default — add ignore: ['**/.*'] in collection exclude options if needed. source
-
NEW: useSearchCollection() composable — client-side FTS5 full-text search with prefix matching, BM25 ranking, and snippets support. Added in v3.14.0. source
-
NEW: findPageHeadline(), findPageBreadcrumb(), findPageChildren(), findPageSiblings() utilities — helper functions for page hierarchy navigation. Added in v3.6.0 and v3.6.1. source
-
DEPRECATED: z re-export from @nuxt/content — import from zod or zod/v3 directly instead. Migration: import { z } from '@nuxt/content' → import { z } from 'zod' source
-
DEPRECATED: Calling .editor() directly on zod schemas — use property() wrapper instead. Migration: z.string().editor(...) → property(z.string()).editor(...) source
-
BREAKING: Built-in database adapters removed in favour of db0 connectors — v3.1.0 adoption of unified database connector pattern. source
-
NEW: node-sqlite3 connector support — v3.1.0 adds explicit node:sqlite3 driver for Node.js environments. source
-
NEW: bun sqlite connector for Bun runtime — explicit connector for Bun deployments added in v3.15.0. source
-
NEW: Type inference for extraFields in search — queryCollectionSearchSections() now infers custom fields in results (v3.14.0). source
-
NEW: NOT IN SQL operator support — expanded SQL operator types in v3.14.0. source
-
NEW: Custom properties on ContentConfig — allow extending config with application-specific properties (v3.14.0). source
-
NEW: contentRawMarkdown auto-generation feature — automatically generates markdown version of documents (v3.11.0). source
-
NEW: rewriteLLMSTxt option to disable path rewriting in llms.txt (v3.11.0). source
-
NEW: property() utility for schema field customization — replaces direct .editor() chaining pattern (v3.7.0). source
-
NEW: Support for <= and >= SQL operators — expanded comparison operators (v3.6.1). source
-
NEW: CSV file collections support — single CSV files can now be treated as page collections (v3.10.0). source
-
NEW: Optional database indexes — indexes option for collections to optimize query performance (v3.10.0). source
-
NEW: minHeading/maxHeading options for queryCollectionSearchSections() — control heading level range in search sections (v3.10.0). source
-
Always define collection schemas with Zod or Valibot in content.config.ts — this enforces data consistency, provides type safety, and drives form generation in Nuxt Studio source
-
Add database indexes to frequently filtered or sorted columns using the indexes array — composite indexes dramatically reduce D1 read costs on Cloudflare; without indexes, D1 counts all rows scanned rather than just matched results source
-
Use select() to fetch only needed fields when querying collections — reduces database overhead and improves response times, especially with large content sets source
-
Prefer Zod v4 over v3 — native JSON Schema export eliminates the zod-to-json-schema dependency and reduces build complexity source
-
Define collection sources explicitly with include patterns in content.config.ts — without this, all files in content/ are parsed by default, which can slow build times with large content sets source
-
Register content transformation hooks in nuxt.config.ts (not Nitro plugins) using hooks.content:file:beforeParse or hooks.content:file:afterParse — v3 hooks run at build time, not runtime source
-
Define custom properties added via hooks in your collection schema so they can be queried — properties added in content:file:afterParse hooks are only accessible if declared in the Zod schema source
-
Use useAsyncData(route.path, () => queryCollection(...).path(route.path).first()) for page queries — keying by route.path ensures proper caching and prevents stale content source
-
Use <ContentRenderer :value="page" /> for rendering markdown — this component converts parsed content AST to HTML and Prose components, avoiding manual DOM manipulation source
-
Override Prose components by creating components/content/Prose*.vue files — this is the standard way to customize how markdown elements (headings, links, code blocks) render without touching the content module source
-
Pass prose prop to <ContentRenderer> when you want automatic Prose component usage — without it, markdown renders as plain HTML source
-
Define rawbody: z.string() in collection schema to ship raw markdown to production — Nuxt Content auto-fills this field; use it for search, export, or client-side rendering workflows source
-
Avoid defining the same file in multiple collections — if a file matches multiple collection sources, hot reload breaks; use exclude patterns to prevent overlap source
-
Use useSearchCollection() for instant full-text search powered by SQLite FTS5 — zero-dependency built-in solution with prefix matching and snippet extraction source
