0
# Nuxt Content
1

2
Nuxt Content is a comprehensive content management module for Nuxt.js applications that enables developers to build file-based content systems with powerful querying capabilities. It reads content from directories containing Markdown, YAML, CSV, or JSON files and creates a data layer with full TypeScript support, Vue component rendering in Markdown through MDC syntax, and blazing-fast hot module replacement during development.
3

4
## Package Information
5

6
- **Package Name**: @nuxt/content
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @nuxt/content`
10

11
## Core Imports
12

13
```typescript
14
import { queryCollection, queryCollectionNavigation } from '#content/composables';
15
import { ContentRenderer } from '#content/components';
16
```
17

18
For direct module imports:
19

20
```typescript
21
import { defineCollection, defineContentConfig, defineTransformer, z } from '@nuxt/content/utils';
22
import { findPageBreadcrumb, findPageChildren, findPageSiblings, findPageHeadline } from '@nuxt/content/utils';
23
import { field, group } from '@nuxt/content/preview';
24
import { compressTree, decompressTree, visit } from '@nuxt/content/runtime';
25
```
26

27
## Basic Usage
28

29
```typescript
30
// In pages/[...slug].vue or other composables
31
export default defineComponent({
32
  async setup() {
33
    // Query a single content item
34
    const article = await queryCollection('articles')
35
      .path('/blog/my-article')
36
      .first();
37

38
    // Query multiple items with filtering
39
    const posts = await queryCollection('blog')
40
      .where('published', '=', true)
41
      .order('date', 'DESC')
42
      .limit(10)
43
      .all();
44

45
    // Generate navigation from content
46
    const nav = await queryCollectionNavigation('pages');
47

48
    return { article, posts, nav };
49
  }
50
})
51
```
52

53
```vue
54
<template>
55
  <!-- Render content with full MDC support -->
56
  <ContentRenderer :value="article" />
57
</template>
58
```
59

60
## Architecture
61

62
Nuxt Content is built around several key architectural components:
63

64
- **Collections**: Type-safe content organization with flexible schemas and custom sources
65
- **Query Engine**: SQLite-based query builder with fluent API for filtering, sorting, and pagination
66
- **Content Pipeline**: Build-time processing with transformers, validation, and hot module replacement
67
- **MDC Renderer**: Vue component rendering within Markdown with full TypeScript support
68
- **Database Layer**: Flexible database adapters supporting SQLite, D1, PostgreSQL, and LibSQL
69
- **Preview System**: Live content editing with authentication and real-time updates
70

71
## Capabilities
72

73
### Content Querying
74

75
Powerful query system with fluent API for filtering, sorting, and retrieving content from collections. Includes full TypeScript support and SQLite-based performance.
76

77
```typescript { .api }
78
function queryCollection<T>(collection: T): CollectionQueryBuilder<Collections[T]>;
79

80
interface CollectionQueryBuilder<T> {
81
  path(path: string): CollectionQueryBuilder<T>;
82
  select<K>(...fields: K[]): CollectionQueryBuilder<Pick<T, K>>;
83
  where(field: string, operator: SQLOperator, value?: unknown): CollectionQueryBuilder<T>;
84
  order(field: keyof T, direction: 'ASC' | 'DESC'): CollectionQueryBuilder<T>;
85
  limit(limit: number): CollectionQueryBuilder<T>;
86
  skip(skip: number): CollectionQueryBuilder<T>;
87
  all(): Promise<T[]>;
88
  first(): Promise<T | null>;
89
  count(field?: keyof T | '*', distinct?: boolean): Promise<number>;
90
}
91
```
92

93
[Content Querying](./querying.md)
94

95
### Navigation Generation
96

97
Automatically generate navigation trees and hierarchical structures from your content collections with customizable field selection and filtering.
98

99
```typescript { .api }
100
function queryCollectionNavigation<T>(
101
  collection: T, 
102
  fields?: Array<keyof PageCollections[T]>
103
): ChainablePromise<T, ContentNavigationItem[]>;
104

105
interface ContentNavigationItem {
106
  title: string;
107
  path: string;
108
  stem?: string;
109
  children?: ContentNavigationItem[];
110
  page?: false;
111
  [key: string]: unknown;
112
}
113
```
114

115
[Navigation](./navigation.md)
116

117
### Content Rendering
118

119
Vue component system for rendering content with MDC (Markdown Components) support, custom component mapping, and prose styling.
120

121
```typescript { .api }
122
interface ContentRendererProps {
123
  value: object;
124
  excerpt?: boolean;
125
  tag?: string;
126
  components?: object;
127
  data?: object;
128
  prose?: boolean;
129
  class?: string | object;
130
  unwrap?: boolean | string;
131
}
132
```
133

134
[Content Rendering](./rendering.md)
135

136
### Collection Configuration
137

138
Type-safe collection definition system with schema validation, custom sources, and flexible content organization.
139

140
```typescript { .api }
141
function defineCollection<T>(collection: Collection<T>): DefinedCollection;
142
function defineContentConfig(config: ContentConfig): ContentConfig;
143

144
interface Collection<T> {
145
  type: 'page' | 'data';
146
  source?: string | CustomCollectionSource;
147
  schema?: ZodSchema<T>;
148
  fields?: CollectionFields<T>;
149
}
150
```
151

152
[Collections](./collections.md)
153

154
### Module Configuration
155

156
Comprehensive module configuration with database settings, preview mode, build options, and experimental features.
157

158
```typescript { .api }
159
interface ModuleOptions {
160
  database: DatabaseConfig;
161
  preview: PreviewOptions;
162
  watch: WatchOptions;
163
  renderer: RendererOptions;
164
  build: BuildOptions;
165
  experimental: ExperimentalOptions;
166
}
167
```
168

169
[Module Configuration](./configuration.md)
170

171
### Preview System
172

173
Live content editing system with field definitions, authentication, and real-time preview capabilities.
174

175
```typescript { .api }
176
function field(config: FieldConfig): PreviewField;
177
function group(config: GroupConfig): PreviewGroup;
178

179
interface PreviewField {
180
  type: PickerTypes;
181
  name: string;
182
  label?: string;
183
  required?: boolean;
184
}
185
```
186

187
[Preview System](./preview.md)
188

189
### Navigation Utilities
190

191
Helper functions for working with navigation trees, extracting breadcrumbs, children, siblings, and headlines from hierarchical content structures.
192

193
```typescript { .api }
194
function findPageBreadcrumb(
195
  navigation?: ContentNavigationItem[], 
196
  path?: string | undefined | null, 
197
  options?: FindPageBreadcrumbOptions
198
): ContentNavigationItem[];
199

200
function findPageChildren(
201
  navigation?: ContentNavigationItem[], 
202
  path?: string | undefined | null, 
203
  options?: FindPageOptions
204
): ContentNavigationItem[];
205

206
function findPageSiblings(
207
  navigation?: ContentNavigationItem[], 
208
  path?: string | undefined | null, 
209
  options?: FindPageOptions
210
): ContentNavigationItem[];
211

212
function findPageHeadline(
213
  navigation?: ContentNavigationItem[], 
214
  path?: string | undefined | null, 
215
  options?: FindPageOptions
216
): string | undefined;
217
```
218

219
[Navigation Utilities](./navigation-utilities.md)
220

221
### Runtime Utilities
222

223
Low-level utilities for working with content trees, compression, and AST manipulation for advanced content processing scenarios.
224

225
```typescript { .api }
226
function compressTree(input: MDCRoot): MinimarkTree;
227
function decompressTree(input: Tree): MDCRoot;
228
function visit(
229
  tree: Tree, 
230
  checker: (node: Node) => boolean, 
231
  visitor: (node: Node) => Node | undefined
232
): void;
233
```
234

235
[Runtime Utilities](./runtime-utilities.md)
236

237
## Types
238

239
```typescript { .api }
240
type SQLOperator = '=' | '!=' | '>' | '<' | '>=' | '<=' | 'IN' | 'NOT IN' | 'LIKE' | 'NOT LIKE';
241

242
interface Collections {
243
  [key: string]: CollectionType;
244
}
245

246
interface PageCollections {
247
  [key: string]: PageCollectionType;
248
}
249

250
interface ChainablePromise<T, R> extends Promise<R> {
251
  collection: T;
252
}
253

254
interface FindPageBreadcrumbOptions {
255
  current?: boolean;
256
  indexAsChild?: boolean;
257
}
258

259
interface FindPageOptions {
260
  indexAsChild?: boolean;
261
}
262

263
interface MDCRoot {
264
  type: 'root';
265
  children: Node[];
266
}
267

268
interface MinimarkTree {
269
  type: 'minimark';
270
  value: unknown;
271
}
272

273
interface Tree {
274
  type: string;
275
  value?: unknown;
276
}
277

278
interface Node {
279
  type: string;
280
  [key: string]: unknown;
281
}
282
```