Markdown component for Vue. The minimal amount of CSS to replicate the GitHub Markdown style. The current document website is converted using this Vue component.
- ⛑ Safe by default (no
v-html/innerHTMLor XSS attacks) - ♻️ Components (pass your own component to use instead of
<h2>for## hi) - 🧩 Plugins (many plugins you can pick and choose from)
- ☘️ Compliant (100% to CommonMark, 100% to GFM with a plugin)
npm i @uivjs/vue-markdown-preview<template>
<div>
<markdown-preview :source="markdown" />
<markdown-preview class="markdown-warpper">
{{markdown}}
</markdown-preview>
<markdown-preview>
## Hello Markdown
</markdown-preview>
</div>
</template>
<script>
import { defineComponent } from 'vue';
import MarkdownPreview from '@uivjs/vue-markdown-preview';
import '@uivjs/vue-markdown-preview/markdown.css';
const markdown = `## Hello Markdown
\`\`\`shell
npm i @uivjs/vue-markdown-preview
\`\`\`
`;
export default defineComponent({
data() {
return {
markdown
}
},
components: {
MarkdownPreview
}
});
</script>This example shows how to use a remark plugin. In this case, remark-gfm, which adds support for strikethrough, tables, tasklists and URLs directly:
<template>
<markdown-preview :remarkPlugins="remarkPlugins">
{{markdown}}
</markdown-preview>
</template>
<script>
import { defineComponent } from 'vue';
import MarkdownPreview from '@uivjs/vue-markdown-preview';
import '@uivjs/vue-markdown-preview/markdown.css';
import remarkGfm from 'remark-gfm';
const markdown = `A paragraph with *emphasis* and **strong importance**.
> A block quote with ~strikethrough~ and a URL: https://vuejs.org.
* Lists
* [ ] todo
* [x] done
A table:
| a | b |
| - | - |
`;
export default defineComponent({
data() {
return {
markdown,
remarkPlugins: [remarkGfm]
}
},
components: {
MarkdownPreview
}
});
</script>This example shows how to use a plugin and give it options. To do that, use an array with the plugin at the first place, and the options second. remark-gfm has an option to allow only double tildes for strikethrough:
<template>
<markdown-preview :remarkPlugins="remarkPlugins">
This ~is not~ strikethrough, but ~~this is~~!
</markdown-preview>
</template>
<script>
import MarkdownPreview from '@uivjs/vue-markdown-preview';
import '@uivjs/vue-markdown-preview/markdown.css';
import remarkGfm from 'remark-gfm';
export default {
data() {
return {
remarkPlugins: [[remarkGfm, { singleTilde: false }]]
}
},
components: {
MarkdownPreview
}
};
</script>You can also change the things that come from markdown:
<template>
<markdown-preview :components="components">
{{`<em>www \nxxx</em>\n- 1\n- 2`}}
</markdown-preview>
</template>
<script>
import MarkdownPreview from '@uivjs/vue-markdown-preview';
import '@uivjs/vue-markdown-preview/markdown.css';
export default {
data() {
return {
components: {
em: ({ children, ...properties}) => {
return <i style={{ color: 'red' }} {...properties}>{children}</i>
},
li: ({ node, checked, index, ordered, children, ...properties}) => {
console.log('other:', node, properties, children, checked, index, ordered)
return <li {...properties}>{children}</li>
},
}
}
},
components: {
MarkdownPreview
}
};
</script>The keys in components are HTML equivalents for the things you write with markdown (such as h1 for # heading). Normally, in markdown, those are: a, blockquote, br, code, em, h1, h2, h3, h4, h5, h6, hr, img, li, ol, p, pre, strong, and ul. With remark-gfm, you can also use: del, input, table, tbody, td, th, thead, and tr. Other remark or rehype plugins that add support for new constructs will also work with vue-markdown-preview.
The props that are passed are what you probably would expect: an a (link) will get href (and title) props, and img (image) an src (and title), etc. There are some extra props passed.
codeinline(boolean?) — set to true for inline codeclassName(string?) — set to language-js or so when using\```js
h1,h2,h3,h4,h5,h6level(numberbetween 1 and 6) — heading rank
input(when using remark-gfm)checked(boolean) — whether the item is checkeddisabled(true)type('checkbox')
liindex(number) — number of preceding items (so first gets0, etc.)ordered(boolean) — whether the parent is an ol or notchecked(boolean?) — null normally, boolean when using remark-gfm’s tasklistsclassName(string?) — set to task-list-item when using remark-gfm and the item1 is a tasklist
ol,uldepth(number) — number of ancestral lists (so first gets0, etc.)ordered(boolean) — whether it’s an ol or notclassName(string?) — set to contains-task-list when using remark-gfm and the list contains one or more tasklists
td,th(when using remark-gfm)style(Object?) — something like{textAlign: 'left'}depending on how the cell is alignedisHeader(boolean) — whether it’s a th or not
tr(when using remark-gfm)isHeader(boolean) — whether it’s in the thead or not
Every component will receive a node (Object). This is the original hast element being turned into a Vue element.
source(string, default:'') Markdown to parse.components(Object.<string, VNodeChild>, default:{}) Object mapping tag names toVuecomponents.remarkPlugins(Array.<Plugin>, default:[]) List of remark plugins to use. See the next section for examples on how to pass options.rehypePlugins(Array.<Plugin>, default:[]) List of rehype plugins to use. See the next section for examples on how to pass options.skipHtml(boolean, default:false) ignore HTML in markdown completely.linkTarget(stringor(href, children, title) => string, optional) target to use on links (such as_blankfor<a target="_blank"…)sourcePos(boolean, default:false) pass a prop to all components with a serialized position (data-sourcepos="3:1-3:13")rawSourcePos(boolean, default:false) pass a prop to all components with theirposition(sourcePosition: {start: {line: 3, column: 1}, end:…})includeElementIndex(boolean, default:false) pass the index (number of elements before it) andsiblingCount(number of elements in parent) as props to all componentstransformLinkUri((href, children, title) => string, default:uriTransformer, optional) change URLs on links, pass null to allow all URLs, see security.transformImageUri((src, alt, title) => string, default:uriTransformer, optional) change URLs on images, pass null to allow all URLs, see security
We use unified, specifically remark for markdown and rehype for HTML, which are tools to transform content with plugins. Here are three good ways to find plugins:
- awesome-remark and awesome-rehype — selection of the most awesome projects
- List of remark plugins and list of rehype plugins — list of all plugins
- remark-plugin and rehype-plugin topics — any tagged repo on GitHub
vue-markdown-preview follows CommonMark, which standardizes the differences between markdown implementations, by default. Some syntax extensions are supported through plugins.
We use micromark under the hood for our parsing. See its documentation for more information on markdown, CommonMark, and extensions.
This package is fully typed with TypeScript. It exports Options and Components types, which specify the interface of the accepted props and components.
Use of vue-markdown-preview is secure by default. Overwriting transformLinkUri or transformImageUri to something insecure will open you up to XSS vectors. Furthermore, the remarkPlugins, rehypePlugins, and components you use may be insecure.
To make sure the content is completely safe, even after what plugins do, use rehype-sanitize. It lets you define your own schema of what is and isn’t allowed.
npm install # Installation dependencies
npm run bootstrap # Install dependencies in sub-packagesnpm run build # Compile package
# listen to the component compile and output the .js file
# listen for compilation output type .d.ts file
npm run watch # Monitor the compiled package `@uivjs/vue-markdown-preview`
npm run start # development mode, listen to compile preview website instance- react-markdown-preview React component preview markdown text in web browser.
- react-markdown Markdown component for React.
Licensed under the MIT License.