md-editor-v3

md-editor-v3 is a markdown editor for Vue 3 built with TypeScript and JSX.

Key Capabilities

• UI/UX: Toolbar customization, full-screen mode, keyboard shortcuts, and built-in themes (Default and Dark).
• Content: Support for mermaid (>=1.8.0) diagrams, katex (>=1.9.0) mathematical formulas, and emoji extensions.
• Formatting: Built-in prettier support for beautifying markdown content.
• Media: Support for uploading, pasting, or clipping images.
• Preview Styles: Multiple preview themes including default, vuepress, github, cyanosis, mk-cute, and smart-blue.
• Performance: Supports on-demand import (since v4.0.0).

md-editor-v3 is a Markdown editor for Vue 3 developed with jsx and typescript. Key features include:

• Toolbar & UI: Shortcut insertion, full-screen mode, and customizable toolbar (order, visibility, and custom types like dropdowns or popups).
• Themes: Built-in light and dark themes; 6 preview themes (default, vuepress, github, cyanosis, mk-cute, smart-blue) and support for custom themes.
• Content Handling: Support for prettier formatting (via CDN), image pasting/uploading, and image cropping.
• Extensions: Support for mermaid diagrams (>=1.8.0) and katex math formulas (>=1.9.0).
• Capabilities: Multi-language support, keyboard shortcuts, and on-demand (tree-shaking) imports.

The library is organized into three main layers of exported components and utilities:

1. Main Components: The core entry points for users.

   • MdEditor: The full editor component.
   • MdPreview: A standalone component for rendering Markdown.
   • MdCatalog: A component for displaying the document outline/table of contents.

2. Reusable UI Components: Modular pieces for building custom layouts.

   • NormalToolbar, DropdownToolbar, ModalToolbar, NormalFooterToolbar.

3. Global Capabilities: Utilities and configurations.

   • config, XSSPlugin, clearSideEffects, and localization (zh_CN, en_US).

Internally, MdEditor is composed of a ToolBar, Content (which includes the CodeMirror editor, Markdown preview, HTML preview, and built-in catalog), and a Footer.

In md-editor-v3 version 6.5.x, ECharts code blocks are parsed using new Function by default, which may pose security risks in environments with strict CSP or untrusted content.

To improve security, if you are using version 6.5.0 or higher, you can use the editorExtensions.echarts.parseOption configuration to replace the default parser with JSON.parse. Note that version 7.0 is planned to use JSON.parse as the default.

To keep the initial bundle size small, md-editor-v3 uses a "heavy dependency lazy injection" pattern. Many rich-text capabilities are not installed by default but are managed via editorExtensions.

Supported heavy dependencies include:

• highlight, prettier, cropper, screenfull, mermaid, katex, echarts.

How it works:

• If you do not manually provide these instances, the components will attempt to inject the necessary CDN scripts/styles at runtime (e.g., injecting cropper resources only when image cropping is needed).
• Note: When using this pattern, be mindful of Content Security Policy (CSP) restrictions and potential side effects from CDN-injected scripts. You may need to manually clean up residual tags after multiple mount/unmount cycles.

The library separates the editing experience from the rendering result. To extend the functionality, you must choose the correct extension chain:

• To modify the Editor Experience (e.g., adding autocomplete, custom shortcuts, editor themes, or floating toolbars): Use the CodeMirror 6 extension system via codeMirrorExtensions.
• To modify the Rendering Result (e.g., adding new Markdown syntax, modifying code block HTML, adding XSS handling, or adjusting heading IDs): Use the markdown-it plugin system via markdownItConfig or markdownItPlugins.

If you manually generate an id for the editor or previewer, ensure it is stable across renders. Using Math.random() will cause hydration mismatches, broken directory linkage, or multiple instances interfering with each other.

• SSR Support: Since version 5.0, the default useId handles most SSR scenarios, so manual id passing is often unnecessary.
• Cross-component Linkage: If you need to link the editor/previewer with an external MdCatalog or custom business logic, explicitly pass the same stable id to both.

Before implementing md-editor-v3, identify which component matches your requirement:

• MdEditor: Use when you need a fully functional, editable Markdown editor.
• MdPreview: Use when you only need to render Markdown content (read-only).
• MdCatalog: Use when you need a table of contents (TOC) navigation.
• DropdownToolbar / ModalToolbar / NormalFooterToolbar: Use for creating custom toolbars or footers.
• config(): Use for modifying global dependencies (e.g., highlight.js, katex, mermaid, echarts), the rendering chain, or the editing chain.
• sanitize or XSSPlugin: Use to handle HTML security and XSS risks.
• clearSideEffects(): Use to clean up default injected external resources.

While MdEditor has a built-in preview mode, you should use MdPreview as a standalone component for specific use cases:

• Use MdPreview when you want to render content in a lightweight way, such as in a pure display/read-only mode or for SSR scenarios.
• Use MdEditor when you need the user to be able to toggle between editing and previewing modes within the editor interface.

Since markdown-it has html: true enabled by default, you should handle security if you allow user-generated content.

Two ways to sanitize:

1. Manual Sanitization: Use the sanitize(html) => html function to wrap your own logic (e.g., using DOMPurify).
2. XSSPlugin: Use the provided XSSPlugin as a markdown-it plugin within the rendering chain.

To use md-editor-v3 in your project, install it using your preferred package manager.

yarn add md-editor-v3

npm i md-editor-v3