MDC supercharges regular Markdown to write documents interacting deeply with any Vue component.
MDC supercharges regular Markdown to write documents interacting deeply with any Vue component.
[![npm version][npm-version-src]][npm-version-href] [![npm downloads][npm-downloads-src]][npm-downloads-href] [![License][license-src]][license-href] [![Nuxt][nuxt-src]][nuxt-href]
[!IMPORTANT]
@nuxtjs/mdcis being deprecated in favor of Comark.Comark is the successor to MDC — it is faster, AI-friendly, and no longer bound to Vue or Nuxt. You can use it with Svelte, Vue, React, or any other framework.
Your existing markdown files are compatible — no content changes needed.
MDC supercharges regular Markdown to write documents interacting deeply with any Vue component. MDC stands for MarkDown Components.
added by each Markdown paragraph)Learn more about the MDC syntax on https://content.nuxt.com/docs/files/markdown
[!Note] You may utilize this package inside of your Nuxt project (standard configuration) or within any Vue project.
See Rendering in your Vue project below for more information.
npx nuxi@latest module add mdcThen, add @nuxtjs/mdc to the modules section of your nuxt.config.ts
export default defineNuxtConfig({
modules: ['@nuxtjs/mdc']
})That's it! You can start writing and rendering markdown files in your Nuxt project ✨
@nuxtjs/mdc exposes three components to render markdown files.
Using , you can parse and render markdown contents right inside your components/pages. This component takes raw markdown, parses it using the `parseMarkdown` function, and then renders it with .
Note that ::alert will use the components/mdc/Alert.vue component.
This component will take the result of parseMarkdown function and render the contents. For example, this is an extended version of the sample code in the Browser section which uses MDCRenderer to render the parsed markdown.
This component is a replacement for Vue's component, specifically designed for MDC. Using this component, you can render a component's children while removing one or multiple wrapping elements. In the below example, the Alert component receives text and its default slot (children). But if the component renders this slot using the normal, it will render a element around the text.
::alert
This is an Alert
::
It is the default behavior of markdown to wrap every text inside a paragraph. MDC didn't come to break markdown behavior; instead, the goal of MDC is to make markdown powerful. In this example and all similar situations, you can use `` to remove unwanted wrappers.
When using your own components in Markdown (::my-component ... ::), indentation inside the container matters.
For the renderer to work as expected, it's important that the indentation of the content nested within ::my-component ... :: aligns with the indentation of the ::my-component line itself.
Consider the following component with a named slot:
Both these work fine (in either default or named slots):
::alert
#slot1
slot-content
:: ::alert
#slot1
slot-content
::In particular, slot markers (for named slots) must not be indented relative to the ::my-component line. If the #slotName line (or its content) is further indented, MDC may fail to detect the slot and the content won’t render as expected:
::alert
#slot1
slot-content
::[!NOTE] When using default (unnamed) slots, content can still render, but if indented it may be parsed as a code block and end up wrapped in a ``.
It's recommended to keep #slotName and slot content aligned with the opening ::my-component line (no extra indentation inside the container).
Prose components are a list of components that will be rendered instead of regular HTML tags. For example, instead of rendering a tag, @nuxtjs/mdc renders a `` component. This is useful when you want to add extra features to your markdown files. For example, you can add a copy button to your code blocks.
You can disable prose components by setting the prose option to false in nuxt.config.ts. Or extend the map of prose components to add your own components.
export default defineNuxtConfig({
modules: ['@nuxtjs/mdc'],
mdc: {
components: {
prose: false, // Disable predefined prose components
map: {
p: 'MyCustomPComponent' // add global like MyCustomPComponent.global.vue
}
}
}
})In order to customize these components yourself simply make a component with the same name of the prose component you are trying to take control over. Make sure to put these prose components in their own prose folder and tell nuxt to globally register or simple create in prose folder P.global.vue them so that MDC can get proper access.
export default defineNuxtConfig({
modules: ['@nuxtjs/mdc'],
mdc: {
components: {
prose: true
}
},
components: {
global: true,
path: './components/prose'
}
})Here is the list of available prose components:
| Tag | Component | Source | Description |
|---|---|---|---|
p |
`` | ProseP.vue | Paragraph |
h1 |
`` | ProseH1.vue | Heading 1 |
h2 |
`` | ProseH2.vue | Heading 2 |
h3 |
`` | ProseH3.vue | Heading 3 |
h4 |
`` | ProseH4.vue | Heading 4 |
h5 |
`` | ProseH5.vue | Heading 5 |
h6 |
`` | ProseH6.vue | Heading 6 |
ul |
`` | ProseUl.vue | Unordered List |
ol |
`` | ProseOl.vue | Ordered List |
li |
`` | ProseLi.vue | List Item |
blockquote |
`` | ProseBlockquote.vue | Blockquote |
hr |
`` | ProseHr.vue | Horizontal Rule |
pre |
`` | ProsePre.vue | Preformatted Text |
code |
`` | ProseCode.vue | Code Block |
table |
`` | ProseTable.vue | Table |
thead |
`` | ProseThead.vue | Table Head |
tbody |
`` | ProseTbody.vue | Table Body |
tr |
`` | ProseTr.vue | Table Row |
th |
`` | ProseTh.vue | Table Header |
td |
`` | ProseTd.vue | Table Data |
a |
`` | ProseA.vue | Anchor Link |
img |
`` | ProseImg.vue | Image |
em |
`` | ProseEm.vue | Emphasis |
strong |
`` | ProseStrong.vue | Strong |
Nuxt MDC exposes a handy helper to parse MDC files. You can import the parseMarkdown function from @nuxtjs/mdc/runtime and use it to parse markdown files written with MDC syntax.
// server/api/parse-mdc.ts
import { parseMarkdown } from '@nuxtjs/mdc/runtime'
export default eventHandler(async () => {
const mdc = [
'# Hello MDC',
'',
'::alert',
'This is an Alert',
'::'
].join('\n')
const ast = await parseMarkdown(mdc)
return ast
})The parseMarkdown function is a universal helper, and you can also use it in the browser, for example inside a Vue component.
The parseMarkdown helper also accepts options as the second argument to control the parser's behavior. (Checkout MDCParseOptions interface↗︎).
| Name | Default | Description |
|---|---|---|
remark.plugins |
{} |
Register / Configure parser's remark plugins. |
rehype.options |
{} |
Configure remark-rehype options. |
rehype.plugins |
{} |
Register / Configure parser's rehype plugins. |
highlight |
false |
Control whether code blocks should highlight or not. You can also provide a custom highlighter. |
toc.depth |
2 |
Maximum heading depth to include in the table of contents. |
toc.searchDepth |
2 |
Maximum depth of nested tags to search for heading. |
Checkout MDCParseOptions types↗︎.
You can configure the module by providing the mdc property in your nuxt.config.js; here are the default options:
…Checkout ModuleOptions types↗︎.
The MDCRenderer also supports rendering nested async components by waiting for any child component in its tree to resolve its top-level async setup().
This behavior allows for rendering asynchronous MDC block components (e.g. via defineAsyncComponent) as well as introducing components that themselves internally utilize the MDCRenderer to render markdown before allowing the parent component to resolve.
In order for the parent MDCRenderer component to properly wait for the child async component(s) to resolve:
await (if no async/No open issues yet, or sync has not completed.