Contents

vite-plugin-vue-markdown

Compile Markdown to Vue component. A lite version of vite-plugin-md.

Use Markdown as Vue components
Use Vue components in Markdown

Install

npm i vite-plugin-vue-markdown -D # yarn add vite-plugin-vue-markdown -D

Add it to vite.config.js

// vite.config.js
import Vue from ‘@vitejs/plugin-vue’
import Markdown from ‘vite-plugin-vue-markdown’

export default {
plugins: [
Vue({
include: [/.vue$/, /.md$/], // <–
}),
Markdown()
],
}

And import it as a normal Vue component

Import Markdown as Vue components

export default {
components: {
HelloWorld,
},
}
</script>

Use Vue Components inside Markdown

You can even use Vue components inside your markdown, for example

Note you can either register the components globally, or use the <script setup> tag to register them locally.

import { createApp } from ‘vue’
import App from ‘./App.vue’
import Counter from ‘./Counter.vue’

const app = createApp(App)

// register global
app.component(‘Counter’, Counter) // <–

app.mount()

Or you can use vite-plugin-components for auto components registration.

Frontmatter

Frontmatter will be parsed and inject into Vue’s instance data frontmatter field.

For example:

—
name: My Cool App
—

# Hello World

This is {{frontmatter.name}}

Will be rendered as

<h1>Hello World</h1>
<p>This is My Cool App</p>

It will also be passed to the wrapper component’s props if you have set wrapperComponent option.

Document head and meta

To manage document head and meta, you would need to install @vueuse/head and do some setup.

npm i @vueuse/head

// vite.config.js
import Vue from ‘@vitejs/plugin-vue’
import Markdown from ‘vite-plugin-vue-markdown’

export default {
plugins: [
Vue({
include: [/.vue$/, /.md$/],
}),
Markdown({
headEnabled: true // <–
})
]
}

// src/main.js
import { createApp } from ‘vue’
import { createHead } from ‘@vueuse/head’ // <–

const app = createApp(App)

const head = createHead() // <–
app.use(head) // <–

Then you can use frontmatter to control the head. For example:

—
title: My Cool App
meta:
– name: description
content: Hello World
—

For more options available, please refer to @vueuse/head‘s docs.

Options

vite-plugin-vue-markdown uses markdown-it under the hood, see markdown-it‘s docs for more details

// vite.config.js
import Markdown from ‘vite-plugin-vue-markdown’

export default {
plugins: [
Markdown({
// default options passed to markdown-it
// see: https://markdown-it.github.io/markdown-it/
markdownItOptions: {
html: true,
linkify: true,
typographer: true,
},
// A function providing the Markdown It instance gets the ability to apply custom settings/plugins
markdownItSetup(md) {
// for example
md.use(require(‘markdown-it-anchor’))
md.use(require(‘markdown-it-prism’))
},
// Class names for the wrapper div
wrapperClasses: ‘markdown-body’
})
],
}

See the tsdoc for more advanced options

Example

See the /example.

Or the pre-configured starter template Vitesse.

Integrations

Work with vite-plugin-voie

import Markdown from ‘vite-plugin-vue-markdown’
import Voie from ‘vite-plugin-voie’

export default {
plugins: [
Voie({
extensions: [‘vue’, ‘md’],
}),
Markdown()
],
}

Put your markdown under ./src/pages/xx.md, then you can access the page via route /xx.

Work with vite-plugin-components

vite-plugin-components allows you to do on-demand components auto importing without worrying about registration.

import Markdown from ‘vite-plugin-vue-markdown’
import ViteComponents from ‘vite-plugin-components’

export default {
plugins: [
Markdown(),
// should be placed after `Markdown()`
ViteComponents({
// allow auto load markdown components under `./src/components/`
extensions: [‘vue’, ‘md’],

// allow auto import and register components used in markdown
customLoaderMatcher: path => path.endsWith(‘.md’),
})
],
}

Components under ./src/components can be directly used in markdown components, and markdown components can also be put under ./src/components to be auto imported.

TypeScript Shim

declare module ‘*.vue’ {
import type { ComponentOptions } from ‘vue’
const Component: ComponentOptions
export default Component
}

declare module ‘*.md’ {
import type { ComponentOptions } from ‘vue’
const Component: ComponentOptions
export default Component
}

Compile Markdown to Vue component