Markdown
Usage
Define a Collection
import { defineCollection, defineContentConfig, z } from '@nuxt/content'
export default defineContentConfig({
collections: {
blog: defineCollection({
type: 'page',
source: 'blog/*.md',
schema: z.object({
date: z.string()
})
})
}
})
.md
files Create
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('/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(slug).first()
})
</script>
<template>
<!-- Render the blog post as Prose & Vue components -->
<ContentRenderer :value="post" />
</template>
<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.
---
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
Key | Type | Default | Description |
title | string | First <h1> of the page | Title of the page, will also be injected in metas |
description | string | First <p> of the page | Description of the page, will be shown below the title and injected into the metas |
navigation | boolean | true | Define 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.
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
::
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
::
<!-- components/content/Card.vue -->
<template>
<div class="p-2 border bg-white dark:bg-black dark:border-gray-700 rounded">
<slot />
</div>
</template>
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.
::
<template>
<section>
<h1 class="text-4xl">
<slot mdc-unwrap="p" />
</h1>
<slot name="description" />
</section>
</template>
My Page Title
This will be rendered inside the description
slot.
<slot />
component.::the-title
A [rich text](/) will be **rendered** by the component.
::
<template>
<h1 class="text-4xl">
<slot mdc-unwrap="p" />
</h1>
</template>
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.
::
<script setup>
defineProps(['type'])
</script>
<template>
<div :class="[type]">
<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 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"]'}
::
::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>
Nuxt Architecture.
Harness the full power of Nuxt and the Nuxt ecosystem.
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}!
Hello World !
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.
Attributes work on:
- image,
- link,
code
, - italic and bold 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>
<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, 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:
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 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
}