milkdown-element

Milkdown Crepe markdown editor packaged as a standalone web component. All dependencies (including CodeMirror, ProseMirror, Mermaid, etc.) are bundled into a single browser-ready ESM file.

Includes a read-only viewer component (milkdown-viewer-element) for displaying authored content without editing capabilities.

Install

npm install milkdown-element

Usage

<script type="module">
  import 'milkdown-element';
</script>

<milkdown-element doc="# Hello world"></milkdown-element>

Placeholder

<milkdown-element placeholder="Start typing..."></milkdown-element>

Listening for changes

<milkdown-element id="editor"></milkdown-element>
<script type="module">
  import 'milkdown-element';

  const editor = document.querySelector('#editor');
  editor.addEventListener('input', () => {
    console.log(editor.getMarkdown());
  });
</script>

With Lit

import 'milkdown-element';

html`
  <milkdown-element
    .doc=${this.markdown}
    placeholder="Start typing..."
    .onUpload=${(file: File) => this.uploadImage(file)}
    .onFileUpload=${(file: File) => this.uploadFile(file)}
    @input=${this.#onInput}
  ></milkdown-element>
`;

Viewer (read-only)

Use milkdown-viewer-element to render authored content without the toolbar, slash menu, or editing capabilities:

<milkdown-viewer-element .doc=${this.markdown}></milkdown-viewer-element>

The viewer renders all content types (images, iframes, mermaid diagrams, file blocks, code blocks, highlights, emoji, tables, and LaTeX) but disables all editing interactions.

Features

The editor ships with these built-in content types on top of standard markdown:

| Feature | Description | | --- | --- | | Toolbar | Floating formatting toolbar appears when text is selected | | Slash menu | Type / on an empty line to open a block insertion menu | | Image upload | Drag-and-drop or paste images; uses the onUpload callback | | File attachment | Attach downloadable files via the slash menu; uses onFileUpload | | Iframe embed | Embed external pages; available via slash menu or by typing ::iframe{src="url"} | | Mermaid diagrams | Create flowcharts and diagrams; available via slash menu or ```mermaid | | Highlight | Highlight text with ==highlighted text== or the toolbar button | | Emoji | Standard emoji support | | Tables | Insert and edit tables via the slash menu | | Code blocks | Syntax-highlighted code blocks with language selection | | LaTeX | Inline and block math via LaTeX syntax | | Lists | Bullet, ordered, and task lists | | Links | Paste URLs or use the link tooltip to add hyperlinks |

Custom Plugins

Both milkdown-element and milkdown-viewer-element accept a plugins property for registering custom Milkdown plugins. The editor also accepts onBuildMenu to add items to the / slash menu.

import type { MilkdownPlugin } from 'milkdown-element';

Quick start

html`
  <milkdown-element
    .plugins=${myPlugins}
    .onBuildMenu=${myBuildMenu}
  ></milkdown-element>

  <milkdown-viewer-element
    .plugins=${myViewerPlugins}
  ></milkdown-viewer-element>
`;

Building a plugin

A plugin is an array of MilkdownPlugin items created with helpers from @milkdown/kit/utils. At minimum you need a node schema (what the block looks like in ProseMirror) and a remark transform (how it maps to/from markdown).

1. Define the markdown format

Pick a markdown representation for your block. A fenced code block with a custom language is the easiest approach since it doesn't conflict with any built-in syntax:

```my-widget
some serialized data
```

2. Write a remark transform

Convert fenced code blocks with your language into a custom AST node type before Milkdown parses them:

import { $remark } from '@milkdown/kit/utils';
import { visit, SKIP } from 'unist-util-visit';

function remarkMyWidget() {
  return (tree: any) => {
    visit(tree, 'code', (node: any, index: number | undefined, parent: any) => {
      if (node.lang !== 'my-widget' || index == null || !parent) return;
      parent.children.splice(index, 1, {
        type: 'myWidget',
        data: node.value,
      });
      return [SKIP, index] as const;
    });
  };
}

const remarkPlugin = $remark('remarkMyWidget', () => remarkMyWidget as never);

3. Define the node schema

Use $node to describe how the node is parsed from markdown, serialized back, and rendered in the DOM. The toDOM return value controls what element appears in the editor:

import { $node } from '@milkdown/kit/utils';

const myWidgetNode = $node('myWidget', () => ({
  group: 'block',
  atom: true,
  isolating: true,
  marks: '',
  attrs: { data: { default: '' } },
  parseDOM: [
    {
      tag: 'my-widget',
      getAttrs: (dom: HTMLElement) => ({ data: dom.getAttribute('data') ?? '' }),
    },
  ],
  toDOM: (node) => ['my-widget', { data: node.attrs.data, contenteditable: 'false' }],
  parseMarkdown: {
    match: (node) => node.type === 'myWidget',
    runner: (state, node, type) => {
      state.addNode(type, { data: node.data });
    },
  },
  toMarkdown: {
    match: (node) => node.type.name === 'myWidget',
    runner: (state, node) => {
      state.addNode('code', undefined, node.attrs.data, { lang: 'my-widget' });
    },
  },
}));

4. Assemble the plugin array

Flatten everything into a single MilkdownPlugin[] — the remark, node, and any input rules or prose plugins:

import type { MilkdownPlugin } from '@milkdown/ctx';

export const myWidgetPlugin: MilkdownPlugin[] = [
  remarkPlugin,
  myWidgetNode,
].flat();

5. Add a slash menu item (optional)

Export a buildMenu function and pass it to the editor's onBuildMenu property:

import { commandsCtx, editorViewCtx } from '@milkdown/kit/core';
import { clearTextInCurrentBlockCommand } from '@milkdown/kit/preset/commonmark';

export function myWidgetBuildMenu(groupBuilder: any) {
  try {
    const group = groupBuilder.getGroup('advanced');
    group.addItem('my-widget', {
      label: 'My Widget',
      icon: '<svg>...</svg>',
      onRun: (ctx: any) => {
        const commands = ctx.get(commandsCtx);
        const view = ctx.get(editorViewCtx);
        commands.call(clearTextInCurrentBlockCommand.key);
        const { from } = view.state.selection;
        const tr = view.state.tr.replaceWith(
          from, from,
          myWidgetNode.type(ctx).create({ data: '' }),
        );
        view.dispatch(tr);
      },
    });
  } catch {
    // group may not exist
  }
}

html`<milkdown-element .onBuildMenu=${myWidgetBuildMenu}></milkdown-element>`;

Syncing interactive components with a NodeView

If your web component is interactive (buttons, inputs, etc.), the default toDOM rendering won't propagate changes back to ProseMirror. Use a $prose plugin to register a NodeView that listens for events from your component and updates the document:

import { $prose } from '@milkdown/kit/utils';
import { Plugin, PluginKey } from '@milkdown/kit/prose/state';

const myWidgetNodeView = $prose(() => new Plugin({
  key: new PluginKey('MY_WIDGET_VIEW'),
  props: {
    nodeViews: {
      myWidget: (node, view, getPos) => {
        const dom = document.createElement('my-widget');
        dom.setAttribute('data', node.attrs.data);
        dom.setAttribute('contenteditable', 'false');

        dom.addEventListener('widget-change', (e: Event) => {
          const { data } = (e as CustomEvent).detail;
          const pos = getPos();
          if (pos === undefined) return;
          view.dispatch(view.state.tr.setNodeMarkup(pos, undefined, { data }));
        });

        return {
          dom,
          update(updatedNode) {
            if (updatedNode.type.name !== 'myWidget') return false;
            dom.setAttribute('data', updatedNode.attrs.data);
            return true;
          },
          stopEvent: () => true,
          ignoreMutation: () => true,
        };
      },
    },
  },
}));

Add it to your plugin array:

export const myWidgetPlugin: MilkdownPlugin[] = [
  remarkPlugin,
  myWidgetNode,
  myWidgetNodeView,
].flat();

Your web component dispatches the event whenever its state changes:

this.dispatchEvent(new CustomEvent('widget-change', {
  detail: { data: this.data },
  bubbles: true,
  composed: true,
}));

Different components for editor vs viewer

You can provide separate plugin arrays to the editor and viewer so each renders a different web component for the same node. For example, an interactive admin component in the editor and a read-only display in the viewer:

// Editor plugin: renders <my-widget-admin>
const editorNode = $node('myWidget', () => ({
  /* ...same schema... */
  toDOM: (node) => ['my-widget-admin', { data: node.attrs.data, contenteditable: 'false' }],
}));

// Viewer plugin: renders <my-widget-display>
const viewerNode = $node('myWidget', () => ({
  /* ...same schema... */
  toDOM: (node) => ['my-widget-display', { data: node.attrs.data, contenteditable: 'false' }],
}));

export const editorPlugin: MilkdownPlugin[] = [remarkPlugin, editorNode].flat();
export const viewerPlugin: MilkdownPlugin[] = [remarkPlugin, viewerNode].flat();

html`
  <milkdown-element .plugins=${editorPlugin}></milkdown-element>
  <milkdown-viewer-element .plugins=${viewerPlugin}></milkdown-viewer-element>
`;

Both share the same remark transform and markdown serialization, so the data round-trips correctly between them. See the demo/ folder for a complete working example.

API

milkdown-element

| Property | Attribute | Type | Description | | --- | --- | --- | --- | | doc | doc | string | Markdown content to edit | | placeholder | placeholder | string | Placeholder text shown when the editor is empty | | onUpload | — | (file: File) => Promise<string> | Callback to upload an image; should return the image URL | | onFileUpload | — | (file: File) => Promise<{ url: string; name: string }> | Callback to upload a file; should return the download URL and display name | | resolveImageUrl | — | (url: string) => string \| Promise<string> | Optional URL resolver for image display (e.g. CDN proxy) | | plugins | — | MilkdownPlugin[] | Custom Milkdown plugins to register with the editor | | onBuildMenu | — | (builder: unknown) => void | Callback to add items to the / slash menu | | crepe | — | Crepe \| null | The underlying Crepe instance (read-only at runtime) |

| Method | Returns | Description | | --- | --- | --- | | getMarkdown() | string | Returns current editor markdown | | getImageSrcs() | string[] | Returns all image URLs found in the current markdown | | getFileSrcs() | string[] | Returns all file URLs found in the current markdown | | reset() | void | Clears the editor and re-initializes |

| Event | Detail | Description | | --- | --- | --- | | input | — | Fired when markdown content changes |

milkdown-viewer-element

| Property | Attribute | Type | Description | | --- | --- | --- | --- | | doc | doc | string | Markdown content to display | | resolveImageUrl | — | (url: string) => string \| Promise<string> | Optional URL resolver for image display | | plugins | — | MilkdownPlugin[] | Custom Milkdown plugins to register with the viewer |

Accessing the Crepe instance

The underlying Crepe instance is available via the crepe property. It is null until the editor finishes initializing.

const el = document.querySelector('milkdown-element');
await el.updateComplete;
el.crepe; // Crepe instance

The Crepe and MilkdownPlugin types are re-exported for TypeScript consumers:

import type { Crepe, MilkdownPlugin } from 'milkdown-element';

Development

npm run setup    # install deps for library + demo
npm run demo     # start the demo dev server (opens browser)

The demo imports directly from src/ via a Vite alias, so changes to the library source are reflected immediately with HMR.

Build

npm run build    # one-shot production build
npm run dev      # rebuild on file changes (watch mode)