Marks
Define text marks with a tag or a snippet, give them values with sanitized attributes, and toggle marks and pending marks from code.
A mark is formatting on a run of text: bold, a link, a color. Marks live in a plugin’s marks map, keyed by name. In the document a text run carries its marks as values: true for a plain mark, any JSON value for a valued one.
{ "text": "Edytor", "marks": { "bold": true, "link": { "href": "https://example.com" } } }
Options
tag?string
The mark's element. The core renders <tag data-edytor-mark="name">, the clipboard exports the same tag, and pasted HTML with this tag gets the mark.
stringattributes?(value) => Record<string, string | undefined>
The element's attributes, from the mark's value. Sanitize here. undefined omits an attribute.
(value) => Record<string, string | undefined>snippet?Snippet<[MarkSnippetPayload]>
Custom markup, rendered inside a core <span data-edytor-mark="name">. Wins over tag for rendering; tag is still used for copying.
Snippet<[MarkSnippetPayload]>edge?'inclusive' | 'exclusive' | 'side-dependent'
Whether text typed at the mark's edge takes the mark.
'inclusive' | 'exclusive' | 'side-dependent''inclusive'toolbar?{ label: string; icon: string; run?: (edytor) => void }
A button in the toolbar plugin: it toggles the mark, or calls run instead (the comments plugin's Comment button opens its composer).
{ label: string; icon: string; run?: (edytor) => void }copy?boolean
Whether copy and cut carry the mark. false copies the text without it, in the internal fragment and the HTML alike (a comment's anchor).
booleantrueparse?(element: HTMLElement) => value | undefined
HTML import: the mark's value when a pasted element carries it. Checked before the bare tag.
(element: HTMLElement) => value | undefinedmarkdown?[open, close] | ((value) => [open, close] | undefined)
Markdown export (toMarkdown): the delimiters around the marked text, ['==', '=='], or a function of the value (a link's ['[', '](href)']). Without one the text is exported unmarked.
[open, close] | ((value) => [open, close] | undefined)void?boolean
Render the mark's element with contenteditable="false".
booleanA mark with neither tag nor snippet renders its text with no element and copies as plain text.
When a run has several marks, they nest in registration order, the first registered innermost. The same order applies to rendering and to the copied HTML.
A tag mark
The simplest mark is a tag:
import type { Plugin } from 'edytor';
export const markerPlugin: Plugin = () => ({
marks: {
marker: { tag: 'mark', toolbar: { label: 'Highlight', icon: '🖍' } }
}
});
It renders <mark data-edytor-mark="marker">…</mark>, copies as <mark>, and a pasted <mark> element gets the mark with the value true. A mark without attributes matches its bare tag on paste; one with attributes is imported only through parse.
A valued mark
A valued mark stores a value and turns it into attributes. Values come from collaborators and from pasted HTML too, so treat them as untrusted: check their type and shape in attributes, and return undefined to drop an attribute.
import type { Plugin } from 'edytor';
const LANGS = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
export const languagePlugin: Plugin = () => ({
marks: {
// { text: 'bonjour', marks: { lang: 'fr' } } renders <span lang="fr">
lang: {
tag: 'span',
attributes: (value) => ({ lang: typeof value === 'string' && LANGS.test(value) ? value : undefined }),
parse: (element) => (element.localName === 'span' && element.lang) || undefined
}
}
});
For URLs and CSS the stakes are higher: the rich text link mark drops any href whose scheme is not http:, https:, mailto: or tel:, and its color mark drops a value containing ;, braces, quotes or url(. Do the same in your own marks.
A snippet mark
When a tag cannot express the markup, declare a snippet. It receives { content, mark, text }: content renders the marked text (and the marks nested inside), mark is the value, text the text segment’s handle.
<script module lang="ts">
import type { Plugin } from 'edytor';
import type { MarkSnippetPayload } from 'edytor';
export const spoilerPlugin: Plugin = () => ({
marks: {
spoiler: { snippet: spoiler }
}
});
</script>
{#snippet spoiler({ content }: MarkSnippetPayload)}
<span class="spoiler">{@render content()}</span>
{/snippet}
The core renders <span data-edytor-mark="spoiler"><span class="spoiler">…</span></span>. Without a tag the mark copies as plain text; declare one to copy it as an element (the snippet still renders). Keep the markup inline, and render the marked text only through content().
Edges
edge decides whether a character typed at the start or end of a marked run takes the mark:
inclusive(default): it does. Typing after bold text continues in bold.exclusive: it does not.side-dependent: at the start of the run it does; at the end, only when the caret is inside the run. The rich textlinkmark uses this, so text typed right after a link is not linked unless the caret was placed inside it.
The edge also decides what happens to text a collaborator types at the edge of a mark you set at the same time, before either of you saw the other’s change: inclusive takes it in at both ends, exclusive at neither, side-dependent at the start only. Every replica reaches the same result, whatever order the changes arrive in. A view tells its document the edges its mark records declare; a document with no view (the room, a headless createDocument) learns them from semantics.marks (defaultSemantics holds the link’s, as richTextMarks, and the comment’s, as commentMarks).
How concurrent marks merge
Each mark you set is one operation over its range, with a timestamp later than every mark its writer had seen. Where operations of one mark overlap, the latest wins; elsewhere each keeps its own range:
- two collaborators who bold overlapping text get the union in bold;
- red over “The quick” and blue over “quick fox”, set at the same time, keep “The” red and “fox” blue, and “quick” takes one of the two on every replica;
- removing bold from a word you see bold always wins over that bold.
A comment-like mark (one per thread) uses a key of its own per thread: comment:<id>. Each is a separate mark, so two overlapping comments never cut each other short, and the key reads the comment mark record (its tag, snippet, edge and copy). The comments plugin anchors its threads this way:
edytor.document.formatRange(blockId, 4, 9, { 'comment:c1': { id: 'c1' } });
Toggling marks from code
The rich text plugin exports its helpers. They act on the current selection and handle every text segment the selection spans:
import { richTextOperations } from 'edytor';
richTextOperations(edytor).setMarkAtRange('bold'); // toggle over the selection
richTextOperations(edytor).setMarkValueAtRange('color', '#d44c47'); // set a value
richTextOperations(edytor).removeAllMarksAtRange();
setMarkAtRange toggles any mark the editor defines, over each text segment the selection spans (the rich text marks are typed, any other name is accepted), and at a caret stages it for the next character typed:
import { richTextOperations, type EdytorInstance } from 'edytor';
export const toggleMark = (edytor: EdytorInstance, mark: string, value?: string) =>
richTextOperations(edytor).setMarkAtRange(mark, value);
Underneath, a mark is the formatRange operation: edytor.formatRange(id, offset, length, { [mark]: value }) sets mark over a range of block id (block offsets), and a value of null removes it; edytor.clearMarks(id, offset, length) removes every mark. Each is an operation plugins see in onBeforeOperation. The toggle (remove the mark when every part of the range has it, set it otherwise) is richTextOperations(edytor).setMarkAtRange(mark)’s.
Pending marks
At a collapsed caret there is no text to format: setMarkAtRange stages the mark instead, and the next characters typed at that caret take it. This is what Mod + B does before you type.
Staged marks are edytor.selection.pending, the full set of marks the next insertion carries (null for a mark switched off). Set them directly with edytor.selection.stage(marks), or clear them with edytor.selection.stage(undefined). Moving the caret clears them; typing at the caret consumes them.
Text inserted without explicit marks takes, in order of precedence: the common marks of the range it replaces, the pending marks, then the marks of its neighbor, filtered by each mark’s edge.