unplugin/unplugin-vue-markdownPublic

NotificationsYou must be signed in to change notification settings
Fork37
Star600

Compile Markdown to Vue component

License

MIT license

600 stars 37 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 239 Commits
.github		.github
.vscode		.vscode
examples		examples
scripts		scripts
src		src
test		test
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

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 byunplugin.
⚡️ The same transformation asVitePress.

Install

npm i unplugin-vue-markdown

Vite

// vite.config.tsimportVuefrom'@vitejs/plugin-vue'importMarkdownfrom'unplugin-vue-markdown/vite'exportdefaultdefineConfig({plugins:[Vue({include:[/\.vue$/,/\.md$/],// <-- allows Vue to compile Markdown files}),Markdown({/* options */}),],})

Example:examples/vite

Webpack

// webpack.config.jsconstMarkdown=require('unplugin-vue-markdown/webpack')const{ VueLoaderPlugin}=require('vue-loader')module.exports={/* ... */module:{rules:[// ... other rules{test:/\.(vue|md)$/,loader:'vue-loader'}]},plugins:[newVueLoaderPlugin(),Markdown({/* options */})]}

Vue CLI

// vue.config.jsconstMarkdown=require('unplugin-vue-markdown/webpack')module.exports={parallel:false,// Disable thread-loader which will cause errors, we are still investigating the root causechainWebpack:(config)=>{config.module.rule('vue').test(/\.(vue|md)$/)// <-- allows Vue to compile Markdown filesconfig.plugin('markdown').use(Markdown({markdownItUses:[prism,],}))},}

Example:examples/vue-cli

Import Markdown as Vue components

<template><HelloWorld/></template><script>importHelloWorldfrom'./README.md'exportdefault{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> tag to register them locally.

import{createApp}from'vue'importAppfrom'./App.vue'importCounterfrom'./Counter.vue'constapp=createApp(App)// register globalapp.component('Counter',Counter)// <--app.mount()

<scriptsetup>import{Counter}from'./Counter.vue'</script><Counter:init='5'/>

Or you can useunplugin-vue-components for auto components registration.

Frontmatter

Frontmatter will be parsed and inject into Vue's instance datafrontmatter field.

For example:

---name:My Cool App---#Hello WorldThis 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 setwrapperComponent 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.jsimportVuefrom'@vitejs/plugin-vue'importMarkdownfrom'unplugin-vue-markdown/vite'exportdefault{plugins:[Vue({include:[/\.vue$/,/\.md$/],}),Markdown({headEnabled:true// <--})]}

// src/main.jsimport{createHead}from'@unhead/vue/client'// <--import{createApp}from'vue'constapp=createApp(App)consthead=createHead()// <--app.use(head)// <--

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

---title:My Cool Appmeta:  -name:descriptioncontent:Hello World---

For more options available, please refer to@unhead/vue's docs.

Options

unplugin-vue-markdown usesmarkdown-it under the hood, seemarkdown-it's docs for more details

// vite.config.jsimportMarkdownItAnchorfrom'markdown-it-anchor'importMarkdownItPrismfrom'markdown-it-prism'importMarkdownfrom'unplugin-vue-markdown/vite'exportdefault{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/pluginsmarkdownItSetup(md){// for examplemd.use(MarkdownItAnchor)md.use(MarkdownItPrism)},// Class names for the wrapper divwrapperClasses:'markdown-body'})],}

Seethe tsdoc for more advanced options

Example

See the/examples.

Or the pre-configured Markdown templateVitesse.

Integrations

Work withvite-plugin-pages

importVuefrom'@vitejs/plugin-vue'importMarkdownfrom'unplugin-vue-markdown/vite'importPagesfrom'vite-plugin-pages'exportdefault{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.

Work withunplugin-vue-components

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

importVuefrom'@vitejs/plugin-vue'importComponentsfrom'unplugin-vue-components/vite'importMarkdownfrom'unplugin-vue-markdown/vite'exportdefault{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 markdowninclude:[/\.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'{importtype{ComponentOptions}from'vue'constComponent:ComponentOptionsexportdefaultComponent}declare module'*.md'{importtype{ComponentOptions}from'vue'constComponent:ComponentOptionsexportdefaultComponent}