MDC Syntax

MDC stands for MarkDown Components. This syntax supercharges regular Markdown to write documents interacting deeply with any Vue component from your components/content/ directory or provided by a module.

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

Block Components

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

Any component in the components/content/ directory or made available globally in your application can be used in Markdown files.

The component must contain either:

  • A <slot /> to accept raw text or another component.
  • The <ContentSlot /> component to accept formatted text.

In a markdown file, use the component with the :: identifier.
::cardThe content of the card::
<template>  <div class="p-6 border bg-white dark:bg-black dark:border-gray-700 rounded">    <slot />  </div></template>

The content of the card


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

  • The default slot renders the top-level content inside the block component.
  • named slots use the # identifier to render the corresponding content.
::heroDefault slot text#descriptionThis will be rendered inside the `description` slot.::
<template>  <section>    <h1 class="text-4xl"><slot /></h1>    <slot name="description"/>  </section></template>

Default slot text

This will be rendered inside the description slot.


MDC supports nested components inside slots by indenting them.
::hero  :::card    A nested card    ::card      A super nested card    ::  :::::

A nested card

A super nested card

You can add more :::: when nesting components as a visual reminder.

Markdown rendering

The <ContentSlot /> component is auto-imported by Nuxt Content. It acts as a special slot that accepts rich text rendered by Markdown.

The unwrap prop accepts an HTML tag that will be used to unwrap the content, useful when using tags such as title tags (<h1>, <h2>, ...) or inline tags (<button>, <a>, ...).

<template>  <h1 class="text-4xl">    <ContentSlot :use="$slots.default" unwrap="p" />  </h1></template>
::the-titleA [rich text](/) will be **rendered** by the component.::

A rich text will be rendered by the component.

The <ContentSlot /> component can act as a named slot with the use property:

<ContentSlot :use="$slots.description" unwrap="p">

Inline components

Inline components are components without slots or <ContentSlot />.

They can be used with the : identifier.
# Title:banner
<template>  <aside>    This component does not have any children.  </aside></template>

If you want to use an inline component followed by specific characters like -, _ or :, you can use a dummy props specifier after it.


In this example, :hello{} will search for the <Hello /> component, and -world will be plain text.


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]">  <ContentSlot :use="$slots.default" unwrap="p" /></div></template>
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"}

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

Span Text

To create inline spans in your text you can use the [] identifier.

Hello [World]{.bg-blue-500}!

Hello World!


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

Hello [World]{.text-primary-500}!

Hello World!

Other than spans the attribute syntax will work on images, links, code, bold and italic texts.

Attributes works on:- ![](/icon.png){} image,- [link](#attributes){.bg-primary-400}, `code`{.text-red-500},- _italic_{.bg-primary-500} and **bold**{.bg-primary-500} texts.

Attributes works on:

  • image,
  • link, code,
  • italic and bold texts.