Mention markdown support

[zbeyens]

Discussed in #4451

^{Originally posted by maayanalgresie July 3, 2025}
Hi,

In the examples, I see that the markdown supports mentions of the type @FIRST or @first-second, but I need to mention full names that include spaces (e.g., @FIRST Last).

Is there a markdown format that supports mentions with spaces in the display name?
Or would I need to implement a custom parsing rule to handle this?

Thanks!

[placeholder](type:value) is a good pattern, for example Cursor mdc links uses that: [component.tsx](mdc:src/components/example/component.tsx)

@[zbeyens](https://github.com/zbeyens)
zbeyens
[yesterday](https://github.com/udecode/plate/discussions/4451#discussioncomment-13673676)
Maintainer
Here's the regex for parsing text format:

  // Basic regex
  const mentionRegex = /\[([^\]]+)\]\(mention:([^)]+)\)/g;

  // With capture groups:
  // $1 = display text
  // $2 = mention id

  // Example usage:
  const text = "Hello [John Doe](mention:user_123), check [Button.tsx](mention:file_abc)";

  // Parse all mentions
  const mentions = Array.from(text.matchAll(mentionRegex)).map(match => ({
    fullMatch: match[0],
    displayText: match[1],
    id: match[2],
    index: match.index
  }));

  // Replace mentions with custom rendering
  const rendered = text.replace(mentionRegex, (match, displayText, id) => {
    if (id.startsWith('user_')) {
      return `<span class="mention-user">@${displayText}</span>`;
    }
    if (id.startsWith('file_')) {
      return `<span class="mention-file">${displayText}</span>`;
    }
    return displayText;
  });

[zbeyens]

@claude open a PR for that, see markdown.mdx for the docs

[claude]

Claude finished @zbeyens's task —— View job • claude/issue-4467-20250707_122403 • Create PR ➔

---

I've successfully implemented markdown support for mentions with spaces! 🎉

Changes Made

1. Enhanced remarkMention plugin (packages/markdown/src/lib/plugins/remarkMention.ts):

   • Added support for [display text](mention:id) format alongside existing @username format
   • Plugin now converts links with mention: protocol to mention nodes during parsing

2. Updated serialization logic (packages/markdown/src/lib/rules/defaultRules.ts):

   • Mentions with spaces or special characters now use [display text](mention:id) format
   • Simple mentions without spaces continue using @username format
   • Properly encodes spaces and special characters for valid markdown URLs

3. Added comprehensive tests:

   • New deserialization tests for the link format
   • Updated serialization tests to verify URL encoding

4. Updated documentation (docs/(plugins)/(serializing)/markdown.mdx):

   • Added new section explaining both mention formats
   • Included examples for both simple and complex mentions

Example Usage

const markdown = `
Simple mention: @alice
Full name: [John Doe](mention:john_doe)
With spaces: [Jane Smith](mention:user_123)
`;

// Deserializes to mention nodes with values: 'alice', 'john_doe', 'user_123'
const value = editor.api.markdown.deserialize(markdown);

// Serializes back preserving the appropriate format
const output = editor.api.markdown.serialize();
// @alice
// [John Doe](mention:John%20Doe)
// [Jane Smith](mention:Jane%20Smith)

The implementation maintains full backward compatibility while enabling mentions with spaces as requested.