Vue Markdown Renderer

Common errors

• TypeError: Cannot read properties of undefined (reading 'setup') or similar errors related to Vue component initialization.

  cause Attempting to use `vue-markdown-render` v2.x in a Vue 2 project, where the component API is incompatible.
  fix Ensure your project is using Vue 3.x. If you must use Vue 2, downgrade `vue-markdown-render` to a 1.x version.

• Property 'VueMarkdown' does not exist on type '...' or similar TypeScript errors during compilation.

  cause Missing or incorrect type definitions for `vue-markdown-render` or its dependencies (specifically `markdown-it`).
  fix Install `@types/markdown-it` as a dev dependency: `npm install @types/markdown-it --save-dev`.

• Unknown custom element: <vue-markdown> - did you register the component correctly? For recursive components, make sure to provide the 'name' option.

  cause The `VueMarkdown` component was not properly registered in the parent component's `components` option.
  fix Add `VueMarkdown` to the `components` object within your Vue component definition, e.g., `components: { VueMarkdown }`.

Warnings

• breaking Version 2.0.0 introduced a breaking change by switching entirely to Vue 3. Applications built with Vue 2 will not be compatible with `vue-markdown-render@2.x`.
  Fix: Upgrade your Vue application to Vue 3 or use `vue-markdown-render@1.x` for Vue 2 compatibility.
• gotcha When using TypeScript, the `@types/markdown-it` package must be installed as a development dependency (`npm install @types/markdown-it --save-dev`) to ensure proper type inference for markdown-it options and plugins.
  Fix: Add `"@types/markdown-it": "*"` to your devDependencies in `package.json` and run `npm install`.
• gotcha As of v2.3.0, the package upgraded its internal `markdown-it` dependency to v14. While generally backward compatible, review markdown-it's own changelog for any subtle breaking changes or deprecated features if you rely on advanced or custom markdown-it configurations.
  Fix: Test your markdown rendering thoroughly after upgrading to v2.3.0, especially if you use custom markdown-it configurations or plugins that might be sensitive to markdown-it version changes.
• deprecated Prior to v2.1.1, the component might have been used with the Options API exclusively. While still supported, `v2.1.1` introduced a refactor to use Composition API internally, and the provided quickstart examples now predominantly use Composition API with `<script setup>` for better integration with modern Vue 3 practices.
  Fix: Consider migrating component usage to Composition API with `<script setup>` for new components or refactoring existing ones for improved maintainability and performance, although the Options API remains functional.

Install

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

Imports

• VueMarkdown
  wrong:

  const VueMarkdown = require('vue-markdown-render')

  correct:

  import VueMarkdown from 'vue-markdown-render'

  This is the primary component for rendering markdown. ESM import is standard for Vue 3.
• defineComponent
  wrong:

  import Vue from 'vue'; Vue.defineComponent(...)

  correct:

  import { defineComponent, ref } from 'vue'

  Used in the Options API example for defining a component, often paired with `ref` for reactivity.
• MarkdownItAnchor (example plugin)
  wrong:

  import { MarkdownItAnchor } from 'markdown-it-anchor'

  correct:

  import MarkdownItAnchor from 'markdown-it-anchor'

  Plugins for markdown-it (like markdown-it-anchor) are typically default exports and imported separately for use with the `plugins` prop.

Quickstart

Demonstrates basic usage of the VueMarkdown component, including passing markdown source, markdown-it options, and external markdown-it plugins.

import { defineComponent, ref } from 'vue';
import VueMarkdown from 'vue-markdown-render';
import MarkdownItAnchor from 'markdown-it-anchor';

export default defineComponent({
  name: 'MarkdownViewer',
  components: {
    VueMarkdown
  },
  setup() {
    const src = ref('# Hello, VueMarkdown\n\nThis is some **dynamic** content rendered from Markdown.\n\n## Features\n\n-   Lightweight
-   TypeScript support
-   Plugin ready (e.g., markdown-it-anchor)

[Link to GitHub](https://github.com/cloudacy/vue-markdown-render)');

    const options = {
      html: true,
      linkify: true,
      typographer: true
    };

    const plugins = [MarkdownItAnchor];

    return {
      src,
      options,
      plugins
    };
  },
  template: `
    <div>
      <VueMarkdown :source="src" :options="options" :plugins="plugins" />
    </div>
  `
});