Mavon Editor

Common errors

• [Vue warn]: Failed to resolve component: mavon-editor

  cause The Mavon Editor component has not been properly registered with your Vue application, or Vue cannot find its definition.
  fix Verify that you have correctly imported the `mavonEditor` plugin (default import) and then registered it globally using `app.use(mavonEditor)` (for Vue 3) or `Vue.use(mavonEditor)` (for Vue 2) in your application's entry point.

• TypeError: mavonEditor is not a function (when calling `app.use(mavonEditor)` or `Vue.use(mavonEditor)`)

  cause This typically occurs when `mavonEditor` was imported incorrectly as a named export instead of a default export, or if a CommonJS `require` statement was used in an ESM context and didn't resolve the default export correctly.
  fix Ensure you are using a default import for the plugin: `import mavonEditor from 'mavon-editor';`. If using CommonJS, confirm `const mavonEditor = require('mavon-editor');` (or `require('mavon-editor').default` in some interop cases) correctly provides the plugin object.

• My custom HTML styles (e.g., `style="color: red;"`) or certain HTML attributes are being removed from the Markdown output.

  cause The default XSS protection, introduced in v2.10.0, is actively filtering out HTML attributes or tags that are not explicitly whitelisted.
  fix In your editor's configuration options, specify the `xssOptions.whiteList` property to explicitly allow the HTML tags and attributes you need. For example, to allow `style` on `<span>` tags: `{ xssOptions: { whiteList: { span: ['style'] } } }`.

Warnings

• breaking Version 3.0.0 of Mavon Editor introduced official support for Vue 3, making it fundamentally incompatible with Vue 2 applications. Projects built with Vue 2 must continue using the v2.x branch (e.g., v2.10.4) or undertake a full migration to Vue 3 to utilize v3.x.
  Fix: For Vue 2 projects, explicitly install `mavon-editor@2` (e.g., `npm install mavon-editor@2`). For Vue 3 projects, install the latest version, typically `npm install mavon-editor@latest`.
• breaking Starting from v2.10.0, XSS defense mechanisms are enabled by default. This change filters attributes of all HTML tags within the Markdown output, which may inadvertently remove valid styling (e.g., `style="..."`) or other HTML attributes if not explicitly whitelisted. The `html` option also defaults to `true`; however, setting it to `false` is recommended if direct HTML tag rendering is not explicitly required to enhance security.
  Fix: If custom HTML attributes or specific tags are necessary, configure the `xssOptions.whiteList` property in the editor's options to explicitly permit them (e.g., `{ whiteList: { span: ['style'] } }`). For maximum security, consider setting `html: false` if raw HTML embedding is not a core requirement.
• gotcha The `mavon-editor` package exports a default plugin object for global use, not a named component. Attempting to import the component using named imports (e.g., `import { mavonEditor } from 'mavon-editor';`) will result in an `undefined` module or component resolution error.
  Fix: Always use a default import for the plugin: `import mavonEditor from 'mavon-editor';`.
• gotcha The editor's visual appearance is entirely dependent on its associated CSS. Neglecting to import the necessary CSS file will lead to an unstyled, broken, or poorly rendered editor component on your page.
  Fix: Ensure that `import 'mavon-editor/dist/css/index.css';` is included in your main application entry file (e.g., `main.js` or `main.ts`) or within the root component where Mavon Editor is used.

Install

• npm install mavon-editor npm
• yarn add mavon-editor yarn
• pnpm add mavon-editor pnpm

Imports

• mavonEditor (Vue plugin)
  wrong:

  import { mavonEditor } from 'mavon-editor';
  // Or for CommonJS in environments where default interop fails:
  // const mavonEditor = require('mavon-editor');

  correct:

  import mavonEditor from 'mavon-editor';

  The `mavon-editor` package provides a default export, which is a Vue plugin (compatible with both Vue 2 and Vue 3). This plugin is intended for global registration via `app.use()` (Vue 3) or `Vue.use()` (Vue 2) to make the `<mavon-editor>` component available throughout your application. Using named imports for the plugin will result in an error.
• Mavon Editor Styles

  import 'mavon-editor/dist/css/index.css';

  This CSS import is absolutely essential for the editor's visual appearance and proper layout. It must be included in your application's entry point or any component where the editor is utilized to ensure correct styling.
• Configuration Types

  import type { Config } from 'mavon-editor';

  For TypeScript users, importing the `Config` type provides strong typing for the editor's various properties and options, enabling better type safety and autocompletion when configuring the component.

Quickstart

Demonstrates global registration of Mavon Editor as a Vue 3 plugin and its usage within a root component. It showcases two-way data binding with `v-model`, basic configuration props, and event handling for markdown and HTML output, including a placeholder for image upload.

import { createApp, ref } from 'vue';
import mavonEditor from 'mavon-editor';
import 'mavon-editor/dist/css/index.css';

const app = createApp({
  template: `
    <div id="app" style="padding: 20px;">
      <h1>My Vue 3 Markdown App</h1>
      <mavon-editor
        v-model="markdownContent"
        :toolbarsFlag="true"
        :subfield="true"
        :boxShadow="true"
        style="height: 500px;"
        @change="onEditorChange"
        @imgAdd="onImageAdd"
      />
      <div style="margin-top: 20px;">
        <h3>Rendered HTML Preview:</h3>
        <div v-html="htmlContent" style="border: 1px solid #ccc; padding: 10px;"></div>
      </div>
    </div>
  `,
  setup() {
    const markdownContent = ref('# Hello Mavon Editor\n\nThis is a **Vue 3** markdown editor instance.\n\n```typescript\nconst message: string = "Hello World!";\nconsole.log(message);\n```\n\nYou can easily write Markdown, preview it, and even upload images.\n\n<span style="color: red;">This text is red.</span>');
    const htmlContent = ref('');

    const onEditorChange = (markdown, html) => {
      console.log('Markdown changed:', markdown);
      htmlContent.value = html;
    };

    const onImageAdd = (pos, $file) => {
      // Implement image upload logic here
      console.log(`Image at position ${pos} added:`, $file.name);
      // Example: Upload to server and replace markdown with uploaded URL
      // editor.$img2Url(pos, 'http://example.com/your-uploaded-image.png');
    };

    return { markdownContent, htmlContent, onEditorChange, onImageAdd };
  }
});

app.use(mavonEditor);
app.mount('#app');