Vite-Vue-MD: Import .md file as Vue.js Components
This Vite plugin adds support for importing a Markdown file as a Vue component. Works with Vue 2 & 3.
Vue.js Demo Blocks
Render your Vue.js code blocks inline by simply adding demo
next to the language name.
For example, when this Markdown file is rendered with this plugin, you'll see a clickable button here:
```vue demo
<script setup>
const clickHandler = () => alert('Clicked!')
</script>
<template>
<button @click="clickHandler">
Click me
</button>
</template>
```(end)
Install
npm install -D vite-vue-md
Setup
In your vite.config.js
file:
- Import
vite-vue-md
and add it to theplugins
array. - In your
vue()
plugin options, add ainclude
option that includes.md
files.
vite.config.js:
import vue from '@vitejs/plugin-vue'
+ import vueMd from 'vite-vue-md'
export default {
plugins: [
// ...
vue({
+ include: [/\.vue$/, /\.md$/] // ← Treat MD files as Vue components
}),
+ vueMd(/* Options */) // ← Compile MD files to Vue components
]
// ...
}
To compile a Vue.js codeblock as a Demo Block, add demo
next to the language name:
```vue demo
<script setup>
const clickHandler = () => alert('Clicked!');
</script>
<template>
<button @click="clickHandler">
Click me
</button>
</template>
```(end)
Multi-file demos
The entry point for demo blocks must be a Vue.js component. But you can import other code blocks in any language from the same Markdown file.
For non-entry files, set a file name via demo=<file name>
. Then import it from the Vue.js demo block via the doc:
protocol:
<script setup>
import { clickHandler } from 'doc:click-handler.js'
</script>
<template>
<button @click="clicked">
Click me
</button>
</template>
Second file:
demo=click-handler.js
export const clickHandler = () => alert('Clicked!');
Demo + Code blocks
Since the code blocks are rendered inline, they're replaced by the actual Vue.js component. To show the code block, you can add a onDemo
callback to the plugin options:
({
onDemo(componentTag, code) {
// Register the wrapper component
this.registerComponent('DemoContainer', './DemoContainer.vue')
// Return a custom HTML string
return `
<DemoContainer>
<!-- Inline the component here -->
${componentTag}
<!-- Pass in the code block here -->
<template #code>
<template v-pre>${this.escapeHtml(code)}</template>
</template>
</DemoContainer>
`
}
})
Options
include
Type: ReadonlyArray<string | RegExp> | string | RegExp
Files to include from being compiled as Vue files.
exclude
Type: ReadonlyArray<string | RegExp> | string | RegExp
Files to exclude from being compiled as Vue files.
markdownItOptions
Type: markdownIt.Options
MarkdownIt options. See MarkdownIt's documentation for more information.
markdownItSetup
Type: (md: markdownIt) => void;
Callback to add plugins to MarkdownIt.
wrapperClass
Type: string
Default: markdown-body
The class to add to the wrapper element that contains the Markdown page.
onDemo
Type:
(
tag: string,
code: string,
demos: Map<string, string>
) => string
You can intercept each demo block and return a custom HTML string. This is useful for adding custom styling to demo blocks.
In addition, there are utils exposed in the this
context:
escapeHtml
: Escape HTML code to prevent it from being rendered as HTML.registerComponent
: Register a component to be used in the demo block. This is useful for registering components that are imported from other files.
See example above in the Demo Blocks section.
markdownCss
Type: string
File path to a stylesheet to use for the Markdown page. This will be added using <style scoped>
so it will only apply to the markdown page. Useful for styling only the HTML generated by the MarkdownIt plugin.
useVOnce
Type: boolean
Whether to add v-once
to the entire Markdown page. This will prevent the Markdown page from being re-rendered when the Vue component is updated.
Warning: This will disable demo blocks. Only use this if you have a large document and don't need demo blocks.
Related
unplugin-vue-markdown
Another Vite plugin for compiling Markdown files to Vue components.
This plugin has drawn inspiration from it but has a different feature set. This plugin only supports Vue.js code in code blocks.