Overview

Fresh

What is MD-LD?

MD-LD (Markdown Linked Data) is not just another RDF syntax. It is a universal semantic writing interface that removes the intermediary between human text and machine-readable graphs.

MD-LD is the only RDF format that is both writable by humans and parseable by machines in the same document. Unlike Turtle (write-only), JSON-LD (machine-only), and RDFa (embedded-in-HTML-only), MD-LD annotations flow with natural Markdown prose, making knowledge graphs readable without a renderer.

Traditional systems require:

Human → UI → App Logic → Hidden Database → APIs → Exports

MD-LD enables:

Human text → Graph immediately

Core value: Author and maintain knowledge graphs as plain text with deterministic round-trip safety. No platforms, databases, or proprietary SaaS mediation required.

[ex] <tag:ame@example.com,2026:>

# Alice {=ex:alice .prov:Person label}

[Alice Smith] {ex:fullName}
[alice@example.com] {ex:email}

Generates RDF quads that work with n3.js, rdflib, and any RDF/JS-compatible library.

Why MD-LD?

The Problem with Current Systems

Most software today uses graphs internally but hides them behind UIs:

• Notion, Slack, Google Docs — Human interfaces over hidden graphs
• CRMs, task apps, note apps — Proprietary data silos
• Social networks — Platform-controlled knowledge prisons

Users cannot access the graph directly. Semantics are hidden. Data is locked in products.

The MD-LD Solution

MD-LD removes the intermediary. Writing becomes publishing. Publishing becomes graph construction.

Key benefits:

• Graph sovereignty — You own text, graph, provenance, execution, history
• No central platform required — Works offline, in browsers, on servers
• Universal semantic substrate — Agents can read, reason, write, execute, validate
• Continuous semantic narrative — Unifies chat, tasks, notes, emails, calendar, files
• Native time dimension — Every action, statement, correction becomes part of the graph
• Decentralized authority — RFC 4151 tag: URIs enable self-sovereign identity without central registries
• Text-native agent memory — LLM Agent memory substrate in plain text — parse context, write knowledge, merge with other agents, all as Markdown files. No database required.

Core Features

• Prefix folding — Build hierarchical namespaces with CURIE-based IRI authoring
• Subject declarations — {=IRI} and {=#fragment} for context setting
• Object IRIs — {+IRI} and {+#fragment} for temporary object declarations
• Three predicate forms — p (S to L), ?p (S to O), !p (O to S)
• Type declarations — .Class for rdf:type triples
• Datatypes and language — ^^xsd:date and @en support
• Fragments — Document structuring with {=#fragment}
• Polarity system — Sophisticated diff authoring with + and - prefixes
• Origin tracking — Complete provenance with lean quad-to-source mapping
• Span chains — Walkable textual topology between semantic blocks for context recovery
• Elevated statements — Automatic rdf:Statement pattern detection
• Primary metadata quartet — Subject, type, label, comment for document identity
• Round-trip safety — Deterministic parse to generate cycles

Bundle size: 86KB unminified, 20KB gzipped

Quick Start

Install via npm or pnpm:

pnpm install mdld-parse

import { parse, generate, merge } from 'mdld-parse';

// Parse MD-LD to RDF quads
const result = parse({ text: mdldString });
console.log(result.quads);      // RDF/JS quads
console.log(result.primary);    // Primary metadata (subject, type, label, comment)
console.log(result.statements); // Elevated statements
console.log(result.origin);     // Provenance tracking

// Generate MD-LD from quads
const { text } = generate({ quads: result.quads });

// Merge multiple documents (CRDT-style)
const merged = merge([doc1, doc2, doc3]);

Browser ESM

<script type="importmap">
{
  "imports": {
    "mdld-parse": "https://cdn.jsdelivr.net/npm/mdld-parse/+esm"
  }
}
</script>
<script type="module">
  import { parse } from 'mdld-parse';
  const result = parse('[ex] <tag:my@example.com,2026:test/>\n\n# Hello {=ex:init .prov:Activity label}');
</script>

Browser Console Example

You can paste this into your browser console to see a list of tasks rendered as JSON:

const mdld = await import('https://cdn.jsdelivr.net/npm/mdld-parse/+esm')

const text = `[my] <tag:alice@example.org:>

# Tasks {=my:tasks .prov:Collection label}

## Task 1 {=my:tasks/1 .prov:Activity label}
One of my [urgent] {my:tasks/status} [tasks] {+my:tasks !prov:hadMember}
> Explore deeper the concept of a triple in RDF {comment}

## Task 2 {=my:tasks/2 .prov:Activity label}
One of my [tasks] {+my:tasks !prov:hadMember}
> Start building knowledge graphs {comment}
`;

const result = mdld.parse({ text });
console.log(result.quads);

Real-World Applications

Personal Knowledge Management

[alice] <tag:alice@example.com,2026:>

# Meeting Notes {=alice:meeting-2024-01-15 .alice:Meeting label}

Attendees:
**Alice** {+alice:alice ?alice:attendee label}
**Bob** {+alice:bob ?alice:attendee label}

Action items:
**Review proposal** {+alice:task-1 ?alice:actionItem label}

Developer Documentation

[api] <tag:brian@example.org,2026:app/api/>
# Get User by ID {=api:/users/:id .api:Endpoint label}

Method: [GET] {+api:methods/GET ?api:method}
Path: [/users/:id] {api:path}
Status: [OK] {api:status}

Academic Research

[alice] <tag:alice@example.org,2026:>
# Semantic Web {=alice:research/paper-semantic-markdown .alice:ScholarlyArticle label}
Is part of [semantic research] {+alice:research/semantic !member}

Authored by [Alice Johnson] {+alice:alice-johnson ?alice:author} on [2026-08-12] {alice:datePublished ^^xsd:date}.

Content Management

[blog] <tag:justin@example.org,2026:>
# Understanding MD-LD {=blog:post-mdld .blog:Post label}

[MD-LD] {blog:emphasized} allows you to embed RDF directly in Markdown.

Documentation Map

Section	Description
Authoring Guide	Learn MD-LD syntax from scratch
API Reference	parse(), generate(), merge() functions
Syntax Reference	Complete syntax token reference
Concepts	Core concepts explained in depth
Specification	Formal specification
Examples	Working domain examples
Grammar	EBNF and TextMate grammar
Ontologies	Built-in W3C ontologies