Semantic Markdown
Semantic Markdown is a portable, standards-aligned protocol for storing rich span metadata (comments, highlights, AI provenance) directly inside standard Markdown documents.
It was created to solve a fundamental problem in the Meechi ecosystem: How do we store rich annotations without breaking the portability of the Markdown file?
The Reference-Link Protocol
Most editors use non-standard HTML spans (<span data-id="123">) or sidecar JSON files. These break portability and make version control a nightmare.
Semantic Markdown uses Reference-style Markdown links to turn the document footer into a lightweight database:
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.
- Zero Side-Effects: It ignores standard links like
[Google](https://google.com)and only targets specific ID prefixes.
Usage in Meechi
Meechi uses this protocol to "claim" knowledge. When you highlight a PDF or a manual, Meechi injects your commentary using this format. This ensures that even if you open your notes in another app 20 years from now, your thoughts are still there, readable and structured.
Categorized Metadata
The protocol is schema-agnostic, but we recommend using ID Prefixes for clarity:
ref-: Comments & personal notes.col-: Semantic highlighting (colors).ai-: AI Provenance (which model generated this text?).cite-: Citations and database cross-references.
Open Source
The core parsing logic is open source and available for any developer to use in their own local-first applications.
- NPM: @meechi-ai/semantic-markdown (opens in a new tab)
- GitHub: luismichio/semantic-markdown (opens in a new tab)