Smart Editor

A framework-agnostic Markdown editor for web apps with split code/preview UX, runtime API, extensible toolbar actions, markdown-it parsing, and source-line synchronization.

This document is for developers integrating the editor into their own application. It is not an end-user guide for writing Markdown.

Contents

• Getting Started
• Supported Code Block Languages
• Embedding the Editor on a Page
• Configuration Options
• Runtime API
• Events and Callback Usage
• Built-in Plugins and Features
• Extending Functionality (Custom Toolbar Buttons)
• Versioned API Changes
• Markdown Compatibility Notes
• Security Notes
• License
• Development Commands
• Troubleshooting

Getting Started

Requirements

• Modern browser with ES module support.
• A container element with explicit height (important for CodeMirror layout).
• Optional globals for enhanced preview:
  • window.mermaid for Mermaid rendering.
  • KaTeX CSS for math rendering visuals.
• Fenced code blocks with an explicit language, for example javascript, are syntax-highlighted in preview.

Install dependencies (project development)

npm install

Build

npm run build

Build output is written to dist/:

• dist/smart-editor.esm.js
• dist/smart-editor.cjs.js
• dist/smart-editor.iife.js

Supported Code Block Languages

Syntax highlighting in preview is enabled for fenced code blocks with explicit language names, for example:

```javascript
console.log('hello');
```

Supported language labels:

• bash
• c
• cpp
• diff
• django
• dockerfile
• excel
• graphql
• handlebars
• http
• java
• javascript
• json
• kotlin
• lisp
• lua
• makefile
• markdown
• mathematica
• matlab
• nginx
• objectivec
• perl
• php
• plaintext
• powershell
• python
• ruby
• sql
• scala
• shell
• swift
• typescript
• xml

Common aliases are accepted (for example js, ts, html, sh, ps1, gql, md, objc).

Special fallback:

• curl is mapped to bash highlighting.

Embedding the Editor on a Page

Option A: Vanilla JS (createEditor)

<div id="editor" style="height: 600px;"></div>

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css">
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script>
  mermaid.initialize({ startOnLoad: false });
</script>

<script type="module">
  import { createEditor } from './dist/smart-editor.esm.js';

  const editor = createEditor('#editor', {
    value: '# Hello',
    mode: 'split',
    onChange: (markdown, tokens, html) => {
      console.log(markdown.length, tokens.length);
    },
  });

  window.editor = editor;
</script>

Option B: Web Component (<smart-editor>)

Importing the library registers the custom element as a side effect.

<smart-editor id="mde" mode="split" theme="auto" style="height: 600px;"></smart-editor>

<script type="module">
  import './dist/smart-editor.esm.js';

  const el = document.getElementById('mde');
  el.setMarkdown('# Initial content');

  el.addEventListener('se-change', (e) => {
    console.log(e.detail.markdown);
  });
</script>

Configuration Options

createEditor(element, options) and new EditorCore(element, options) use the same options schema.

| Option | Type | Default | Description | |---|---|---|---| | value | string | '' | Initial markdown content. | | mode | 'split' \| 'code' \| 'preview' \| 'wysiwyg' | 'split' | Initial view mode (wysiwyg is preview-first beta mode). | | scrollSync | boolean | true | In split mode, synchronizes vertical scrolling between code and preview using smooth animated follow. | | theme | 'auto' \| 'light' \| 'dark' \| 'sepia' \| 'midnight' \| 'solarized' \| 'nord' \| 'high-contrast' | 'auto' | Theme id applied to the editor root. auto follows the OS color scheme; the built-in presets can also be switched at runtime. | | markdown.options | object | {} | Options passed to markdown-it. | | markdown.plugins | Array | [] | Extra markdown-it plugins: [[pluginFn, pluginOpts?], ...]. | | upload.endpoint | string | undefined | Default upload endpoint (POST multipart/form-data) used for all file types with no matching entry in upload.endpoints. Images fall back to base64 when omitted or on error; non-image files require an endpoint and are rejected without one. | | upload.endpoints | Object.<string,string> | undefined | Per-type endpoint overrides. Keys can be a MIME type (image/png), a wildcard (image/*), or a file extension (.pdf). The first matching entry wins; unmatched files fall back to upload.endpoint. Example: { 'image/*': '/upload/image', 'application/pdf': '/upload/raw' } | | upload.headers | object | {} | Extra HTTP headers for upload requests (e.g. Authorization). | | upload.extraFields | object | {} | Extra FormData fields appended to every upload (e.g. { upload_preset: 'my_preset' } for Cloudinary unsigned upload). | | upload.responseUrlField | string | 'url' | JSON field in the upload response that holds the asset URL (e.g. 'secure_url' for Cloudinary). | | upload.maxSize | number | 5 * 1024 * 1024 | Max image size in bytes. | | upload.fileMaxSize | number | upload.maxSize | Max non-image file size in bytes. | | upload.formats | string[] | common image MIME list | Allowed image MIME types. | | upload.fileFormats | string[] | undefined | Allowed non-image MIME types/extensions (for example application/pdf, .docx). If omitted, non-image files are accepted. | | upload.pickerAccept | string | */* | Value for file-picker accept attribute. | | drawio.url | string | https://embed.diagrams.net/?embed=1&proto=json&spin=1&ui=min&libraries=1 | draw.io embed URL used by modal. Set your own URL for self-hosted/offline mode. | | drawio.allowHostedFallback | boolean | true | When true, editor retries with https://embed.diagrams.net if local/self-hosted draw.io fails to initialize. Set to false for strict offline mode. | | toolbar | object | undefined | Declarative toolbar layout: visible items, grouping, ordering, display mode, and dropdown menus. | | busy.showDelay | number | 140 | Delay (ms) before showing loading overlay (anti-flicker for very fast tasks). | | busy.minVisible | number | 180 | Minimum overlay visibility time (ms) once shown, to avoid flashing. | | busy.texts.defaultLabel | string | 'Working...' | Default busy label used when task does not provide one. | | busy.texts.cancel | string | 'Cancel' | Cancel button label in the loading overlay. | | compatibility.enabled | boolean | false | Enables publishing-compatibility validation and suggested fixes. | | compatibility.showPanel | boolean | false (auto true when enabled) | Shows built-in compatibility status panel above editor panes. | | compatibility.debounce | number | 500 | Validation debounce in milliseconds while typing. | | compatibility.showPreviewUsingProfile | boolean | false | When enabled, preview uses HTML generated by the compatibility profile. | | compatibility.markdownIt | object | Eleventy-like defaults | markdown-it options for the built-in Eleventy compatibility profile. | | compatibility.plugins | Array | [] | Extra markdown-it plugins for compatibility profile, e.g. [[markdownItAnchor, opts]]. | | compatibility.disableRules | string[] | ['emphasis'] | markdown-it rules disabled by the built-in Eleventy compatibility profile. | | compatibility.profile | object | Eleventy markdown-it profile | Custom profile implementing render(markdown) => { html, tokens? }. | | compatibility.rules | Array | built-in table rule | Validation/fix rules used by compatibility service. | | onChange | function | undefined | Called with (markdown, tokens, html). | | onSelectionChange | function | undefined | Called with current selection object. | | onPaste | function | undefined | Native paste event hook. | | onUploadStart | function | undefined | Called with (file). | | onUploadDone | function | undefined | Called with (file, urlOrBase64). | | onUploadError | function | undefined | Called with (file, error). | | onPreviewClick | function | undefined | Called with (element, { from, to }). | | onCommand | function | undefined | Called before runCommand(id, args). | | onCompatibilityReport | function | undefined | Called with latest compatibility report object. | | onCompatibilityStatusChange | function | undefined | Called with (status, report) on status transitions. | | onCompatibilityFixApplied | function | undefined | Called after user accepts compatibility fix proposal. | | onBusyChange | function | undefined | Called with busy overlay state { busy, count, label, detail, scope, locked, canCancel, cancelToken }. |

Compatibility Quick Start (Eleventy)

Use this setup when your production publishing pipeline is Eleventy and you want editor preview/validation to match it as closely as possible.

import { createEditor, createEleventyCompatibilityProfile } from 'smart-md-editor';
import markdownItAnchor from 'markdown-it-anchor';
import markdownItCollapsible from 'markdown-it-collapsible';

const profile = createEleventyCompatibilityProfile({
  markdownIt: {
    html: true,
    breaks: true,
    linkify: true,
  },
  disableRules: ['emphasis'],
  plugins: [
    [markdownItAnchor, {
      permalink: true,
      permalinkSymbol: '',
      permalinkBefore: false,
    }],
    [markdownItCollapsible, {}],
  ],
});

const editor = createEditor('#editor', {
  compatibility: {
    enabled: true,
    showPanel: true,
    profile,
  },
});

Notes:

• Keep Eleventy and editor markdown-it options/plugins aligned.
• The compatibility panel supports per-issue jump + fix and batch fix flow.
• Built-in table diagnostics include: table.missing-leading-pipe, table.missing-trailing-pipe, table.column-count-mismatch, table.invalid-separator-row.

Example: upload + parser plugins

const editor = createEditor('#editor', {
  value: '# Content',
  scrollSync: true,
  busy: {
    showDelay: 160,
    minVisible: 220,
    texts: {
      defaultLabel: 'Przetwarzanie...',
      cancel: 'Anuluj',
    },
  },
  upload: {
    // Option A: custom backend
    endpoint: '/api/upload',
    headers: { Authorization: `Bearer ${token}` },
    maxSize: 8 * 1024 * 1024,
    formats: ['image/png', 'image/jpeg', 'image/webp'],
    fileFormats: [
      'application/pdf',
      'application/msword',
      'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
      'application/vnd.ms-excel',
      'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
    ],
    pickerAccept: 'image/*,.pdf,.doc,.docx,.xls,.xlsx',

    // Option B: Cloudinary unsigned direct upload (no backend needed)
    // endpoint: 'https://api.cloudinary.com/v1_1/YOUR_CLOUD_NAME/image/upload',
    // extraFields: { upload_preset: 'YOUR_UPLOAD_PRESET' },
    // responseUrlField: 'secure_url',
    // maxSize: 10 * 1024 * 1024,
  },
  markdown: {
    options: { html: true, linkify: true, typographer: true },
    plugins: [
      [someMarkdownItPlugin, { someOption: true }],
    ],
  },
});

Example: theme selection

const editor = createEditor('#editor', {
  theme: 'sepia',
});

editor.setTheme('midnight');
console.log(editor.getAvailableThemes());

Built-in presets:

• light: neutral bright UI
• dark: neutral dark UI
• sepia: warm reading theme for long-form writing
• midnight: cool dark coding theme with stronger contrast
• solarized: classic balanced palette inspired by Solarized
• nord: cool arctic dark palette
• high-contrast: accessibility-focused very high contrast variant

Runtime API

Returned editor instance (or <smart-editor> proxies) provides:

| Method | Signature | Description | |---|---|---| | getMarkdown | () => string | Get current markdown string. | | setMarkdown | (markdown, opts?) | Replace full document. opts.undoable=false skips undo history entry. Use opts.preservePreviewScroll=true in toolbar/programmatic full-document rewrites to keep preview stable during render. | | getTokens | () => object[] | Get markdown-it token array for current markdown. | | getPreview | () => string | Get sanitized preview HTML. | | getSelection | () => { from, to, text, lineFrom, lineTo } | Current selection info (line* are 0-based). | | setSelection | (from, to) | Set selection by character offsets. | | insertText | (text, position?) | Insert text at cursor or explicit offset. | | replaceSelection | (text) | Replace current selection. | | undo | () | Undo in code editor. | | redo | () | Redo in code editor. | | focus | () | Focus code editor. | | setMode | (mode) | Switch mode: split, code, preview, wysiwyg. | | getMode | () => mode | Read current mode. | | setTheme | (theme) => string | Switch theme to auto or one of the registered built-in theme ids. | | getTheme | () => string | Read current theme id. | | getAvailableThemes | () => { id, label, description, scheme }[] | List built-in theme metadata for selectors/settings UIs. | | isBusy | () => boolean | Returns whether any tracked async task is currently active. | | getBusyState | () => object | Returns current busy state snapshot. | | beginBusyTask | (opts?) => string | Start a manual busy task and return its token. | | updateBusyTask | (token, patch) => void | Update message/details for a running busy task. | | endBusyTask | (token) => void | End a previously started busy task. | | cancelBusyTask | (token?) => void | Cancel one busy task by token, or all when omitted. | | runWithBusy | (task, opts?) => Promise<any> | Wrap an async task with loading overlay, lock, and optional cancellation signal. | | registerAction | (actionDef) | Register custom toolbar action. | | unregisterAction | (id) | Remove custom toolbar action. | | getToolbarConfig | () => object \| null | Get the current declarative toolbar config, if one is active. | | setToolbarConfig | (config) => void | Replace the toolbar layout at runtime. | | updateToolbarConfig | (mutator) => object | Mutate current toolbar config via callback and apply it. | | upsertToolbarGroup | (group) => object | Add or replace one toolbar group by id. | | removeToolbarGroup | (groupId) => object | Remove one toolbar group by id. | | upsertToolbarItem | (groupId, item, position?) => object | Add or replace one top-level group item. | | removeToolbarItem | (groupId, itemId) => object | Remove one top-level group item by id. | | upsertDropdownItem | (groupId, dropdownId, item, position?) => object | Add or replace one dropdown entry. | | removeDropdownItem | (groupId, dropdownId, itemId) => object | Remove one dropdown entry by id. | | runCommand | (id, args?) | Run action by id programmatically. | | openDrawioEditor | (opts?) => Promise<boolean> | Open draw.io modal and insert/update ![draw.io](image){xml} block line. | | proposeChange | (newMarkdown, opts?) => Promise<boolean> | Open diff modal and apply if accepted. Supports opts.mode: replace-all, replace-selection, insert-at-cursor. | | getCompatibilityReport | () => object | Get latest compatibility report (disabled, valid, warning, invalid). | | getCompatibilityStatus | () => 'disabled' \| 'valid' \| 'warning' \| 'invalid' | Get current compatibility status. | | isCompatibilityEnabled | () => boolean | Check whether compatibility mode is active. | | setCompatibilityEnabled | (enabled) => object | Enable/disable compatibility mode and return latest report. | | setCompatibilityProfile | (profile) => object | Replace compatibility profile and revalidate when enabled. | | validateCompatibility | (opts?) => object | Run compatibility validation manually. | | proposeCompatibilityFix | (issueId) => Promise<boolean> | Propose/apply one issue fix through diff modal. | | proposeAllCompatibilityFixes | () => Promise<boolean> | Propose/apply one combined fix for all fixable issues. | | destroy | () | Dispose editor instance and listeners. |

Example: programmatic content proposal

const accepted = await editor.proposeChange('# Suggested update\n\nGenerated text...');
if (accepted) {
  console.log('Applied');
}

Example: wrapping custom async work with loading state

await editor.runWithBusy(async ({ signal, update }) => {
  update({ label: 'Downloading template...', detail: 'Template: weekly-report' });

  const response = await fetch('/api/templates/weekly-report', { signal });
  const markdown = await response.text();
  editor.replaceSelection(markdown);
}, {
  label: 'Downloading template...',
  detail: 'Template: weekly-report',
  lock: true,
  cancellable: true,
});

Example: proposal apply modes

await editor.proposeChange('# Full replacement', { mode: 'replace-all' });
await editor.proposeChange('only this part', { mode: 'replace-selection' });
await editor.proposeChange(' inserted chunk ', { mode: 'insert-at-cursor' });

• replace-selection falls back to insert-at-cursor when no text is selected.
• In insert-at-cursor, insertion happens at the end of the current selection/cursor (selection.to).

Theme helpers export

import { EDITOR_THEME_PRESETS, getEditorThemeList } from 'smart-md-editor';

console.log(Object.keys(EDITOR_THEME_PRESETS));
console.log(getEditorThemeList());

If you want to add another built-in theme in the source tree, define its token set in src/styles/themes.js; the editor stylesheet consumes that registry automatically.

Events and Callback Usage

Compatibility callbacks example

const editor = createEditor('#editor', {
  compatibility: {
    enabled: true,
  },
  onCompatibilityStatusChange(status, report) {
    console.log(status, report.summary);
  },
});

const report = editor.validateCompatibility();
if (report.issues[0]?.fixable) {
  await editor.proposeCompatibilityFix(report.issues[0].id);
}

Compatibility profile example (Eleventy-like)

import markdownItAnchor from 'markdown-it-anchor';
import markdownItCollapsible from 'markdown-it-collapsible';

const editor = createEditor('#editor', {
  compatibility: {
    enabled: true,
    markdownIt: {
      html: true,
      breaks: true,
      linkify: true,
    },
    disableRules: ['emphasis'],
    plugins: [
      [markdownItAnchor, {
        permalink: true,
        permalinkSymbol: '',
        permalinkBefore: false,
      }],
      [markdownItCollapsible, {}],
    ],
  },
});

The built-in Eleventy compatibility profile already includes an image resize plugin compatible with #320px / #50% markers in image alt text.

JS callback options (createEditor)

const editor = createEditor('#editor', {
  onChange(markdown, tokens, html) {
    // Persist markdown or update app state
  },
  onSelectionChange(sel) {
    // sel: { from, to, text, lineFrom, lineTo }
  },
  onPreviewClick(element, range) {
    // range: { from, to }
  },
  onUploadStart(file) {
    console.log('Uploading:', file.name);
  },
  onUploadDone(file, value) {
    // value is URL (upload success) or base64 fallback.
    // Images become ![](...), other files become [file.name](...).
  },
  onUploadError(file, error) {
    console.warn(error.message);
  },
  onCommand(id, args) {
    console.log('Action run:', id, args);
  },
  onBusyChange(state) {
    // state.busy, state.label, state.detail, state.canCancel
    console.log('Busy:', state);
  },
});

Web Component events

<smart-editor> emits CustomEvents:

• se-change: detail = { markdown, tokens, html }
• se-selection-change: detail = { from, to, text, lineFrom, lineTo }
• se-preview-click: detail = { element, lineRange: { from, to } }
• se-busy-change: detail = { busy, count, label, detail, scope, locked, canCancel, cancelToken }

const el = document.querySelector('smart-editor');

el.addEventListener('se-change', (e) => {
  console.log(e.detail.markdown);
});

el.addEventListener('se-preview-click', (e) => {
  console.log(e.detail.lineRange.from);
});

Built-in Plugins and Features

The editor auto-registers built-in toolbar actions grouped by intent.

Inline formatting

• bold
• italic
• strikethrough
• inline-code

Block structure

• h1, h2, h3
• blockquote
• hr
• code-block

Lists

• ul
• ol
• task-list

Insert tools

• link
• image (URL prompt)
• asset-upload (asset picker + paste/drop support; images -> markdown image, files -> markdown link)
• table (dialog)
• mermaid
• drawio

Parser-level extensions included in core

• Source line mapping attributes for code-preview sync.
• Split-mode bidirectional smooth vertical scroll sync between code and preview (scrollSync, enabled by default).
• Table cell source-column metadata.
• draw.io image block rendering from ![draw.io](image){xml} with click-to-edit in preview.
• Fenced mermaid block placeholders rendered with Mermaid (if present).
• Inline/block math placeholders rendered with KaTeX post-processing.
• Image alt resize syntax: ![alt|320x180](url) -> <img width="320" height="180">.

Extending Functionality (Custom Toolbar Buttons)

Use registerAction to add custom actions to the toolbar.

Toolbar Layout Configuration

If toolbar is omitted, the editor renders the legacy toolbar derived from registered actions (group + order).

If toolbar is provided, the toolbar becomes fully declarative: you decide which items are visible, in what order, in which group, and whether each item renders as label, icon, or icon-label.

Supported item types

• Action reference: maps to a registered action by id.
• Custom item: defines its own run(api, state, args?) inline.
• Dropdown: groups action references and custom items under one hover/click trigger.

Toolbar config example

const toolbar = {
  groups: [
    {
      id: 'inline',
      order: 10,
      items: [
        { action: 'bold', display: 'icon' },
        { action: 'italic', display: 'icon' },
        {
          id: 'more-inline',
          label: 'More',
          display: 'icon-label',
          items: [
            { action: 'strikethrough', display: 'label' },
            { action: 'inline-code', label: 'Code', display: 'label' },
          ],
        },
      ],
    },
    {
      id: 'templates',
      order: 20,
      items: [
        {
          id: 'templates-menu',
          label: 'Templates',
          display: 'label',
          items: [
            {
              id: 'template-news',
              label: 'News Article',
              args: { templateId: 'news' },
              async run(api, state, args) {
                const res = await fetch(`/api/templates/${args.templateId}`);
                const { markdown } = await res.json();
                api.setMarkdown(markdown, { preservePreviewScroll: true });
              },
            },
          ],
        },
      ],
    },
  ],
};

Group schema

{
  id?: string,
  order?: number,
  items: ToolbarItem[],
}

toolbar.groups accepts either an array of group objects or an object map keyed by group id.

Item schema

type ToolbarDisplay = 'label' | 'icon' | 'icon-label';

type ToolbarItem =
  | string
  | {
      id?: string,
      action: string,
      label?: string,
      icon?: string,
      title?: string,
      shortcut?: string,
      display?: ToolbarDisplay,
      args?: object,
    }
  | {
      id?: string,
      label?: string,
      icon?: string,
      title?: string,
      shortcut?: string,
      display?: ToolbarDisplay,
      args?: object,
      isEnabled?: (state) => boolean,
      isActive?: (state) => boolean,
      run: (api, state, args?) => void | Promise<void>,
    }
  | {
      id?: string,
      label?: string,
      icon?: string,
      title?: string,
      display?: ToolbarDisplay,
      items: Array<string | object>,
    };

Runtime toolbar updates

Use helper methods when host data changes, for example after the user creates a new template.

Example for integrators: add a custom action button at runtime in declarative toolbar mode, even if the target group is not defined in initial toolbar.groups.

editor.registerAction({
  id: 'star-wrap',
  title: 'Add star',
  icon: '⭐',
  run(api, state) {
    const text = state.selection?.text;
    if (text) api.replaceSelection(`⭐ ${text} ⭐`);
    else api.insertText(' ⭐ ');
  },
});

editor.upsertToolbarItem('custom', {
  id: 'star-wrap-item',
  action: 'star-wrap',
  display: 'icon',
});

upsertToolbarItem(groupId, ...) auto-creates the group when it does not exist. If you need explicit group ordering, call upsertToolbarGroup({ id, order, items: [] }) first.

editor.upsertDropdownItem('templates', 'templates-menu', {
  id: 'template-new',
  label: 'New Template',
  async run(api) {
    const res = await fetch('/api/templates/new');
    const { markdown } = await res.json();
    api.setMarkdown(markdown, { preservePreviewScroll: true });
  },
});

editor.removeDropdownItem('templates', 'templates-menu', 'template-new');

Positioning is supported by optional { beforeId, afterId } for upsertToolbarItem and upsertDropdownItem.

Action schema

{
  id: string,
  label?: string,
  icon?: string,      // SVG string or text
  title?: string,
  group?: string,     // default: 'default'
  order?: number,     // default: 50
  shortcut?: string,  // display only
  isEnabled?: (state) => boolean,
  isActive?: (state) => boolean,
  run: async (api, state, args?) => void,
}

api object available in actions

• getMarkdown, setMarkdown
• getTokens, getPreview
• getSelection, setSelection
• insertText, replaceSelection
• runCommand
• getToolbarConfig, setToolbarConfig
• updateToolbarConfig
• upsertToolbarGroup, removeToolbarGroup
• upsertToolbarItem, removeToolbarItem
• upsertDropdownItem, removeDropdownItem
• openDrawioEditor
• focus

When an action rewrites the whole document (setMarkdown(...)), prefer:

api.setMarkdown(nextMarkdown, { preservePreviewScroll: true });

This keeps preview stable during synchronous/asynchronous render work and avoids visible jump on toolbar-triggered document rewrites.

state object available in actions

• state.selection
• state.markdown
• state.cursorLine

Example: async custom action

editor.registerAction({
  id: 'insert-suggestion',
  title: 'Insert suggestion',
  label: 'AI',
  group: 'custom',
  order: 200,
  async run(api, state) {
    const res = await fetch('/api/suggest', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ markdown: state.markdown }),
    });

    const { suggestion } = await res.json();
    api.replaceSelection(suggestion || 'No suggestion');
  },
});

To remove it later:

editor.unregisterAction('insert-suggestion');

Markdown Compatibility Notes

The editor is designed to keep markdown output compatible with markdown-it based pipelines.

• Core parser is markdown-it with configurable options/plugins.
• Generated markdown remains plain markdown text.
• Mermaid integration is represented as fenced blocks.
• draw.io integration is represented as ![draw.io](image){xml} lines.
• Image resizing metadata is encoded in alt text using |WxH suffix.

draw.io Markdown Format

draw.io diagrams are serialized as one markdown line:

![draw.io](<image-src>){<uri-encoded-xml>}

• <image-src> is typically a data:image/svg+xml;base64,... preview image.
• <uri-encoded-xml> is diagram XML encoded with encodeURIComponent.
• In preview, clicking the image or the Edit diagram button opens draw.io modal and preserves XML.

draw.io URL fallback behavior

By default, editor starts draw.io modal with hosted embed (https://embed.diagrams.net/?...). If you provide a custom local drawio.url and init fails, it retries once with hosted embed.

Use this option to enforce strict offline behavior:

createEditor(element, {
  drawio: {
    url: '/drawio/?embed=1&proto=json&spin=1&ui=min&libraries=1',
    allowHostedFallback: false,
  },
});

Self-hosted draw.io assets (optional)

The npm package ships editor code only (no bundled dist/drawio webapp). For offline/self-hosted mode, download draw.io assets directly to your application and point drawio.url at that location.

npx smart-md-editor drawio:download --out ./public/drawio --version latest

Static hosting examples:

# Vite / plain static app
npx smart-md-editor drawio:download --out ./public/drawio --version latest

# Next.js
npx smart-md-editor drawio:download --out ./public/drawio --version latest

# Any app served from a subpath, e.g. https://example.com/docs/
npx smart-md-editor drawio:download --out ./public/docs/drawio --version latest

URL mapping:

./public/drawio       -> /drawio/?embed=1&proto=json&spin=1&ui=min&libraries=1
./public/docs/drawio  -> /docs/drawio/?embed=1&proto=json&spin=1&ui=min&libraries=1

Then configure editor:

createEditor(element, {
  drawio: {
    url: '/drawio/?embed=1&proto=json&spin=1&ui=min&libraries=1',
    allowHostedFallback: false,
  },
});

Example

![draw.io](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iLi4uIj48L3N2Zz4=){%3Cmxfile%20host%3D%22app.diagrams.net%22%3E%3Cdiagram%20id%3D%22d1%22%20name%3D%22Page-1%22%3E%3CmxGraphModel%3E%3Croot%3E%3CmxCell%20id%3D%220%22%2F%3E%3CmxCell%20id%3D%221%22%20parent%3D%220%22%2F%3E%3C%2Froot%3E%3C%2FmxGraphModel%3E%3C%2Fdiagram%3E%3C%2Fmxfile%3E}

Security Notes

• Preview HTML is sanitized with DOMPurify before rendering.
• If you add custom parser output attributes/tags needed in preview, update the allowlist in src/ui/PreviewPanel.js.
• Upload endpoint must validate file type/size server-side as well.

License

This project is licensed under the MIT License. See LICENSE for details.

Versioned API Changes

Use this section as a compatibility reference when upgrading the editor in host applications.

0.1.0

• Initial public integration surface:
  • Factory: createEditor(element, options)
  • Exports: EditorCore, SmartEditorElement
  • Web Component registration: <smart-editor>
• Runtime API includes document ops, selection ops, mode switching, action registration, draw.io modal, and diff-based proposeChange.
• Core options include markdown-it configuration, upload configuration, draw.io URL override, and integration callbacks.
• Built-in action groups include inline formatting, blocks, lists, links/images, table/mermaid/draw.io, and image upload.
• Parser support includes source-line mapping, table cell metadata, Mermaid/KaTeX placeholders, draw.io image+xml blocks, and image dimension syntax (|WxH).

Upgrade Notes

• Treat any removal or signature change in methods listed under Runtime API as breaking.
• Treat callback signature changes in Configuration Options as breaking.
• Treat changes to markdown serialization conventions (draw.io image+xml block, image |WxH) as breaking for downstream pipelines.
• Prefer additive changes for custom action integrations: add new action IDs instead of mutating existing IDs used by host automation.

0.2.0

• Added declarative toolbar config for explicit grouping, ordering, display mode selection, and dropdown menus.
• Added runtime toolbar methods: getToolbarConfig() and setToolbarConfig(config).
• Toolbar items now support inline async run(api, state, args?) handlers in addition to references to registered actions.
• Added runtime toolbar helper methods for granular updates (updateToolbarConfig, upsert/remove for groups/items/dropdown items).

Development Commands

npm install
npm run build
npm run dev
npm run drawio:download

To run the demo, serve from repository root (not from demo/):

npx serve .

Then open /demo/ in the browser.

Troubleshooting

Editor is blank or layout is broken

Ensure the editor container has explicit height, for example:

<div id="editor" style="height: 600px;"></div>

Mermaid blocks stay as raw code

Ensure Mermaid script is loaded and initialized on the page (window.mermaid).

Math blocks render as placeholders or plain text

Ensure KaTeX CSS is loaded. (KaTeX rendering is run by core, CSS controls visual output.)

Assets do not upload

For images, if upload.endpoint is missing or the upload request fails, the editor falls back to embedding the image as a base64 data URI (![](data:image/...;base64,...)), so the document remains self-contained.

For non-image files (PDF, Word, Excel, etc.), there is no base64 fallback — a data-URI makes no sense as a markdown link and would bloat the document. If no endpoint resolves for a non-image file, onUploadError is fired and nothing is inserted.

If your storage service uses different endpoints per resource type (e.g. Cloudinary's /image/upload vs /raw/upload), use upload.endpoints:

upload: {
  endpoint: 'https://api.cloudinary.com/v1_1/demo/raw/upload',   // default for everything
  endpoints: {
    'image/*': 'https://api.cloudinary.com/v1_1/demo/image/upload', // images go here instead
  },
  extraFields: { upload_preset: 'my_preset' },
}

React usage

A React adapter exists at src/adapters/react/SmartEditor.jsx. It exports SmartEditor. In the current build exports, the main package entry exports createEditor, EditorCore, and SmartEditorElement.