API

Markdown

Importing Markdown

The app extension needs to be installed in order to import markdown (*.md) files. In QMarkdown v3, this is supported through Quasar CLI Vite. To import markdown files, DO NOT place them into your public folder. Put them into your assets folder.

<template>
  <q-markdown :src="ContactUs" show-copy />
</template>

<script>
import { defineComponent } from 'vue'
import ContactUs from '@/assets/contact-us.md'

export default defineComponent({
  setup () {
    return {
      ContactUs
    }
  }
})
</script>

Extending Prism

The prismjs package is used for language highlighting. When Prism is installed by QMarkdown, it loads itself globally. You can access it via window.Prism. Visit their documentation on modifying the run-time, like adding additional language support.

Global Properties

QMarkdown has the ability to set global properties via the useQMarkdownGlobalProps function.

To set it up site wide, put it into a boot file. The function takes an object containing the camelCase naming of the props for QMarkdown.

import { useQMarkdownGlobalProps } from '@quasar/quasar-ui-qmarkdown'

// defaults for QMarkdown
useQMarkdownGlobalProps({
  noLineNumbers: true,
  lineNumberAlt: '
#39;
})

Global Plugins

As well, the property, plugins, has been added to enhance QMarkdown with markdown-it plugins. You can do something like this in a boot file:

import { useQMarkdownGlobalProps } from '@quasar/quasar-ui-qmarkdown'
import markdownItMermaid from '@datatraccorporation/markdown-it-mermaid'

// defaults for QMarkdown
useQMarkdownGlobalProps({
  plugins: [markdownItMermaid]
})

In this case, the markdown-it-mermaid will be made available to all QMarkdown instances.

QMarkdown Native Handling

QMarkdown has a number of built-in processors to handle inline markdown. These are listed below:

Blockquotes

Code

Copy to clipboard

Containers

Emphasis

Heading

Horizontal rules

Images

Inline rendering

Use the inline prop when markdown needs to live inside existing paragraph or text structure. Inline mode uses markdown-it.renderInline() and a span root, so emphasis, links, and tokens render without generated paragraph wrappers.

Links

Lists

Tables

Titles

Typography

Extending with Plugins

In order to reduce the payload size of QMarkdown and to increase performance, a lot of the “default” markdown-it plugins have been removed for v2.0.0+. If you have the need, you can add them back either via the plugins property or the global props, as described above.

Here is a list of plugins that used to be in QMarkdown v1.x:

import abbreviation from 'markdown-it-abbr'
import deflist from 'markdown-it-deflist'
import { full as emoji } from 'markdown-it-emoji'
import footnote from 'markdown-it-footnote'
import insert from 'markdown-it-ins'
import mark from 'markdown-it-mark'
import subscript from 'markdown-it-sub'
import superscript from 'markdown-it-sup'
import taskLists from 'markdown-it-task-lists'

The rest of the plugins are custom with QMarkdown or deemed necessary (like the one to handle images).

Install only the plugins your project actually uses. To run every example in this section, your app needs these runtime packages:

{
  "dependencies": {
    "@datatraccorporation/markdown-it-mermaid": "^0.5.0",
    "katex": "^0.17.0",
    "markdown-it-abbr": "^2.0.0",
    "markdown-it-deflist": "^3.0.1",
    "markdown-it-emoji": "^3.0.0",
    "markdown-it-footnote": "^4.0.0",
    "markdown-it-ins": "^4.0.0",
    "markdown-it-mark": "^4.0.0",
    "markdown-it-sub": "^2.0.0",
    "markdown-it-sup": "^2.0.0",
    "markdown-it-task-lists": "^2.1.1",
    "markdown-it-texmath": "^1.0.0"
  }
}

Some markdown-it plugins do not ship TypeScript declarations. If your project reports a missing module type, add an ambient declaration in a local file such as src/env.d.ts:

declare module "@datatraccorporation/markdown-it-mermaid";
declare module "markdown-it-abbr";
declare module "markdown-it-deflist";
declare module "markdown-it-emoji";
declare module "markdown-it-footnote";
declare module "markdown-it-ins";
declare module "markdown-it-mark";
declare module "markdown-it-sub";
declare module "markdown-it-sup";
declare module "markdown-it-task-lists";
declare module "markdown-it-texmath";

Style-based plugins may also need CSS imports. For example, the math example imports both katex/dist/katex.min.css and markdown-it-texmath/css/texmath.css.

Abbreviations

Definition lists

Emojies

Footnotes

Insert

Mark

Math

QMarkdown does not bundle a math renderer, but math plugins can be wired in through the plugins prop. This example uses markdown-it-texmath with KaTeX.

Subscript/superscript

Task lists

Mermaid

Advanced

Editor