Vue Markdown Loader

Common errors

• Module build failed (from ./node_modules/vue-markdown-loader/index.js): Error: Cannot find module 'vue-loader/lib/plugin'

  cause `VueLoaderPlugin` is missing from your webpack plugins array, or `vue-loader` version is incompatible with your setup.
  fix Add `const VueLoaderPlugin = require('vue-loader/lib/plugin');` to your webpack config and instantiate `new VueLoaderPlugin()` in the `plugins` array. Ensure `vue-loader` and `vue-template-compiler` versions are compatible.

• Markdown content is rendered as plain HTML/text without Vue component functionality or styles/scripts are not applied.

  cause The loader is not correctly configured to pass compiled content to `vue-loader`, often due to missing `raw: true` option or incorrect loader path when using `vue-loader` v15+.
  fix Verify that your webpack rule for `.md` files uses `vue-markdown-loader/lib/markdown-compiler` and includes `options: { raw: true }`. Also, ensure `vue-loader` is applied after `vue-markdown-loader` in the chain.

• Embedded `<script>` or `<style>` tags within markdown are not correctly processed or cause syntax errors.

  cause The automatic extraction feature (introduced in v2.0.0) might interfere with your embedded code, or the content is not correctly tokenized.
  fix If you want to prevent automatic extraction and handle scripts/styles manually (e.g., through `vue-loader`), set the `preventExtract: true` option in `vue-markdown-loader`'s options.

Warnings

• deprecated The package's own README explicitly states 'You have other better choices' and lists alternative loaders. This indicates the project is not actively recommended for new development and might not receive future updates or active support.
  Fix: Consider alternatives like `vmark`, `ware-loader`, or `vue-md-loader` for new projects, as suggested in the package's documentation.
• breaking Since `v2.0.0`, the loader automatically extracts script and style tags from HTML content embedded within Markdown. This might alter how your embedded Vue code or styles are processed.
  Fix: If you do not want this automatic extraction behavior, set the `preventExtract: true` option in your loader configuration.
• gotcha When used with `vue-loader` v15+, it is crucial to use the specific `vue-markdown-loader/lib/markdown-compiler` path and include the `raw: true` option to ensure the Markdown content is correctly processed and passed to `vue-loader`.
  Fix: Ensure your `webpack.config.js` or `vue.config.js` includes `{ loader: 'vue-markdown-loader/lib/markdown-compiler', options: { raw: true } }` in the loader chain for `.md` files.

Install

• npm install vue-markdown-loader npm
• yarn add vue-markdown-loader yarn
• pnpm add vue-markdown-loader pnpm

Imports

• vue-markdown-loader (basic)
  wrong:

  import { vueMarkdownLoader } from 'vue-markdown-loader'

  correct:

  loader: 'vue-markdown-loader'

  This is the primary way to reference the loader in your webpack configuration for basic setups (e.g., Vue 1 or older Vue 2 without vue-loader v15+ specific splitting).
• vue-markdown-loader/lib/markdown-compiler
  wrong:

  loader: 'vue-markdown-loader'

  correct:

  loader: 'vue-markdown-loader/lib/markdown-compiler'

  When integrating with `vue-loader` v15+ (common in modern Vue 2 projects), you must use this specific path for the markdown compiler to work correctly as a chained loader.
• VueLoaderPlugin
  wrong:

  import { VueLoaderPlugin } from 'vue-loader'

  correct:

  const VueLoaderPlugin = require('vue-loader/lib/plugin');

  This plugin is mandatory for `vue-loader` v15+ and above. Since `vue-markdown-loader` is typically used in conjunction with `vue-loader`, ensure this plugin is correctly configured in your webpack plugins array.

Quickstart

This webpack.config.js demonstrates how to integrate `vue-markdown-loader` with `vue-loader` v15+ for compiling Markdown files into Vue components, including key options like `raw` and `preventExtract`.

const path = require('path');
const VueLoaderPlugin = require('vue-loader/lib/plugin');

module.exports = {
  mode: 'development',
  entry: './src/main.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader'
      },
      {
        test: /\.md$/,
        use: [
          {
            loader: 'vue-loader'
          },
          {
            loader: 'vue-markdown-loader/lib/markdown-compiler',
            options: {
              raw: true, // Crucial for passing raw HTML to vue-loader
              preventExtract: false, // Set to true to disable automatic script/style extraction
              wrapper: 'article', // Customize the root wrapper tag
              // Example markdown-it plugin usage
              use: [
                [require('markdown-it-anchor'), { permalink: true, permalinkBefore: true, permalinkSymbol: '#' }]
              ]
            }
          }
        ]
      }
    ]
  },
  plugins: [
    new VueLoaderPlugin()
  ],
  resolve: {
    extensions: ['.js', '.vue', '.json', '.md'],
    alias: {
      'vue$': 'vue/dist/vue.esm.js'
    }
  }
};