Consider an original lab notebook that links a mention to a permitted specimen record. The author types @sample-018 and chooses the record. The notebook must reopen with a recognized mention, not an ordinary blue link whose identity has been lost.
Define the saved element before the feed menu
For this example, the application wants HTML with a clear marker and a separate stable record ID:
<a class="mention" data-mention="@sample-018"
data-user-id="specimen-018"
href="/specimens/018">@sample-018</a>
This is an original illustrative record, not a reference to a real specimen service. The official customization example uses data-user-id; keeping that attribute name here makes the converter contract easy to compare. In a real specimen application, choose a domain-appropriate attribute and update both converters consistently.
The menu item needs the mention's id and the extra properties that the downcast converter will use. Its visible label, directory lookup permission, and saved representation are separate decisions. Avoid treating a successful menu selection as proof that the saved element will survive the server's HTML filter.
Read custom properties with the mention helper
Within a custom upcast converter's model-value callback, the documented pattern is:
const mentionValue = editor.plugins.get('Mention').toMentionAttribute(
viewItem,
{
link: viewItem.getAttribute('href'),
userId: viewItem.getAttribute('data-user-id')
}
);
Here editor and viewItem are provided by the real converter integration. This fragment is not a complete plugin. Register the converter for the intended anchor, class, data-mention, and required attributes; use the official full converter example as the installation reference for your CKEditor release.
The helper creates the mention attribute object expected by CKEditor. Do not replace it with an object containing only a label and record ID. The mention carries internal properties needed for its editing and copy behavior.
Keep conversion priority and occurrence identity distinct
The documented custom converters use converterPriority: 'high' so they run before the standard Mention and Link conversions. Separately, the downcast attribute element uses priority: 20 to preserve the intended wrapping behavior with other text attributes. These settings serve different layers.
The downcast element also uses the mention's uid as its element ID. That helps keep neighboring mention occurrences from merging. Two references to the same specimen can share the stable specimen ID while remaining separate occurrences in the document. Current data output also persists that occurrence UID in data-mention-uid, in addition to the illustrative application attributes shown above.
Current official code treats clipboard conversion explicitly: it omits serialized data-mention-uid during copy or cut to prevent duplicated UIDs. Follow that current pattern rather than copying an older converter that blindly persists the occurrence identifier into clipboard HTML. Do not add a converter at the highest priority; Mention already uses a highest-priority guard to prevent partial mention copies from becoming malformed mentions.
Reopen and copy the specimen reference
Test the integration through its actual save path. Insert two references to the same specimen with text between them. Save, reopen, and inspect whether the expected marker, stable ID, and destination still survive. Copy a full mention and then only part of its text, checking the resulting document rather than assuming both operations should preserve an intact mention.
The Tiptap mention guide explains selecting a stable identity in another editor. CKEditor's custom upcast, downcast, and clipboard rules are a different persistence task. Finish by opening the saved specimen link with the notebook reader's permissions and confirming it resolves to the intended record.