Dark Mode

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Compile Markdown to Vue component

License

Notifications You must be signed in to change notification settings

unplugin/unplugin-vue-markdown

Repository files navigation

unplugin-vue-markdown

Compile Markdown to Vue component.

  • Use Markdown as Vue components.
  • Use Vue components in Markdown.
  • Supports Vite, Webpack, Vue CLI and more, powered by unplugin.
  • The same transformation as VitePress.

Install

npm i unplugin-vue-markdown
Vite
// vite.config.ts
import Vue from '@vitejs/plugin-vue'
import Markdown from 'unplugin-vue-markdown/vite'

export default defineConfig({
plugins: [
Vue({
include: [/\.vue$/, /\.md$/], // <-- allows Vue to compile Markdown files
}),
Markdown({ /* options */ }),
],
})

Example: examples/vite


Webpack
// webpack.config.js
const Markdown = require('unplugin-vue-markdown/webpack')
const { VueLoaderPlugin } = require('vue-loader')

module.exports = {
/* ... */
module: {
rules: [
// ... other rules
{
test: /\.(vue|md)$/,
loader: 'vue-loader'
}
]
},
plugins: [
new VueLoaderPlugin(),
Markdown({ /* options */ })
]
}

Vue CLI
{ config.module .rule('vue') .test(/\.(vue|md)$/) // <-- allows Vue to compile Markdown files config .plugin('markdown') .use(Markdown({ markdownUses: [ prism, ], })) }, }">// vue.config.js
const Markdown = require('unplugin-vue-markdown/webpack')

module.exports = {
parallel: false, // Disable thread-loader which will cause errors, we are still investigating the root cause
chainWebpack: (config) => {
config.module
.rule('vue')
.test(/\.(vue|md)$/) // <-- allows Vue to compile Markdown files

config
.plugin('markdown')
.use(Markdown({
markdownUses: [
prism,
],
}))
},
}

Example: examples/vue-cli


Import Markdown as Vue components

"><template>
<HelloWorld />
template>

<script>
import HelloWorld from './README.md'

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

Use Vue Components inside Markdown

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

"><Counter :init='5'/>

Note you can either register the components globally, or use the "><script setup>
import { Counter } from './Counter.vue'
script>

<Counter :init='5'/>

Or you can use unplugin-vue-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 Worldh1>
<p>This is My Cool Appp>

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 @unhead/vue and do some setup.

npm i @unhead/vue
// vite.config.js
import Vue from '@vitejs/plugin-vue'
import Markdown from 'unplugin-vue-markdown/vite'

export default {
plugins: [
Vue({
include: [/\.vue$/, /\.md$/],
}),
Markdown({
headEnabled: true // <--
})
]
}
// src/main.js
import { createHead } from '@unhead/vue/client' // <--
import { createApp } from 'vue'

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 @unhead/vue's docs.

Options

unplugin-vue-markdown uses markdown-exit under the hood, a TypeScript rewrite of markdown-it with built-in async rendering. markdown-it plugins are compatible.

Note: The old option names (markdownItOptions, markdownItUses, markdownItSetup) are deprecated but still functional.

// vite.config.js
import MarkdownItAnchor from 'markdown-it-anchor'
import MarkdownItPrism from 'markdown-it-prism'
import Markdown from 'unplugin-vue-markdown/vite'

export default {
plugins: [
Markdown({
// default options passed to markdown-exit
markdownOptions: {
html: true,
linkify: true,
typographer: true,
},
// A function providing the markdown-exit instance gets the ability to apply custom settings/plugins
markdownSetup(md) {
// for example
md.use(MarkdownItAnchor)
md.use(MarkdownItPrism)
},
// Class names for the wrapper div
wrapperClasses: 'markdown-body'
})
],
}

See the tsdoc for more advanced options

Example

See the /examples.

Or the pre-configured Markdown template Vitesse.

Integrations

import Vue from '@vitejs/plugin-vue'
import Markdown from 'unplugin-vue-markdown/vite'
import Pages from 'vite-plugin-pages'

export default {
plugins: [
Vue({
include: [/\.vue$/, /\.md$/],
}),
Pages({
extensions: ['vue', 'md'],
}),
Markdown()
],
}

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

unplugin-vue-components allows you to do on-demand components auto-importing without worrying about registration.

import Vue from '@vitejs/plugin-vue'
import Components from 'unplugin-vue-components/vite'
import Markdown from 'unplugin-vue-markdown/vite'

export default {
plugins: [
Vue({
include: [/\.vue$/, /\.md$/],
}),
Markdown(),
// should be placed after `Markdown()`
Components({
// allow auto load markdown components under `./src/components/`
extensions: ['vue', 'md'],

// allow auto import and register components used in markdown
include: [/\.vue$/, /\.vue\?vue/, /\.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
}

License

MIT License (c) 2020-PRESENT Anthony Fu

About

Compile Markdown to Vue component

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Stars

Watchers

Forks

Sponsor this project

Packages

Contributors