Home

Awesome

🎄 md-editor-v3

English | 中文

Markdown editor for vue3, developed in jsx and typescript.

⭐️ Features

📦 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 themeDark themePreview only

Inputing prompt and mark, emoji extensions

🎁 Apis

🔖 MdPreivew Props

nametypedefaultdescription
modelValuestring''Markdown content, use v-model in vue template
theme'light' | 'dark''light'Editor theme
classstring''
stylestring | CSSProperties{}Inline style
languagestring'zh-CN'Build-in language('zh-CN','en-US')
editorIdstring'md-editor-v3_[\d]'Editor's id, default incrementing by number. When using server-side rendering, make sure to set this attribute to a constant value
showCodeRowNumberbooleantrueShow row number for code block or not
previewTheme'default' | 'github' | 'vuepress' | 'mk-cute' | 'smart-blue' | 'cyanosis''default'Theme of preview, can be customized
noMermaidbooleanfalseUse mermaid or not
noKatexbooleanfalseUse katex or not
codeTheme'atom' | 'a11y' | 'github' | 'gradient' | 'kimbie' | 'paraiso' | 'qtcreator' | 'stackoverflow''atom'Highlight code style, can be customized also
mdHeadingId(text: string, level: number, index: number) => string(text) => textH1-H6 ID generator
sanitize(html: string) => string(html) => htmlThis attribute is used to alter the compiled HTML content
noIconfontbooleanfalseNot append iconfont script, you can get the latest link here
formatCopiedText(text: string) => string(text: string) => textFormat copied code
codeStyleReversebooleantrueCode style will be reversed to dark while code block of the theme has a dark background
codeStyleReverseListArray<string>['default', 'mk-cute']Themes to be reversed
noHighlightbooleanfalseHighlight code or not
noImgZoomInbooleanfalseEnable the function of enlarging images
customIconCustomIcon{}Customized icons
sanitizeMermaid(h: string) => Promise<string>(h: string) => Promise.resolve(h)Convert the generated mermaid code
codeFoldablebooleantrueWhether to enable code folding feature
autoFoldThresholdnumber30Threshold for triggering automatic code folding by line count

🔩 MdEditor Props

Except for the same as MdPreview:

nametypedefaultdescription
pageFullscreenbooleanfalseScreenfull in web page
previewbooleantruePreview content in editor
htmlPreviewbooleanfalsePreview html in editor(If true, preview must be false)
toolbarsArray<ToolbarNames | number>[toolbars]Show contents of toolbar, all keys<sup>see toolbars below</sup>
toolbarsExcludeArray<ToolbarNames | number>[]Don't show contents of toolbar, all keystoolbars
noPrettierbooleanfalseUse prettier to beautify content or not
tabWidthnumber2One tab eq some spaces
tableShape[number, number] | [number, number, number, number][6, 4]Preset the size of the table, [columns, rows, Maximum number of columns, Maximum number of rows]
placeholderstring''
footersArray<'markdownTotal' | '=' | 'scrollSwitch' | number>['markdownTotal', '=', 'scrollSwitch']Show contents of footer, they are divided by '='. Set it to [] to hidden footer
scrollAutobooleantrueScroll default setting
noUploadImgbooleanfalseNot show the entrance to upload pictures
autoFocusbooleanfalsesame as autofocus in native textarea
disabledbooleanfalsesame as disabled in native textarea
readOnlybooleanfalsesame as readonly in native textarea
maxLengthnumbersame as maxlength in native textarea
autoDetectCodebooleanfalseauto detect the type of pasted code, only support that copied from vscode
completionsArray<CompletionSource>[]@codemirror/autocomplete List of function to match keywords
showToolbarNamebooleanfalseShow toolbar name or not
inputBoxWitdhstring'50%'Default width of input box
transformImgUrl(imgUrl: string) => string | Promise<string>t => tTransform image links
<details> <summary>『toolbars』</summary>
[
  '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'
];
</details>

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.

<details> <summary>『StaticTextDefaultValue』</summary>

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;
  };
}
</details>

🧵 MdPreview Events

nametypedescription
onChangevalue: stringContent changed(bind to oninput of textarea)
onHtmlChangedhtml: stringCompile markdown successful event, you can use it to get the html code
onGetCataloglist: Array<HeadList>Get catalog of article

🪢 MdEditor Events

Except for the same as MdPreview:

nametypedescription
onSavevalue: string, html: Promise<string>Saving content, ctrl+s and clicking button will trigger it
onUploadImgfiles: Array<File>, callback: (urls: string[] | { url: string; alt: string; title: string }[]) => voidUploading picture, when picture is uploading the modal will not close, please provide right urls to the callback function
onErrorerr: { name: 'Cropper' | 'fullscreen' | 'prettier' | 'overlength'; message: string }Catch run-time error, Cropper, fullscreen and prettier are used when they are not loaded. And content exceeds the length limit error
onBlurevent: FocusEventTextarea has lost focus
onFocusevent: FocusEventTextarea has received focus
onInputevent: EventElement gets input
onDropevent: DragEventSelection is being dragged
onInputBoxWitdhChange(width: string) => voidWidth of input box has been changed

🎍 Slots

nametypedefaultdescription
defToolbarsArray<DropdownToolbar | NormalToolbar | ModalToolbar>nullCustom toolbar in DropdownToolbar, NormalToolbar or ModalToolbar
defFootersArray<string | VNode | JSX.Element>nullCustom footer

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' }
});
<details> <summary>『EditorExtensions』</summary>
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;
  };
}
</details>

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:

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!

keyfunctiondescription
TABinsert spaceInsert space, the length eq tabWidth, default: 2, support multiline
SHIFT + TABdelete space, setting is the same as Tab
CTRL + CcopyWhen selected, copy the selected content. When not selected, copy the content of the current line
CTRL + XshearWhen selected, cut the selected content. When not selected, cut the current line
CTRL + DdeleteWhen selected, delete the selected content. When not selected, delete the current line
CTRL + SsaveTrigger onSave event
CTRL + Bbold text**bold**
CTRL + Uunderline<u>underline</u>
CTRL + Iitalic*italic*
CTRL + 1-6h1-h6# title
CTRL + ↑superscript<sup>superscript</sup>
CTRL + ↓subscript<sub>subscript</sub>
CTRL + Oordered list1. ordered list
CTRL + Llink[link](https://github.com/imzbf/md-editor-v3)
CTRL + ZwithdrawWithdraw history in editor, not the function of system
CTRL + SHIFT + Sline-through~line-through~
CTRL + SHIFT + Uunordered list- unordered list
CTRL + SHIFT + Ccode block
CTRL + SHIFT + Ipicture![picture](https://imzbf.github.io/md-editor-v3/imgs/preview-light.png)
CTRL + SHIFT + ZforwardForward history in editor, not the function of system
CTRL + SHIFT + FBeautify
CTRL + ALT + Ccode row
CTRL + SHIFT + ALT + Ttable|table|

🪤 Internal Components

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

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

🐣 NormalToolbar

NormalToolbar

🐼 DropdownToolbar

DropdownToolbar

🦉 ModalToolbar

ModalToolbar

🐻 MdCatalog

MdCatalog

🛸 MdModal

MdModal

🛸 NormalFooterToolbar

NormalFooterToolbar

🪤 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;
}