Semantic Markdown 🌿

Semantic Markdown is a portable, standards-aligned protocol for storing rich span metadata directly inside standard Markdown documents.

✨ View Live Demo

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

Why Semantic Links?

Most Markdown-based editors lose custom metadata when saving to .md. They either use non-standard HTML spans (<span data-id="123">) or sidecar JSON files that break portability and git-friendliness.

This package uses Reference-style Markdown links to turn the document footer into a lightweight database for your inline annotations.

The [selected text][ref-abc123] was interesting.

[ref-abc123]: # "type=comment; text=My note; author=user; quote=selected text"

Key Advantages

• 100% Valid Markdown: Renders as normal links (to #) in any standard viewer (GitHub, Obsidian, etc).
• Git-Friendly: Metadata in the footer avoids messy merge conflicts in the document body.
• Portability: Your annotations stay with the file, not in an external database.

Interoperability & Safety

A core design goal of this protocol is Zero Side-Effects. It is designed to live alongside standard Markdown links without interference:

• Private Namespace: The protocol only targets IDs with specific prefixes (e.g., ref-, col-) and a URL exactly matching #.
• Standard Link Preservation: Regular links like [Google](https://google.com) or reference links like [My Ref][1] are ignored by the parser.
• Graceful Fallback: In standard Markdown viewers, semantic links render as non-functional links to #. The document remains 100% readable and valid.

Reliability & Resiliency

The implementation includes several production-grade safeguards:

• Whitespace Resiliency: Automatically ignores whitespace-only marks to prevent "ghost links" like [ ][id] from polluting your documents.
• Automatic Upgrades: Can detect and "upgrade" legacy <span style="color:..."> tags into clean semantic links during the save process.
• Convergent Stability: The fragment merging algorithm handles complex, multi-layered formatting (nested bold/italic) by iterating until the Markdown structure is perfectly stable.

Implementations

Looking for a ready-to-use editor integration?

• Tiptap Semantic Links: The official Tiptap/ProseMirror extension for this protocol.

Metadata Examples

The protocol is schema-agnostic. While you can use any string for the ID, we recommend using ID Prefixes to categorize metadata at a glance:

1. Comments & Notes (ref- prefix)

Track discussions or personal thoughts on specific sentences. [ref-abc123]: # "type=comment; text=Need to verify this; author=luis"

2. Semantic Highlighting (col- prefix)

Attach colors or themes to words without using CSS in the body. [col-xyz789]: # "type=color; color=oklch(55% 0.15 250); label=Important"

3. AI Provenance (ai- prefix)

Track which parts of a document were generated by an AI vs. a Human. [ai-gen456]: # "type=provenance; source=ai; model=gpt-4; confidence=0.98"

4. Citations & Sources (cite- prefix)

Link text to specific database IDs or external library references. [cite-doc789]: # "type=citation; paperId=arxiv-1234; page=12"

Installation

yarn add @meechi-ai/semantic-markdown

Usage

import { parseSemanticDefinitions, generateLinkId } from '@meechi-ai/semantic-markdown';

// Generate a categorized ID
const commentId = generateLinkId('ref-'); // returns "ref-abc123"

// Define your own schema
interface MyMeta extends SemanticMetadata {
  text?: string;
  author?: string;
}

const defs = parseSemanticDefinitions<MyMeta>(markdownContent);

Spec: The Footer Format

The protocol follows a strict reference-link format: [id]: # "key1=encodedValue1; key2=encodedValue2"

• URL: Always # to ensure links are non-functional in viewers.
• Title: A semicolon-delimited list of key=value pairs.
• Encoding: Values are URL-encoded to support special characters (;, ", etc.).

License

MIT.