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>