Usage

Define a Collection

import { defineCollection, defineContentConfig } from '@nuxt/content'
import { z } from 'zod'

export default defineContentConfig({
  collections: {
    blog: defineCollection({
      type: 'page',
      source: 'blog/*.md',
      schema: z.object({
        date: z.string()
      })
    })
  }
})

Create .md files

Create blog posts in content/blog/ directory.

---
date: 2020-11-11
---

# Foo

This is Foo blog post.

---
date: 2024-12-12
---
Hello
I am bar. Nice to meet you.

Query Markdown Files

Now we can query blog posts:

// Get the foo post
const fooPost = await queryCollection('blog').path('/blog/foo').first()

// Find all posts
const allPosts = await queryCollection('blog').order('date', 'DESC').all()

Display Markdown

To display the content of a markdown file, you can use the <ContentRenderer> component.

<script setup>
const slug = useRoute().params.slug
const { data: post } = await useAsyncData(`blog-${slug}`, () => {
  return queryCollection('blog').path(`/blog/${slug}`).first()
})
</script>

<template>
  <!-- Render the blog post as Prose & Vue components -->
  <ContentRenderer :value="post" />
</template>

Frontmatter

Frontmatter is a convention of Markdown-based CMS to provide meta-data to pages, like description or title. In Nuxt Content, the frontmatter uses the YAML syntax with key: value pairs.

These data are available when rendering the content and can store any information that you would need.

Syntax

You can declare a frontmatter block at the top of the Markdown files in the content/ directory with the --- identifier.

---
title: 'Title of the page'
description: 'meta description of the page'
---

<!-- Content of the page -->

const home = await queryCollection('content').path('/').first()

console.log(home.title)
// => 'Title of the page'
console.log(home.description)
// => 'meta description of the page'
console.log(home.body)
// => AST object of the page content

Native parameters

MDC Syntax

We created the MDC syntax to supercharge Markdown and give you the ability to integrate Vue components with slots and props inside your Markdown.

Vue Components

You can use any Vue component in your Markdown files.

We have a special syntax to make it easier to use components in your Markdown files.

::component-name
Default slot content
::

Block Components

Block components are components that accept Markdown content or another component as a slot.

The component must contain at least one <slot /> component to accept formatted text.

In a markdown file, use the component with the :: identifier.

::card
The content of the card
::

<!-- components/content/Card.vue -->
<template>
  <div class="p-2 border bg-white dark:bg-black dark:border-gray-700 rounded">
    <slot />
  </div>
</template>

Slots

A component's slots can accept content or another components.

• Default slot renders the top-level content inside the block component or with #default
• Named slots use the # identifier to render the corresponding content.

::hero
My Page Title

#description
This will be rendered inside the `description` slot.
::

<template>
  <section>
    <h1 class="text-4xl">
      <slot mdc-unwrap="p" />
    </h1>
    <slot name="description" />
  </section>
</template>

::my-title
A [rich text](/) will be **rendered** by the component.
::

<template>
  <h1 class="text-4xl">
    <slot mdc-unwrap="p" />
  </h1>
</template>

Props

There are two ways to pass props to components using MDC.

Inline method

The {} identifier passes props to components in a terse way by using a key=value syntax.

::alert{type="warning"}
The **alert** component.
::

<script setup>
const props = defineProps({ type: { type: String } })

const alertClass = computed(() => {
  return {
    warning: 'bg-orange-100 border-orange-200 dark:bg-orange-900 dark:border-orange-800',
    info: 'bg-blue-100 border-blue-200 dark:bg-blue-900 dark:border-blue-800',
    success: 'bg-green-100 border-green-200 dark:bg-green-900 dark:border-green-800',
  }[props.type]
})
</script>

<template>
  <div
    class="text-black p-2 border dark:text-white rounded"
    :class="alertClass"
  >
    <slot mdc-unwrap="p" />
  </div>
</template>

Multiple props can be separated with a space:

::alert{type="warning" icon="exclamation-circle"}
Oops! An error occurred
::

The v-bind shorthand : can be also be used to bind a prop to a value in the frontmatter.

---
type: "warning"
---

::alert{:type="type"}
Your warning
::

If you want to pass arrays or objects as props to components you can pass them as JSON string and prefix the prop key with a colon to automatically decode the JSON string. Note that in this case you should use single quotes for the value string so you can use double quotes to pass a valid JSON string:

::dropdown{:items='["Nuxt", "Vue", "React"]'}
::

::dropdown{:items='[1,2,3.5]'}
::

::chart{:options='{"responsive": true, "scales": {"y": {"beginAtZero": true}}}'}
::

YAML method

The YAML method uses the --- identifier to declare one prop per line, that can be useful for readability.

::icon-card
---
icon: IconNuxt
description: Harness the full power of Nuxt and the Nuxt ecosystem.
title: Nuxt Architecture.
---
::

<script setup>
defineProps({
  title: {
    type: String,
    default: 'Default title'
  },
  description: {
    type: String,
    default: 'Default description'
  },
  icon: {
    type: String,
    default: 'IconMarkdown'
  }
})
</script>

<template>
  <div class="p-6 border bg-white dark:bg-black dark:border-gray-700 rounded">
    <component :is="icon" class="w-20 h-20" />
    <h2 class="text-3xl font-semibold mb-2">
      {{ title }}
    </h2>
    <p>{{ description }}</p>
  </div>
</template>

Attributes

Attributes are useful for highlighting and modifying part of paragraph. The syntax is nearly similar to inline components and markdown links syntax.

Possible values are all named attributes, classes with the notation .class-name and an ID with #id-name.

Hello [World]{style="color: green;" .custom-class #custom-id}!

In addition to mdc components and span, attribute syntax will work on images, links, inline code, *bold* and _italic_ text.

Attributes work on:

- [link](#attributes){style="background-color: green;"}, `code`{style="color: cyan;"},
- _italic_{style="background-color: yellow; color:black;"} and **bold**{style="background-color: lightgreen;"} texts.

Binding Data

You can bind data within your Markdown document using the {{ $doc.variable || 'defaultValue' }} syntax. These values can be defined in the YAML frontmatter at the top of the document, within each MDC component, or injected using the data prop of the <ContentRenderer> component.

Define in YAML

---
title: 'Title of the page'
description: 'meta description of the page'
customVariable: 'Custom Value'
---

# The Title is {{ $doc.title }} and customVariable is {{ $doc.customVariable || 'defaultValue' }}

Define in external with <ContentRenderer>

<template>
  <div>
    <ContentRenderer :value="data" :data="mdcVars"/>
    <button type="button" v-on:click="mdcVars.name = 'Hugo'">Change name</button>
  </div>
</template>

<script setup lang="ts">
const { data } = await useAsyncData(() => queryCollection('content').path('/test').first());
const mdcVars = ref({ name: 'Maxime'});
</script>

# Hello {{ $doc.name || 'World' }}

Prose Components

In Nuxt Content, the prose represents HTML tags generated by the Markdown syntax, such as heading levels and links.

For each HTML tag, a Vue component is used, allowing you to override them if needed, for example <p> becomes <ProseP>.

If you want to customize a Prose component, here are the recommended steps:

• Check out the original component sources.
• Use the exact same props.
• In your components/content/ directory, give it the same name.
• Make it yours 🚀.

Code Highlighting

Nuxt Content uses Shiki, which colors tokens with VSCode themes.

Code highlighting works both on ProsePre and ProseCode.

Each line of a code block gets its line number in the line attribute so lines can be labeled or individually styled.

Images

You can add images to your public directory:

content/
  index.md
public/
  image.png
nuxt.config.ts
package.json

And then use them in your markdown files in the content directory as such:

![my image](/image.png)

Excerpt

Content excerpt or summary can be extracted from the content using <!--more--> as a divider.

---
title: Introduction
---

Learn how to use `@nuxt/content`.

<!--more-->

Full amount of content beyond the more divider.

Description property will contain the excerpt content unless defined within the frontmatter props.

If there is no <!--more--> divider in the text then excerpt is undefined.

const content = defineCollection({
  type: 'page',
  source: '**',
  schema: z.object({
    excerpt: z.object({
      type: z.string(),
      children: z.any(),
    }),
  }),
})

Example variables will be injected into the document:

{
  "excerpt": Object
  "body": Object
  // ... other keys
}