vite-vue-md

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:

<script setup>
const clickHandler = () => alert('Clicked!')
</script>

<template>
    <button @click="clickHandler">
        Click me
    </button>
</template>

Install

npm install -D vite-vue-md

Setup

In your vite.config.js file:

1. Import vite-vue-md and add it to the plugins array.
2. In your vue() plugin options, add a include 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
      ]
      // ...
  }

Demo Blocks

Demo Blocks are Vue.js code blocks that are rendered inline. They're useful for documentation docs to show off your components without compromising the readability of the Markdown file on GitHub.

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>
```

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:

Entry file:
```vue demo
<script setup>
import { clickHandler } from 'doc:click-handler.js'
</script>

<template>
    <button @click="clicked">
        Click me
    </button>
</template>
```

Second file:
```js 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.