markdown-to-vue-loader

Markdown to Vue component loader for Webpack.

• The built-in markdown parser is markdown-it.
• Examples.

Features

• Supports Vue 2 and Vue 3.
• Supports loading a markdown file as a Vue component.
• Supports loading code blocks (Vue and HTML by default) as Vue components.
• Supports 10 options.

Getting started

Installation

npm install markdown-to-vue-loader vue-loader webpack --save-dev

Usage

Within your webpack.config.js configuration object, you'll need to add the markdown-to-vue-loader to the list of modules, like so:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.md$/,
        use: [
          'vue-loader',
          {
            loader: 'markdown-to-vue-loader',
            options: {
              // ...
            },
          },
        ],
      },
    ],
  },
  resolve: {
    alias: {
      // Vue 2
      // vue$: 'vue/dist/vue.esm.js',

      // Vue 3
      vue$: 'vue/dist/vue.esm-bundler',
    },
  },
};

Usage for Vue CLI

Within your vue.config.js configuration file, you'll need to add the markdown-to-vue-loader to the chainWebpack, like so:

// vue.config.js
module.exports = {
  chainWebpack: (config) => {
    config.module
      .rule('markdown')
        .test(/\.md$/)
        .use('vue-loader')
          .loader('vue-loader')
          .end()
        .use('markdown-to-vue-loader')
          .loader('markdown-to-vue-loader')
          .options({
            // ...
          })
          .end();
  },
};

Options

cheerioLoadOptions

• Type: Object

• Default:

  {
    decodeEntities: false,
    lowerCaseAttributeNames: false,
    lowerCaseTags: false,
  }

The options for the load method of the cheerio.

configureMarkdownIt

• Type: Function

• Default: null

• Example:

  {
    configureMarkdownIt(md) {
      md.set(...)
        .use(...);
    }
  }

Checkout the documentation of MarkdownIt for more information.

componentNamespace

• Type: String
• Default: 'component'

The namespace for component name.

For example, if this is set to 'awesome-component', then given this input (example.md):

# Example

```vue
<template>
  <p>Hello, World!</p>
</template>
```

will generate (example.vue):

<template>
  <div>
    <h1>Example</h1>
    <awesome-component-example-0></awesome-component-example-0>
    <pre><code class="language-vue">&lt;template&gt;
  &lt;p&gt;Hello, World!&lt;/p&gt;
&lt;/template&gt;</code></pre>
  </div>
</template>
<script>
  module.exports = {
    components: {
      'awesome-component-example-0': {
        template: '<p>Hello, World!</p>'
      }
    }
  };
</script>

componentWrapper

• Type: String
• Default: ''

The wrapper for component content. Supports to use Vue component as the wrapper.

For example, if this is set to '<section></section>', then given this input (example.md):

# Example

```html
<p>Hello, World!</p>
```

will generate (example.vue):

<template>
  <div>
    <h1>Example</h1>
    <section><component-example-0></component-example-0></section>
    <pre><code class="language-html">&lt;p&gt;Hello, World!&lt;/p&gt;</code></pre>
  </div>
</template>
<script>
  module.exports = {
    components: {
      'component-example-0': {
        template: '<p>Hello, World!</p>'
      }
    }
  };
</script>

exportSource

• Type: Boolean
• Default: false

Export source markdown text.

If this is set to true, then you can get the source from the Vue component's source property.

For example (example.md):

# Hello, World!

import Example from 'example.md';

console.log(Example.source);
// > # Hello, World!

languages

• Type: Array
• Default: ['vue', 'html']

The code blocks of these languages will be loaded as Vue components be default.

For example, if this is set to ['js'], then given this input (example.md):

# Example

```js
export default {
  template: '<p>Hello, World!</p>'
}
```

will generate (example.vue):

<template>
  <div>
    <h1>Example</h1>
    <component-example-0></component-example-0>
    <pre><code class="language-js">export default {
  template: '&lt;p&gt;Hello, World!&lt;/p&gt;'
}</code></pre>
  </div>
</template>
<script>
  module.exports = {
    components: {
      'component-example-0': {
        template: '<p>Hello, World!</p>'
      }
    }
  };
</script>

markdownItOptions

• Type: Object

• Default:

  {
    html: true,
    linkify: true,
    typographer: true,
  }

• Example:

  {
    typographer: false,
    highlight(str, lang) {
      return '';
    },
  }

The options for the built-in markdown parser markdown-it.

preClass

• Type: String
• Default: ''
• Example: 'prettyprint'

The class name for each <pre></pre> element.

preWrapper

• Type: String
• Default: ''
• Example: '<div class="example-code"></div>'

The wrapper for each <pre></pre> element. Supports to use Vue component as the wrapper.

tableClass

• Type: String
• Default: ''
• Example: 'table table-bordered border-striped'

The class name for each <table></table> element.

tableWrapper

• Type: String
• Default: ''
• Example: '<div class="table-container"></div>'

The wrapper for each <table></table> element. Supports to use Vue component as the wrapper.

Inline comment options

• <!-- vue-component -->
• <!-- no-vue-component -->

If a code block has a <!-- vue-component --> comment before it, then the loader will load it as a Vue component, even though its language is NOT specified in the languages option.

Conversely, if a code block has a <!-- no-vue-component --> comment before it, then the loader will NOT load it as a Vue component, even though its language is specified in the languages option.

For example, given this input (example.md):

# Example

<!-- vue-component -->

```js
export default {
  template: '<p>Hello, World!</p>'
};
```

<!-- no-vue-component -->

```vue
<template>
  <p>Hello, World!</p>
</template>
```

will generate (example.vue):

<template>
  <div>
    <h1>Example</h1>
    <component-example-0></component-example-0>
    <pre><code class="language-js">export default {
  template: '&lt;p&gt;Hello, World!&lt;/p&gt;'
};</code></pre>
    <pre><code class="language-vue">&lt;template&gt;
  &lt;p&gt;Hello, World!&lt;/p&gt;
&lt;/template&gt;</code></pre>
  </div>
</template>
<script>
  module.exports = {
    components: {
      'component-example-0': {
        template: '<p>Hello, World!</p>'
      }
    }
  };
</script>

Scoped CSS

When a <style> tag has the scoped attribute, its CSS will apply to elements of the current component only.

For example, given this input:

<template>
  <p>Hello, World!</p>
</template>

<style scoped>
  p {
    color: green;
  }
</style>

will render as this:

<div class="component-example-0">
  <p>Hello, World!</p>
</div>

<style>
  .component-example-0 p {
    color: green;
  }
</style>

Versioning

Maintained under the Semantic Versioning guidelines.

License

MIT © Chen Fengyuan