Use this guide to migrate to QMarkdown v4.0.0. The QMarkdown v3 migration notes remain below for applications upgrading across multiple major versions.

QMarkdown v4.0.0

QMarkdown v4 updates its Markdown parser and public plugin types to Markdown-it 15.

Important changes:

• QMarkdown now uses markdown-it ^15.0.0.
• Markdown-it now bundles its TypeScript declarations, so applications should remove @types/markdown-it.
• Markdown-it 15 removes package-internal imports such as markdown-it/lib/token.mjs. Custom plugins must import public runtime values and types from markdown-it.
• Markdown-it 15 upgrades linkify-it and changes some URL parsing boundaries, including Unicode punctuation and authenticated URLs. Bare domains such as example.com are no longer linkified by default. Set :linkify-options="{ fuzzyLink: true }" to retain the previous behavior, and review representative rendered output if your application depends on exact linkification behavior.
• QMarkdown’s MarkdownItPlugin public type now uses Markdown-it 15’s bundled MarkdownIt type.

Update QMarkdown and any direct Markdown-it dependency together:

pnpm up @quasar/quasar-ui-qmarkdown@^4 markdown-it@^15
pnpm remove @types/markdown-it

Custom plugin types should use Markdown-it’s public exports:

import type { MarkdownIt, Renderer, Token } from 'markdown-it'

QMarkdown v4 retains the Vue 3, Quasar 2, and Quasar CLI Vite 3 requirements from v3. The app extension remains Vite-only and requires @quasar/app-vite >=3.0.0.

QMarkdown v3 targets Vue 3, Quasar 2, and Quasar CLI Vite 3. If your app still uses Vue 2 or @quasar/app-webpack, migrate the app before installing QMarkdown v3.

The information below is not exhaustive. Check the Releases page for the latest notes, and please open an issue or PR if something is missing.

QMarkdown v3.0.0

QMarkdown v3 prepares the package for Quasar CLI Vite 3 and the shared app-extension workspace standard.

Important changes:

• The app extension is Vite-only and requires @quasar/app-vite >=3.0.0.
• The webpack app-extension path is no longer supported.
• The package now uses ESM-first exports for Quasar/Vite consumers.
• UMD bundles remain available for CDN and CodePen examples.
• Source files are TypeScript and SCSS.
• Documentation examples now include GitHub source and CodePen playground links through Q-Press.
• Repository tooling now uses pnpm, oxlint, oxfmt, Vitest, and Rolldown.

Requirements

Installing QMarkdown v3

QMarkdown v3 is published on the latest dist tag.

quasar ext add @quasar/qmarkdown

App Extension Changes

The QMarkdown app extension now targets Quasar CLI Vite only.

• Install it only in apps using @quasar/app-vite >=3.0.0.
• The extension registers the Vite boot file only.
• The extension remains the recommended install path for Quasar apps because it also configures Vue template handling for markdown content.
• The optional markdown raw importer still lets you import *.md files as strings when enabled during install.

If you maintain your own boot file, import defineBoot from #q-app:

import { defineBoot } from "#q-app";
import Plugin from "@quasar/quasar-ui-qmarkdown";
import "@quasar/quasar-ui-qmarkdown/dist/index.css";

export default defineBoot(({ app }) => {
  app.use(Plugin);
});

Direct UI Package Usage

Compiled package imports are the recommended path:

import { const QMarkdown: QMarkdownComponentQMarkdown } from "@quasar/quasar-ui-qmarkdown";

QMarkdown
  
const QMarkdown: QMarkdownComponent

Import the component stylesheet alongside the component:

import "@quasar/quasar-ui-qmarkdown/dist/index.css";

Direct src/ imports are still available for advanced use cases. With Quasar CLI Vite 3, dependency transpilation is automatic, so no additional transpile-dependency configuration is needed.

import Plugin from "@quasar/quasar-ui-qmarkdown/src/index";
import "@quasar/quasar-ui-qmarkdown/src/index.scss";

Markdown Rendering Notes

QMarkdown still relies on Vue preserving markdown content inside <q-markdown> tags. If you install manually instead of using the app extension, keep this compiler option in your Quasar config:

build: {
  viteVuePluginOptions: {
    template: {
      compilerOptions: {
        isPreTag: (tag) => tag === "pre" || tag === "q-markdown" || tag === "QMarkdown",
      },
    },
  },
}

CodePen And UMD Examples

The documentation examples use the UMD bundle when opening in CodePen.

If you maintain custom CodePen or script-tag examples, load the QMarkdown CSS and UMD bundle after Quasar:

<link
  href="https://cdn.jsdelivr.net/npm/@quasar/quasar-ui-qmarkdown@3.0.0/dist/index.min.css"
  rel="stylesheet"
/>
<script src="https://cdn.jsdelivr.net/npm/@quasar/quasar-ui-qmarkdown@3.0.0/dist/index.umd.min.js"></script>

Then register the component from the browser global:

app.component("QMarkdown", QMarkdown.QMarkdown);

Contributor Tooling Changes

The QMarkdown repository now uses:

• pnpm@11.10.0
• Node.js >=22.13
• oxlint instead of ESLint
• oxfmt instead of Prettier
• Vitest for runtime and API-drift tests
• Rolldown for UI package builds

Use the existing scripts for local verification:

pnpm format:check
pnpm lint
pnpm test
pnpm build
pnpm typecheck