Vue Showdown
Guide
Playground
v4.2.0
  • English
  • 简体中文
GitHub
Guide
Playground
v4.2.0
  • English
  • 简体中文
GitHub

Guide 🚀

Warning

This guide is for Vue 3 only. If you're using Vue 2, please check out the docs here.

Getting Started

NPM

Install via npm

npm install vue-showdown

Import vue-showdown as a vue plugin:

// import as a Vue plugin
import { createApp } from 'vue';
import { VueShowdownPlugin } from 'vue-showdown';

const app = createApp();

// the second parameter of app.use() is optional
app.use(VueShowdownPlugin, {
  // set default flavor of showdown
  flavor: 'github',
  // set default options of showdown (will override the flavor options)
  options: {
    emoji: false,
  },
});

Or import vue-showdown as a vue component:

// import as a Vue component
import { createApp } from 'vue';
import { VueShowdown } from 'vue-showdown';

const app = createApp();

app.component('VueShowdown', VueShowdown);

Then use <VueShowdown /> in your vue SFC:

<!-- set options via props -->
<VueShowdown
  markdown="## markdown text"
  flavor="github"
  :options="{ emoji: true }"
/>

Tips

vue-showdown also provides UMD, CommonJS and ES Module builds as vue does. Go to the Vue document for more details.

Browser

Direct <script> import after vue.js and showdown.js. Then use vue-showdown as a vue plugin / component.

<body>
  <div id="#app">
    <vue-showdown markdown="## markdown text" />
  </div>

  <script src="https://unpkg.com/vue@3.x/dist/vue.global.prod.js"></script>
  <script src="https://unpkg.com/showdown@1.x/dist/showdown.min.js"></script>
  <script src="https://unpkg.com/vue-showdown@3.x/vue-showdown.min.js"></script>

  <script>
    const app = Vue.createApp();

    // as vue plugin
    app.use(VueShowdownPlugin);

    // OR: as vue component
    app.component('VueShowdown', VueShowdown);

    app.mount('#app');
  </script>
</body>

Plugin Options

import { createApp } from 'vue';
import { VueShowdownPlugin } from 'vue-showdown';

const app = createApp();

app.use(VueShowdownPlugin, {
  // Plugin options here
});

flavor

Default flavor of showdown. Docs here.

  • type: string | null
  • default: null
  • possible values: 'github' | 'original' | 'ghost' | 'vanilla' | 'allOn'

Tips

The flavor here will be set globally by showdown.setFlavor().

options

Default options of showdown. Docs here.

  • type: Object
  • default: {}

Tips

The options here will be set globally by showdown.setOption() after showdown.setFlavor(), which will override the flavor's options.

Component Props

markdown

The raw markdown content to parse.

  • type: string | null
  • default: null
<VueShowdown markdown="# Hello, world!" />
<!-- renders as -->
<div>
  <h1>Hello, world!</h1>
</div>

tag

The HTML tag of the markdown wrapper. Similar to vue-router's tag.

  • type: string
  • default: 'div'
<VueShowdown markdown="# Hello, world!" tag="span" />
<!-- renders as -->
<span>
  <h1>Hello, world!</h1>
</span>

flavor

Flavor of showdown. Docs here.

  • type: string | null
  • default: null
  • possible values: 'github' | 'original' | 'ghost' | 'vanilla' | 'allOn'

Tips

If you set flavor via props, all the options will be reset to the flavor's options, which will override the default options you set by app.use().

options

Options of showdown. Docs here.

  • type: Object
  • default: {}

Tips

The options prop will override the default options set by app.use().

If you also set flavor prop, the options prop will override the flavor's options, too.

extensions

Extensions of showdown. Docs here.

  • type: Array | null
  • default: null

Tips

Check the Advance - Extensions section for details.

vueTemplate

Treat the parsed HTML string as vue template. This will allow you to use vue template syntax in your markdown.

  • type: Boolean
  • default: false

ATTENTION

If you set it to true, you have to use the full (runtime + compiler) build of Vue, as we need to compile templates on the client. Consult the vue dist file guide for more details.

If you have similar request as #5, you can enable this feature.

vueTemplateComponents

Define components which are available in the vue template. It will only take effect when vueTemplate is enabled.

  • type: Object
  • default: {}
  • example:
<script>
import { defineComponent, ref } from 'vue';
import MyComponent from './MyComponent.vue';

export default defineComponent({
  setup() {
    return { MyComponent };
  },
});
</script>

<template>
  <VueShowdown
    markdown="## markdown text with <my-component />"
    :vue-template="true"
    :vue-template-components="{ MyComponent }"
  />
</template>

vueTemplateData

Define data which is available in the vue template. It will only take effect when vueTemplate is enabled.

  • type: Object
  • default: {}
  • example:
<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const message = ref('hello, vue template in markdown!');
    return { message };
  },
});
</script>

<template>
  <VueShowdown
    markdown="## markdown text {{ message }}"
    :vue-template="true"
    :vue-template-data="{ message }"
  />
</template>

Advance

Showdown library

You can also import showdown itself from vue-showdown for advance usages.

import { createApp } from 'vue';
import { VueShowdownPlugin, showdown } from 'vue-showdown';

const app = createApp();

showdown.setFlavor('github');

app.use(VueShowdownPlugin);

Extensions

According to the official docs about extensions, there is no way to set default extensions globally for now.

So the only way to set extensions is via the extensions prop of the VueShowdown component.

<script>
import { defineComponent } from 'vue';
import type { showdown } from 'vue-showdown';

const myExt = (): showdown.ShowdownExtension[] => [
  {
    type: 'lang',
    regex: /markdown/g,
    replace: 'showdown',
  },
];

export default defineComponent({
  setup() {
    return { myExt };
  },
});
</script>

<template>
  <VueShowdown markdown="## markdown text" :extensions="[myExt]" />
</template>

Alternatively, you can register extensions globally via showdown.extension(), and reference it in the extension prop directly by the name that you registered.

import { createApp } from 'vue';
import { VueShowdownPlugin, showdown } from 'vue-showdown';

const app = createApp();

showdown.extension('myExt', () => [
  {
    type: 'lang',
    regex: /markdown/g,
    replace: 'showdown',
  },
]);

app.use(VueShowdownPlugin);
<template>
  <VueShowdown markdown="## markdown text" :extensions="['myExt']" />
</template>
Edit this page on GitHub
Last Updated: 8/13/24, 12:47 PM
Contributors: Xinyu Liu, Jaime Pastor, meteorlxy, NtchPlayer