unplugin-vue-markdown

30.0.0 · active · verified Sun Apr 19

unplugin-vue-markdown is a compiler that transforms Markdown files into Vue components, enabling the seamless integration of Markdown content within Vue applications. It supports using Markdown as Vue components and embedding Vue components directly within Markdown. Currently at version 30.0.0, the library follows an active release cadence, frequently updating to support the latest versions of build tools like Vite and Node.js. Its primary differentiator is its `unplugin` architecture, allowing broad compatibility across Vite, Webpack, and Vue CLI, and offering a transformation pipeline similar to VitePress. This makes it a versatile tool for documentation sites, blogs, and content-driven applications built with Vue, especially those prioritizing Markdown as a primary content format. Recent major updates have focused on dependency modernizations and dropping support for older Node.js versions.

Common errors

```
Syntax Error: Markdown files are not valid Vue components.
```
cause The `@vitejs/plugin-vue` is not configured to include Markdown files, preventing them from being compiled into Vue components.

fix In `vite.config.ts`, add `include: [/\.vue$/, /\u005c.md$/]` to your `Vue()` plugin options.
```
TypeError: Cannot read properties of undefined (reading 'renderer')
```
cause This error can occur in v30.0.0 if you were previously configuring `markdown-it` directly or using `markdown-it` specific plugins that are incompatible with the new `markdown-exit` dependency.

fix Review your `unplugin-vue-markdown` options, especially `markdownUses`, and ensure any custom markdown parsing logic or plugins are compatible with or migrated to `markdown-exit`.
```
Error: Node.js v16 is not supported by unplugin-vue-markdown@^29.0.0
```
cause Your Node.js version is below the minimum requirement (v20+) introduced in `unplugin-vue-markdown` v29.0.0.

fix Upgrade your Node.js environment to version 20 or newer using a version manager like `nvm` or `volta`.
```
webpack-cli failed with error: TypeError: this.getOptions is not a function
```
cause This specific error can sometimes occur in Vue CLI or Webpack builds when `thread-loader` (which Vue CLI uses by default for parallel builds) conflicts with certain plugins.

fix In your `vue.config.js`, set `parallel: false` to disable `thread-loader`.

Warnings

breaking Version 30.0.0 replaced `markdown-it` and `markdown-it-async` with `markdown-exit`. If you had custom `markdown-it` configurations or plugins, they will no longer work and require migration or re-implementation for `markdown-exit`.
Fix: Review your `markdownUses` options and any direct `markdown-it` instance customizations. Consult `markdown-exit` documentation for equivalent functionality.
breaking Version 29.0.0 requires Node.js v20 or higher. Previous versions may have supported Node.js v16 or v18.
Fix: Upgrade your Node.js environment to version 20 or newer. Check your `engines` field in `package.json`.
breaking Version 28.0.0 (following v0.28.0) dropped support for Node.js 16 and Webpack 4. Ensure your project meets the updated engine requirements.
Fix: Upgrade your Node.js to a supported version (>=20.0.0) and update Webpack to version 5 or newer if you are using it.
gotcha When using `@vitejs/plugin-vue`, you MUST include `[/\.vue$/, /\u005c.md$/]` in its `include` option. Without it, Markdown files will not be processed by Vue and will lead to build errors or incorrect rendering.
Fix: Ensure your `vite.config.ts` has `Vue({ include: [/\.vue$/, /\u005c.md$/] })`.
gotcha For Vue CLI users, it's necessary to set `parallel: false` in `vue.config.js` to disable `thread-loader`. Failure to do so can cause build errors or unexpected behavior.
Fix: Add `parallel: false` directly in your `module.exports` object within `vue.config.js`.

Install

npm install unplugin-vue-markdown npm
yarn add unplugin-vue-markdown yarn
pnpm add unplugin-vue-markdown pnpm

Imports

Markdown
wrong:
```
import { Markdown } from 'unplugin-vue-markdown/vite'
```
correct:
```
import Markdown from 'unplugin-vue-markdown/vite'
```
This is the primary import for Vite projects and is a default export. Do not use named imports.
Markdown
wrong:
```
import Markdown from 'unplugin-vue-markdown/webpack'
```
correct:
```
const Markdown = require('unplugin-vue-markdown/webpack')
```
For Webpack and Vue CLI configurations, the CommonJS `require` syntax is typically used, especially in older setups.
Options
```
import type { Options } from 'unplugin-vue-markdown'
```
Import types for configuration options when using TypeScript.

Quickstart

This quickstart demonstrates how to configure `unplugin-vue-markdown` with Vite and `@vitejs/plugin-vue` to enable Markdown file processing as Vue components. It highlights the essential `include` option.

import { defineConfig } from 'vite'
import Vue from '@vitejs/plugin-vue'
import Markdown from 'unplugin-vue-markdown/vite'

// Install dependencies:
// npm install -D vite @vitejs/plugin-vue unplugin-vue-markdown vue

export default defineConfig({
  plugins: [
    Vue({
      include: [/\.vue$/, /\u005c.md$/], // <-- Crucial: enables Vue to process .md files
    }),
    Markdown({
      // Optional configuration, e.g., enabling head management
      // headEnabled: true,
      // markdownUses: [ require('markdown-it-prism') ] // Example for a custom markdown-it plugin (ensure compatibility with markdown-exit in v30)
    }),
  ],
})

// To use in a Vue component (e.g., App.vue):
// <template>
//   <MyMarkdownContent />
// </template>
// <script setup>
// import MyMarkdownContent from './path/to/my-doc.md'
// </script>

view raw JSON →