@uivjs/vue-markdown-preview
===


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.

Feature

- ⛑ Safe by default (no v-html/innerHTML or XSS attacks)
- ♻️ Components (pass your own component to use instead of

for ## hi)
- 🧩 Plugins (many plugins you can pick and choose from)
- ☘️ Compliant (100% to CommonMark, 100% to GFM with a plugin)

Install

``bash
npm i @uivjs/vue-markdown-preview
`

Usage

`vue



`

Examples

$3

This example shows how to use a remark plugin. In this case, remark-gfm, which adds support for strikethrough, tables, tasklists and URLs directly:

`vue



`

$3

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:

`vue



`

Components

You can also change the things that come from markdown:

`vue



`

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.

- code
- inline (boolean?) — set to true for inline code
- className (string?) — set to language-js or so when using \``js
- h1, h2, h3, h4, h5, h6
- level (number between 1 and 6) — heading rank
- input (when using remark-gfm)
- checked (boolean) — whether the item is checked
- disabled (true)
- type ('checkbox')
- li
- index (number) — number of preceding items (so first gets 0, etc.)
- ordered (boolean) — whether the parent is an ol or not
- checked (boolean?) — null normally, boolean when using remark-gfm’s tasklists
- className (string?) — set to task-list-item when using remark-gfm and the item1 is a tasklist
- ol, ul
- depth (number) — number of ancestral lists (so first gets 0, etc.)
- ordered (boolean) — whether it’s an ol or not
- className (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 aligned
- isHeader (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.

API

- source (string, default: '') Markdown to parse.
- components (Object., default: {}) Object mapping tag names to Vue components.
- remarkPlugins (Array., default: []) List of remark plugins to use. See the next section for examples on how to pass options.
- rehypePlugins (Array., 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 (string or (href, children, title) => string, optional) target to use on links (such as _blank for )
- 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 their position (sourcePosition: {start: {line: 3, column: 1}, end:…})
- includeElementIndex (boolean, default: false) pass the index (number of elements before it) and siblingCount (number of elements in parent) as props to all components
- transformLinkUri ((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

Plugins

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

Syntax

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.

Types

This package is fully typed with TypeScript. It exports Options and Components types, which specify the interface of the accepted props and components.

Security

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.

Development

``bash
npm install # Installation dependencies
npm run bootstrap # Install dependencies in sub-packages
`

`bash
npm run build # Compile package


listen to the component compile and output the .js file