Tiptap Semantic Links 🌿

Tiptap Semantic Links is a high-performance extension for the Tiptap/ProseMirror editor. It enables rich, portable span metadata (highlights, colors, comments) that round-trips perfectly to standard Markdown reference links.

✨ View Live Demo

Created by Luis Michio Kobayashi as part of the Meechi ecosystem.

Why this extension?

Standard Markdown lacks a way to store metadata for text spans. This extension implements the Semantic Markdown protocol for Tiptap/ProseMirror by:

1. Hydrating reference links [text][id] into Tiptap mark nodes with generic data-semantic-id attributes.
2. Serializing marks back into a clean Markdown body with a structured metadata footer.

• Automatic Fragment Merging: Solves the common ProseMirror issue where overlapping marks (like bolding part of a comment) split the metadata. This extension re-stitches them on save.
• Self-Healing (Recommended Pattern): We recommend implementing an "Orphan Cleaner" in your editor lifecycle. If a mark exists in the document but its ID is missing from the metadata footer (e.g., after an external git merge), the mark should be automatically removed to maintain document integrity.

Features

• Standard Alignment: Uses the @tiptap/extension-highlight name by default for broad compatibility.
• Protocol Implementation: Built on top of the Semantic Markdown specification.
• Generic Protocol: Uses data-semantic-id and data-semantic-color attributes to remain agnostic of the specific metadata type (comments, colors, etc).
• Smart Colors: Stores colors in the metadata footer rather than messy inline CSS.
• Modern Color Spaces: Fully supports modern CSS color spaces like OKLCH, RGB, and Hex.
• Visual Continuity: Set to a high priority (1000) by default. This ensures annotations are always the outer-most mark, wrapping all other formatting (bold, italic) into a single, continuous highlight box.

Self-Healing & Document Integrity

The extension focuses on the UI and serialization layers. For a production-grade experience, we recommend implementing an Orphan Cleaner pattern in your application lifecycle:

1. Detection: On document load, parse the metadata footer using @meechi-ai/semantic-markdown.
2. Healing: Iterate through the editor's marks. If a mark contains an ID that is no longer present in the footer (e.g., after an external git merge conflict), remove the mark from the document.
3. Stability: This ensures your visual annotations are always backed by valid data.

Conflict Resolution (UI Recommendations)

The extension uses a single mark type, meaning two semantic links cannot overlap on the same text node. To manage this, we recommend implementing a Priority Rule in your application logic:

1. Semantic Hierarchy: Decide which metadata type is most important. For example, in the Meechi ecosystem, Comments (ref-) always override and remove Colors (col-).
2. Mutual Exclusivity: Prevent overlapping annotations of the same high-priority type (e.g., block adding a new comment if the selection already contains one) to keep the Markdown footer clean.
3. Stable IDs: When changing a value (like updating a color), reuse the existing ID from the selection rather than generating a new one.

Commands

// Set a new semantic link with an ID and optional color
editor.commands.setSemanticLink({ 
  semanticId: 'ref-123', 
  color: 'oklch(55% 0.15 250)' 
});

// Update only the color of an existing annotation
editor.commands.setSemanticColor('oklch(60% 0.18 350)');

// Remove the annotation entirely
editor.commands.unsetSemanticLink();

Installation

yarn add @meechi-ai/tiptap-semantic-links @meechi-ai/semantic-markdown

Usage

import { Editor } from '@tiptap/core';
import { SemanticLink } from '@meechi-ai/tiptap-semantic-links';

const editor = new Editor({
  extensions: [
    StarterKit,
    SemanticLink.configure({
      name: 'highlight', // Keep as highlight for compatibility
    }),
  ],
});

Requirements

Requires @meechi-ai/semantic-markdown for the underlying parsing and serialization logic.

License

MIT.