Files

Markdown

Create and query Markdown files in your Nuxt applications and use the MDC syntax to integrate Vue components.

Usage

Define a Collection

content.config.ts
import { defineCollection, defineContentConfig, z } from '@nuxt/content'

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

Create .md files

Create blog posts in content/blog/ directory.

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

# Foo

This is Foo blog post.

Query Markdown Files

Now we can query blog posts:

// Get the foo post
const fooPost = await queryCollection('blog').path('/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.

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

<template>
  <!-- Render the blog post as Prose & Vue components -->
  <ContentRenderer :value="post" />
</template>
Read more about the <ContentRenderer> component and Prose Components.

Front-matter

Front-matter is a convention of Markdown-based CMS to provide meta-data to pages, like description or title. In Nuxt Content, the front-matter 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 front-matter block at the top of the Markdown files in the content/ directory with the --- identifier.

content/index.md
---
title: 'Title of the page'
description: 'meta description of the page'
---

<!-- Content of the page -->
example.ts
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

KeyTypeDefaultDescription
titlestringFirst <h1> of the pageTitle of the page, will also be injected in metas
descriptionstringFirst <p> of the pageDescription of the page, will be shown below the title and injected into the metas
navigationbooleantrueDefine if the page is included in queryCollectionNavigation return value.

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.

Install the MDC VS Code extension to get proper syntax highlighting for the MDC syntax.

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.

content/index.md
::component-name
Default slot content
::
Components that are used in Markdown has to be marked as global in your Nuxt app if you don't use the components/content/ directory, visit Nuxt 3 docs to learn more about it.

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
::

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.
::
Read more about the <slot /> component.
You can use Markdown inside your components slots:
::the-title
A [rich text](/) will be **rendered** by the component.
::

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.
::

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 front matter.

---
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"]'}
::

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.
---
::

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:

- ![](/favicon.ico){style="display: inline; margin: 0;"} image,
- [link](#attributes){style="background-color: pink;"}, `code`{style="color: cyan;"},
- _italic_{style="background-color: yellow; color:black;"} and **bold**{style="background-color: lightgreen;"} texts.

Binding Data in Markdown

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

Example 1: 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' }}

Example 2: Define in external with <ContentRenderer>

test.vue
<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>
test.md
# 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 πŸš€.
Read the complete Prose reference in the Prose Components section.

Code Highlighting

Nuxt Content uses Shiki, that 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:

Directory structure
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:

content/index.md
![my image](/image.png)

Excerpt

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

content/index.md
---
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 Front Matter props.

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

Example variables will be injected into the document:

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