llm-in-text/milkdown-docs/guide/collaborative-editing.md

Collaborative Editing

Milkdown supports collaborative editing powered by Y.js. We provide the @milkdown/plugin-collab plugin to help you use milkdown with yjs easily. This plugin includes basic collaborative editing features like:

• Sync between clients.
• Remote cursor support.
• Undo/Redo support.

::iframe{src="https://stackblitz.com/github/Milkdown/examples/tree/main/vanilla-collab"}

Configure Plugin

First you need to install the plugin and yjs through npm:

npm install @milkdown/plugin-collab

npm install yjs y-protocols y-prosemirror

And you also need to choose a provider for yjs, here we use y-websocket as an example.

After the installation, you can configure your editor:

// ...import other plugins
import { collab, collabServiceCtx } from "@milkdown/plugin-collab";

async function setup() {
  const editor = await Editor.make()
    .config(nord)
    .use(commonmark)
    .use(collab)
    .create();

  const doc = new Doc();
  const wsProvider = new WebsocketProvider("<YOUR_WS_HOST>", "milkdown", doc);

  editor.action((ctx) => {
    const collabService = ctx.get(collabServiceCtx);

    collabService
      // bind doc and awareness
      .bindDoc(doc)
      .setAwareness(wsProvider.awareness)
      // connect yjs with milkdown
      .connect();
  });
}

Now your editor can support collaborative editing. Isn't it easy?

Connect and Disconnect

You may want to control the connect status of the editor manually.

editor.action((ctx) => {
  const collabService = ctx.get(collabServiceCtx);
  const doc = new Doc();
  const wsProvider = new WebsocketProvider("<YOUR_WS_HOST>", "milkdown", doc);

  collabService.bindDoc(doc).setAwareness(wsProvider.awareness);

  document.getElementById("connect").onclick = () => {
    wsProvider.connect();
    collabService.connect();
  };

  document.getElementById("disconnect").onclick = () => {
    wsProvider.disconnect();
    collabService.disconnect();
  };
});

Default Template

By default, the editor will show a empty document. You may want to use a template to show a document.

const template = `# Heading`;

editor.action((ctx) => {
  const collabService = ctx.get(collabServiceCtx);
  const doc = new Doc();
  const wsProvider = new WebsocketProvider("<YOUR_WS_HOST>", "milkdown", doc);

  collabService.bindDoc(doc).setAwareness(wsProvider.awareness);

  wsProvider.once("synced", async (isSynced: boolean) => {
    if (isSynced) {
      collabService
        // apply your template
        .applyTemplate(markdown)
        // don't forget connect
        .connect();
    }
  });
});

Keep in mind that applying a template multiple times may cause some unexpected behavior, such as duplicate content. Because of this you need to make sure the template is applied only once.

By default, the template will only be applied if document get from remote server is empty. You can control this behavior through passing second parameter to applyTemplate:

collabService
  .applyTemplate(markdown, (remoteNode, templateNode) => {
    // return true to apply template
  })
  // don't forget connect
  .connect();

Here the nodes we get are prosemirror nodes. You should return true if the template should be applied, and false if not.