vite-plugin-md

Markdown for Vite

Use Markdown as Vue components
Use Vue components in Markdown

ℹ️ 0.2.x is for Vite 2 and 0.1.x is for Vite 1

Install

npm i vite-plugin-md -D # yarn add vite-plugin-md -D

TypeScript Shim

where needed:

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

declare module '*.md' {
  const Component: ComponentOptions
  export default Component
}

then add the following to vite.config.js

import Vue from '@vitejs/plugin-vue'
import Markdown from 'vite-plugin-md'

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

And import it as a normal Vue component

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> 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()

<script setup>
import { Counter } from './Counter.vue
</script>

<Counter :init='5'/>

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

then in your vite.config.js:

import Vue from '@vitejs/plugin-vue'
import Markdown from 'vite-plugin-md'

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.

Configuration / Options

Options Hash

The configuration for this plugin is a fully typed dictionary of options and therefore is largely self-documenting.

See the tsdoc for more advanced options

Markdown-It plugins (and options)

Under the hood this plugin leverages markdown-it for converting Markdown content to HTML. This parser is very mature and has a rich set of plugins that you use quite easily. If you don't find what you want you can also build your own plugin relatively easily [ docs ].

Whether you're using or building a plugin, you will incorporate it into this plugin using the markdownItSetup property. Alternatively you can also set configuration options of markdown-it with markdownItOptions:

// vite.config.js
import Markdown from 'vite-plugin-md'

export default {
  plugins: [
    Markdown({
      markdownItOptions: {
        html: true,
        linkify: true,
        typographer: true,
      },
      markdownItSetup(md) {
        // add anchor links to your H[x] tags
        md.use(require('markdown-it-anchor'))
        // add code syntax highlighting with Prism
        md.use(require('markdown-it-prism'))
      },
    }),
  ],
}

Builder APIs

Builder API's are mini-configurators for a particular feature area. The idea behind them is to allow extending functionality quickly with sensible defaults but also providing their own configurations to allow users to grow into and configure that feature area. The builder APIs available are:
- Link Builder
- Meta Builder
If you wanted to use both of these builders in their default configuration, you would simply add the following to your options config for this plugin:
```
import Markdown, { link, meta } from 'markdown-it-md'
export default {
  plugins: [
    Markdown({
      builders: [link(), meta()],
    }),
  ],
}
```
If you're interested in building your own you can refer to the Builder API docs.

Example

See the /example.

Or the pre-configured starter template Vitesse.

Integrations

This plugin has good integrations with several other plugins, including:

vite-plugin-pages
vite-plugin-components
vite-plugin-vue-layouts
for details, refer to the Integration Page

cwaring / vite-plugin-md