md-editor-v3 v4.21.2

🎄 md-editor-v3

English | 中文

Markdown editor for vue3, developed in jsx and typescript.

• Documentation and example: Go

• Use it online: Go

• The same series editor for react: md-editor-rt

⭐️ Features

• Toolbar, screenfull or screenfull in web pages and so on.
• Themes, Built-in default and dark themes.
• Shortcut key for editor.
• Beautify your content by prettier(only for markdown content, not the code and other text).
• Multi-language, build-in Chinese and English(default: Chinese).
• Upload picture, paste or clip the picture and upload it.
• Render article directly(no editor, no event listener, only preview of content).
• Theme of preview, default, vuepress, github, cyanosis, mk-cute, smart-blue styles(not identical). It can be customized also(Refer to example page).
• mermaid(>=1.8.0), katex mathematical formula(>=1.9.0).
• Customize the toolbar as you like.
• On-demand Import(>=4.0.0).

📦 Install

yarn add md-editor-v3

Use existing extension of language and theme, such as Japanese

yarn add @vavt/cm-extension

Use existing components of toolbar, such as exporting content as PDF

yarn add @vavt/v3-extension

For more ways to use or contribute, please refer to: md-editor-extension

💡 Usage

When using server-side rendering, make sure to set editorId to a constant value.

Starting from 4.0.0, internal components can be imported on-demand.

✍🏻 Display Editor

<template>
  <MdEditor v-model="text" />
</template>

<script setup>
import { ref } from 'vue';
import { MdEditor } from 'md-editor-v3';
import 'md-editor-v3/lib/style.css';

const text = ref('# Hello Editor');
</script>

📖 Preview Only

<template>
  <MdPreview :editorId="id" :modelValue="text" />
  <MdCatalog :editorId="id" :scrollElement="scrollElement" />
</template>

<script setup>
import { ref } from 'vue';
import { MdPreview, MdCatalog } from 'md-editor-v3';
import 'md-editor-v3/lib/preview.css';

const id = 'preview-only';
const text = ref('# Hello Editor');
const scrollElement = document.documentElement;
</script>

When using server-side rendering, scrollElement should be of string type, eg: body, #id, .class.

🗺 Preview

Default theme	Dark theme	Preview only

Inputing prompt and mark, emoji extensions

🎁 Apis

🔖 MdPreivew Props

🔩 MdEditor Props

Except for the same as MdPreview:

[
  'bold',
  'underline',
  'italic',
  '-',
  'strikeThrough',
  'title',
  'sub',
  'sup',
  'quote',
  'unorderedList',
  'orderedList',
  'task', // ^2.4.0
  '-',
  'codeRow',
  'code',
  'link',
  'image',
  'table',
  'mermaid',
  'katex',
  '-',
  'revoke',
  'next',
  'save',
  '=',
  'pageFullscreen',
  'fullscreen',
  'preview',
  'previewOnly',
  'htmlPreview',
  'catalog',
  'github'
];

You can sort the toolbar as you like, split tools by '-', the left and right toolbars are divided by '='！

You can customize the toolbar. To display them, put index of defToolbars into toolbars(this is not standard), for more usage, please refer to docs.

Expand language, you need to replace all the content here:

export interface ToolbarTips {
  bold?: string;
  underline?: string;
  italic?: string;
  strikeThrough?: string;
  title?: string;
  sub?: string;
  sup?: string;
  quote?: string;
  unorderedList?: string;
  orderedList?: string;
  task?: string; // ^2.4.0
  codeRow?: string;
  code?: string;
  link?: string;
  image?: string;
  table?: string;
  mermaid?: string;
  katex?: string;
  revoke?: string;
  next?: string;
  save?: string;
  prettier?: string;
  pageFullscreen?: string;
  fullscreen?: string;
  catalog?: string;
  preview?: string;
  previewOnly?: string;
  htmlPreview?: string;
  github?: string;
  '-'?: string;
  '='?: string;
}

export interface StaticTextDefaultValue {
  // Toolbar hover tips(html title)
  toolbarTips?: ToolbarTips;
  // H1-H6 dropdown menu item
  titleItem?: {
    h1?: string;
    h2?: string;
    h3?: string;
    h4?: string;
    h5?: string;
    h6?: string;
  };
  imgTitleItem?: {
    link: string;
    upload: string;
    clip2upload: string;
  };
  // The modal tips of add link or upload picture
  linkModalTips?: {
    linkTitle?: string;
    imageTitle?: string;
    descLabel?: string;
    descLabelPlaceHolder?: string;
    urlLabel?: string;
    urlLabelPlaceHolder?: string;
    buttonOK?: string;
  };
  // The modal tips of clip the picture, v1.2.0
  clipModalTips?: {
    title?: string;
    buttonUpload?: string;
  };
  copyCode?: {
    text?: string;
    successTips?: string;
    failTips?: string;
  };
  mermaid?: {
    flow?: string;
    sequence?: string;
    gantt?: string;
    class?: string;
    state?: string;
    pie?: string;
    relationship?: string;
    journey?: string;
  };
  katex?: {
    // formula inline
    inline: string;
    // formula block
    block: string;
  };
  footer?: {
    markdownTotal: string;
    scrollAuto: string;
  };
}

🧵 MdPreview Events

🪢 MdEditor Events

Except for the same as MdPreview:

🎍 Slots

NormalToolbar example:

<template>
  <MdEditor>
    <template #defToolbars>
      <NormalToolbar title="mark" @onClick="handler">
        <template #trigger>
          <svg class="md-editor-icon" aria-hidden="true">
            <use xlink:href="#md-editor-icon-mark"></use>
          </svg>
        </template>
      </NormalToolbar>
    </template>
  </MdEditor>
</template>

<script setup lang="ts">
import { MdEditor, NormalToolbar } from 'md-editor-v3';
import 'md-editor-v3/lib/style.css';

const handler = () => {
  console.log('NormalToolbar clicked!');
};
</script>

🤱🏼 Expose

After 2.5.0, Editor exposes several methods on the instance, used to get or change the internal status of the editor.

<template>
  <MdEditor ref="editorRef" />
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { MdEditor } from 'md-editor-v3';
import type { ExposeParam } from 'md-editor-v3';
import 'md-editor-v3/lib/style.css';

const editorRef = ref<ExposeParam>();

onMounted(() => {
  editorRef.value?.on('catalog', console.log);
  editorRef.value?.toggleCatalog(true);
});
</script>

Switched to the opposite status, if toggle without input parameter.

👂🏼 on

Get the internal state of the editor, including pageFullscreen, fullscreen, preview, htmlPreview, catalog, etc.

type Keys =
  | 'pageFullscreen'
  | 'fullscreen'
  | 'preview'
  | 'previewOnly'
  | 'htmlPreview'
  | 'catalog';

editorRef.value?.on('pageFullscreen', (status) => console.log(status));

💻 togglePageFullscreen

Toggle status of fullscreen within the page.

editorRef.value?.togglePageFullscreen(true);

🖥 toggleFullscreen

Toggle status of fullscreen widthin browser.

editorRef.value?.toggleFullscreen(true);

📖 togglePreview

Toggle status of preview.

editorRef.value?.togglePreview(true);

📖 togglePreviewOnly

Toggle into Preview Only Mode.

editorRef.value?.togglePreviewOnly(true);

📼 toggleHtmlPreview

Toggle status of htmlPreview.

editorRef.value?.toggleHtmlPreview(true);

🧬 toggleCatalog

Toggle status of catalog.

editorRef.value?.toggleCatalog(true);

💾 triggerSave

Save actions will be triggered.

💉 insert

Manually insert content into textarea.

/**
 * @params selectedText
 */
editorRef.value?.insert((selectedText) => {
  /**
   * @return targetValue    Content to be inserted
   * @return select         Automatically select content, default: true
   * @return deviationStart Start position of the selected content, default: 0
   * @return deviationEnd   End position of the selected content, default: 0
   */
  return {
    targetValue: `${selectedText}`,
    select: true,
    deviationStart: 0,
    deviationEnd: 0
  };
});

For more examples, refer to source code of extension component

🎯 focus

Focus on textarea.

import type { FocusOption } from 'md-editor-v3';

const option: FocusOption | undefined = 'start';

// Cursor position when focusing on textarea, default: position when it last lost focus
editorRef.value?.focus(option);

✒️ rerender

Re render the content.

🔍 getSelectedText

Get the currently selected text.

🗑 resetHistory

Clear current history.

🎛 domEventHandlers

Supports listening to all DOM events.

editorRef.value?.domEventHandlers({
  compositionstart: () => {
    console.log('compositionstart');
  }
});

🎛 execCommand

Insert content into the editor via trigger.

editorRef.value?.execCommand('bold');

🔖 getEditorView

Get codemirror instance.

💴 Config Editor

Use config(option: ConfigOption) to reconfigure markdown-it and so on.

!WARNING

We recommend configuring it at the project entry point, such as in main.js for projects created with Vite. Avoid calling config within components!

codeMirrorExtensions

Customize new extensions based on theme and default extensions f codeMirror.

Example: Editor does not render the line number of textarea by default, this extension needs to be manually added

import { config } from 'md-editor-v3';
import { lineNumbers } from '@codemirror/view';

config({
  codeMirrorExtensions(_theme, extensions) {
    return [...extensions, lineNumbers()];
  }
});

markdownItConfig

Customize extensions, attributes of markdown-it, etc.

type MarkdownItConfig = (
  md: markdownit,
  options: {
    editorId: string;
  }
) => void;

Example: Use markdown-it-anchor to render a hyperlink symbol to the right of the title

import { config } from 'md-editor-v3';
import ancher from 'markdown-it-anchor';

config({
  markdownItConfig(mdit) {
    mdit.use(ancher, {
      permalink: true
    });
  }
});

markdownItPlugins

Select and add built-in plugins to markdown-it.

type MarkdownItPlugins = (
  plugins: Array<MarkdownItConfigPlugin>,
  options: {
    editorId: string;
  }
) => Array<MarkdownItConfigPlugin>;

Example: Modify the class name of the image.

import { config } from 'md-editor-v3';

config({
  markdownItPlugins(plugins) {
    return plugins.map((p) => {
      if (p.type === 'image') {
        return {
          ...p,
          options: {
            ...p.options,
            classes: 'my-class'
          }
        };
      }

      return p;
    });
  }
});

editorConfig

Add more languages, reset mermaid template or delay rendering time:

import { config } from 'md-editor-v3';

config({
  editorConfig: {
    languageUserDefined: { lang: StaticTextDefaultValue },
    mermaidTemplate: {
      flow: `flow tempalte`,
      ...more
    },
    // Default 500ms. It is set to 0ms when preview only and not set.
    renderDelay: 500,
    // for modal component
    zIndex: 2000
  }
});

editorExtensions

Config some dependency libraries, like highlight..

import { config } from 'md-editor-v3';

config({
  editorExtensions: { iconfont: 'https://xxx.cc' }
});

export interface EditorExtensions {
  highlight?: {
    instance?: any;
    js?: string;
    css?: {
      [key: string]: {
        light: string;
        dark: string;
      };
    };
  };
  prettier?: {
    standaloneJs?: string;
    parserMarkdownJs?: string;
  };
  cropper?: {
    instance?: any;
    js?: string;
    css?: string;
  };
  iconfont?: string;
  screenfull?: {
    instance?: any;
    js?: string;
  };
  mermaid?: {
    instance?: any;
    js?: string;
  };
  katex?: {
    instance?: any;
    js?: string;
    css?: string;
  };
}

editorExtensionsAttrs

Synchronously add attributes to the CDN link tags, consistent with the type of editorExtensions, with a value type of HTMLElementTagNameMap['tagName'].

import { config, editorExtensionsAttrs } from 'md-editor-v3';

config({
  editorExtensionsAttrs
});

Do not attempt to define the src \ onload \ id of the script and rel \ href \ id of the link in editorExtensionsAttrs, as they will be overwritten by default values

🫨 iconfontType

Set the way to display icons:

• svg: with symbol
• class: with font-class

If the icon is customized through the attribute customIcon, the customized icon will be used first.

🎨 mermaidConfig

Configure mermaid, Details

import { config } from 'md-editor-v3';

config({
  mermaidConfig(base: any) {
    return {
      ...base,
      logLevel: 'error'
    };
  }
});

🔧 katexConfig

Configure katex, Details

import { config } from 'md-editor-v3';

config({
  katexConfig(base: any) {
    return {
      ...base,
      strict: false
    };
  }
});

🪡 Shortcut Key

Pay attention: shortcut keys are only available when the textarea has received focus!

🪤 Internal Components

<script lang="ts" setup>
import { NormalToolbar } from 'md-editor-v3';
</script>

On-demand import. For more examples, refer to document.

🐣 NormalToolbar

NormalToolbar

• props

  • title: string, not required, title of toolbar.

• events

  • onClick: (e: MouseEvent) => void, required.

• slots

  • trigger: VNode | JSX.Element, required, it is usually an icon, which is displayed on the toolbar.

🐼 DropdownToolbar

DropdownToolbar

• props

  • title: string, not required, title of toolbar.
  • visible: boolean, required.

• events

  • onChange: (visible: boolean) => void, required.

• slots

  • trigger: VNode | JSX.Element, required, it is usually an icon, which is displayed on the toolbar.
  • overlay: VNode | JSX.Element, required, content of dropdown box.

🦉 ModalToolbar

ModalToolbar

• props

  • title: string, not required, title of toolbar.
  • modalTitle: string, not required, title of the Modal.
  • visible: boolean, required, visibility of Modal.
  • width: string, not required, width of Modal, default auto.
  • height: string, same as width.
  • showAdjust: boolean, not required, visibility of fullscreen button.
  • isFullscreen: boolean, required when showAdjust = true, status of fullscreen.
  • class: string, not required.
  • style: CSSProperties | string, not required.
  • showMask: boolean, not required, whether to display the mask layer, default true.

• events

  • onClick: () => void, required.
  • onClose: () => void, required, closed event.
  • onAdjust: (val: boolean) => void, fullscreen button was clicked.

• slots

  • trigger: VNode | JSX.Element, required, it is usually an icon, which is displayed on the toolbar.
  • default: VNode | JSX.Element, required, content of Modal.

🐻 MdCatalog

MdCatalog

• props

  • editorId: string, required, same as editor's editorId, used to register listening events.
  • class: string, not required.
  • mdHeadingId: MdHeadingId, not required, same as editor.
  • scrollElement: string | HTMLElement, not required, it is an element selector when its type is string. When previewOnly eq true, it is usually set to document.documentElement.
  • theme: 'light' | 'dark', not required, provide it when you want to change theme online, it is the same as Editor theme.
  • offsetTop: number, not required, highlight current item of catalogs when title is offsetTop pixels from the top, default 20.
  • scrollElementOffsetTop: number, not required, offsetTop of the scroll container，default 0.
  • isScrollElementInShadow: boolean, whether the scroll container is in web component, default false.

• events

  • onClick: (e: MouseEvent, t: TocItem) => void, not required, heading was clicked.
  • onActive: (heading: HeadList | undefined) => void, not required, heading was highlighted.

🛸 MdModal

MdModal

• props

  • title: string, not required, title of Modal.
  • visible: boolean, required, visibility of Modal.
  • width: string, not required, width of Modal, default auto.
  • height: string, same as width.
  • showAdjust: boolean, not required, visibility of fullscreen button.
  • isFullscreen: boolean, required when showAdjust = true, status of fullscreen.
  • class: string, not required.
  • style: CSSProperties | string, not required.
  • showMask: boolean, not required, whether to display the mask layer, default true.

• events

  • onClose: () => void, required, closed event.
  • onAdjust: (val: boolean) => void, fullscreen button was clicked.

• slots

  • default: VNode | JSX.Element, required, content of Modal.

🛸 NormalFooterToolbar

NormalFooterToolbar

• events

  • onClick: (e: MouseEvent) => void, not required, toolbar was clicked.

• slots

  • default: VNode | JSX.Element, required, content.

🪤 Internal Configuration

import {
  iconfontClassUrl,
  iconfontSvgUrl,
  allToolbar,
  allFooter,
  zh_CN,
  en_US
} from 'md-editor-v3';

console.log(iconfontClassUrl, iconfontSvgUrl, allToolbar, allFooter, zh_CN, en_US);

🗂 Examples

🎸 Jsx Template

import { defineComponent, reactive } from 'vue';
import { MdEditor } from 'md-editor-v3';
import 'md-editor-v3/lib/style.css';

export default defineComponent({
  setup() {
    const md = reactive({
      text: '# Hello Editor'
    });
    return () => (
      <MdEditor modelValue={md.text} onChange={(value) => (md.text = value)} />
    );
  }
});

🥹 Upload Picture

Tips: When you paste and upload GIF, it will upload a static picture. So you should upload it by file system!

<template>
  <MdEditor v-model="text" @onUploadImg="onUploadImg" />
</template>

<script setup>
import { ref } from 'vue';
import axios from 'axios';
import { MdEditor } from 'md-editor-v3';
import 'md-editor-v3/lib/style.css';

const text = ref('# Hello Editor');

const onUploadImg = async (files, callback) => {
  const res = await Promise.all(
    files.map((file) => {
      return new Promise((rev, rej) => {
        const form = new FormData();
        form.append('file', file);

        axios
          .post('/api/img/upload', form, {
            headers: {
              'Content-Type': 'multipart/form-data'
            }
          })
          .then((res) => rev(res))
          .catch((error) => rej(error));
      });
    })
  );

  // Approach 1
  callback(res.map((item) => item.data.url));

  // Approach 2
  // callback(
  //   res.map((item: any) => ({
  //     url: item.data.url,
  //     alt: 'alt',
  //     title: 'title'
  //   }))
  // );
};
</script>

🧙‍♂️ Change Styles

.css-vars(@isDark) {
  --md-color: if(@isDark, #999, #222);
  --md-hover-color: if(@isDark, #bbb, #000);
  --md-bk-color: if(@isDark, #000, #fff);
  --md-bk-color-outstand: if(@isDark, #333, #f2f2f2);
  --md-bk-hover-color: if(@isDark, #1b1a1a, #f5f7fa);
  --md-border-color: if(@isDark, #2d2d2d, #e6e6e6);
  --md-border-hover-color: if(@isDark, #636262, #b9b9b9);
  --md-border-active-color: if(@isDark, #777, #999);
  --md-modal-mask: #00000073;
  --md-modal-shadow: if(@isDark, 0px 6px 24px 2px #00000066, 0px 6px 24px 2px #00000019);
  --md-scrollbar-bg-color: if(@isDark, #0f0f0f, #e2e2e2);
  --md-scrollbar-thumb-color: if(@isDark, #2d2d2d, #0000004d);
  --md-scrollbar-thumb-hover-color: if(@isDark, #3a3a3a, #00000059);
  --md-scrollbar-thumb-active-color: if(@isDark, #3a3a3a, #00000061);
}

.md-editor {
  .css-vars(false);
}

.md-editor-dark {
  .css-vars(true);
}

Change background color in dark mode:

.md-editor-dark {
  --md-bk-color: #333 !important;
}