Nuxt Compile Markdown

Nuxt Module to compile markdown files into Vue SFC at build time. This enables you to put .md files into your pages/ directory as standalone pages, and .md under components/ directory as Vue components. With components auto-import built-in in Nuxt, you can also use any components in your markdown files.

• 📚 Write pages & components in Markdown
• 💚 Use Vue components in Markdown.
• 👌 Support SEO & Page Meta
• 📦 Built-in support for MDC (Markdown Components)
• 🧑‍💻 Syntax highlighting with light/dark mode support

Install

1. Add nuxt-compile-markdown dependency to your project

# Using pnpm
pnpm add -D nuxt-compile-markdown

# Using yarn
yarn add --dev nuxt-compile-markdown

# Using npm
npm install --save-dev nuxt-compile-markdown

2. Add nuxt-compile-markdown to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-compile-markdown'
  ]
})

3. Create your components or pages as Markdown ✨

components/
  HelloWorld.md
pages/
  about.md
  index.md

SEO & Page Meta

Use the seo property in the frontmatter to leverage useSeoMeta():

---
seo:
  title: My title
  description: My description
  ogImage: https://example.com/image.png
  twitterCard: summary_large_image
---

# My page

Will be transformed to:

<script setup>
useSeoMeta({
  title: 'My title',
  description: 'My description',
  ogImage: 'https://example.com/image.png',
  twitterCard: 'summary_large_image'
})
</script>

<-- template --->

Note: Use title and description as shortcut for seo.title and seo.description

Use the meta property in the frontmatter to leverage definePageMeta() for the pages/ directory:

---
meta:
  layout: dark
  middleware: log
---

# My page

Will be transformed to:

<script setup>
definePageMeta({
  layout: 'dark',
  middleware: 'log'
})
</script>

<-- template --->

Frontmatter

The frontmatter is parsed and injected into Vue's instance data frontmatter field.

---
name: My Page
---

# Hello World

This is {{ frontmatter.name }}

Import Markdown as Vue components

With Nuxt auto-import, all Markdown files inside the components/ directory will be imported when used:

components/
  HelloWorld.md
pages/
  index.md

Then in your pages/index.md:

I can use a Markdown component:

<HelloWorld />

MDC (Markdown Components) support is also built-in, meaning you can also do:

Inline :my-component{name="World"} syntax.

::HelloWorld
And also **block** syntax{.text-green}
::

If the Markdown is not inside the components/ directory, you can import it and use it as a normal Vue component:

<script setup>
import Readme from '../README.md'
</script>

<template>
  <Readme />
</template>

Syntax Highlighting

We have shiki built-in for syntax highlighting. It's enabled by default and supports light/dark mode out of the box.

To apply the dark mode theme, you will need to add a bit of CSS:

Query-based Dark Mode

@media (prefers-color-scheme: dark) {
  .shiki,
  .shiki span {
    background-color: var(--shiki-dark-bg) !important;
    color: var(--shiki-dark) !important;
  }
}

Class-based Dark Mode

html.dark .shiki,
html.dark .shiki span {
  background-color: var(--shiki-dark-bg) !important;
  color: var(--shiki-dark) !important;
}

You can learn more about the Dual Themes support.

<script> and <style>

Root-level <script> and <style> tags in Markdown files work just like they do in Vue SFCs, including <script setup>, <style module>, etc. The main difference here is that there is no <template> tag: all other root-level content is Markdown. Also note that all tags should be placed after the frontmatter:

---
hello: world
---

<script setup>
const count = ref(0)
</script>

## Markdown Content

The count is: {{ count }}

<button @click="count++">Increment</button>

Avoid <style scoped> in Markdown: When used in Markdown, <style scoped> requires adding special attributes to every element on the current page, which will significantly bloat the page size. <style module> is preferred when locally-scoped styling is needed in a page.

FAQ

How does this compare to @nuxt/content?

nuxt-compile-markdown works at built time and converts the Markdown files to Vue files for maximum performance. This module does not have the ability to query content like Nuxt Content Query Builder.