Knowledge Graph Format

Write Knowledge Graphs
as Markdown

MD-LD embeds semantic triples directly in Markdown using a lightweight annotation syntax. Human-readable. Machine-processable. Round-trip safe.

Markdown Input
# Alice
Alice [is a]
(schema:Person)
{@type}
Alice [knows]
(foaf:knows)
Bob
Alice [age]
(schema:age)
"30"^^xsd:int
Knowledge Graph
Alice
rdf:type schema:Person
foaf:knows Bob
schema:age "30"^^xsd:int
RDF Output
3 quads emitted
Round-trip: SAFE
Pipeline

How MD-LD Works

A round-trip pipeline from human-readable markdown to RDF quads and back. No data loss. No format lock-in.

Markdown Text parse Tokenizer + Lexer tokens State Machine triples Quad Builder quads RDF Quads round-trip generate
1
Write Markdown
Author knowledge in familiar Markdown with inline annotations
2
Tokenize
Lexer splits text into subject, predicate, object, type tokens
3
State Machine
Context-aware parser resolves implicit subjects and graph names
4
Emit Quads
Each triple gets a named graph from origin tracking, round-trip safe
Syntax Breakdown

Anatomy of an Annotation

Every MD-LD annotation is a structured 5-part tuple. Color-coded here so you can see each piece instantly.

Alice [knows] Bob (foaf:knows) {@type} <team-graph>
// Shorthand with implicit subject (from heading context):
[knows] Bob (foaf:knows)
Subject
The entity being described. Often the heading of the current section or an inline noun.
Predicate Label
Human-readable relationship label in square brackets. [knows], [is a], [created by].
Object
The value or target entity. Can be a literal, IRI reference, or another node.
Predicate IRI
The formal RDF predicate in parens using prefix:localname notation. (foaf:knows).
Type Hint
Optional datatype or role in curly braces. {@type}, {xsd:date}, {xsd:integer}.
Named Graph
Optional graph assignment in angle brackets. Enables provenance and multi-graph datasets.
Format Comparison

MD-LD vs. the Alternatives

How does MD-LD stack up against established RDF serialization formats?

Format Human Readable Machine Parseable Round-trip Safe Named Graphs Zero Dependencies
MD-LD Best ★★★★★ ★★★★★ ★★★★★ ✓ ✓
Turtle (.ttl) ★★★★★ ★★★★★ ★★★★★ — ✓
JSON-LD ★★★★★ ★★★★★ ★★★★★ ✓ —
RDFa ★★★★★ ★★★★★ ★★★★★ — —
N-Triples ★★★★★ ★★★★★ ★★★★★ — ✓

Complexity vs. Readability

Readability
MD-LD
96%
Turtle
64%
JSON-LD
40%
RDFa
38%
N-Triples
15%
Parse Speed
N-Triples
225K/s
Turtle
180K/s
MD-LD
225K/s
JSON-LD
108K/s
RDFa
67K/s
Applications

What People Build with MD-LD

From AI memory systems to academic knowledge bases, MD-LD fits wherever you need human + machine access to the same data.

🧠

Agent Memory

Give AI agents persistent, queryable memory stored in readable Markdown files. Agents write facts; humans can audit them without tooling.

📔

Personal Knowledge

Obsidian, Logseq, or plain text notes enriched with semantic triples. Your PKM becomes a queryable knowledge graph.

📚

Developer Docs

Embed structured metadata into API docs and READMEs. Link concepts, versions, and deprecation timelines as graph data.

🔬

Academic Research

Authors annotate findings, citations, and entities inline. Export to RDF for SPARQL queries and publication graphs.

🗂

Content Management

CMS content with embedded relationship data. Editors work in familiar Markdown; the CMS gets structured graph output.

🤝

Collaborative Editing

Teams co-author knowledge graphs in git-friendly plain text. Diffs are readable. Merges are meaningful. No binary formats.

Performance

By the Numbers

20KB
Gzipped bundle size
225K
Quads per second
0
Runtime dependencies
100%
Round-trip fidelity
Internals

Parser Architecture

Five composable stages, each with a single responsibility. Swap any stage without touching the others.

Raw Text Tokenizer Subject token Predicate token Object token Type token Graph token State Machine Context stack Heading scope Implicit subj Error recovery Quad Builder IRI resolution Prefix expand Literal typing Lang tags Blank nodes Origin Tracker Source file Line/col range Graph naming Round-trip key N-Quads / Turtle / JSON-LD
Tokenizer
Context-free lexer. Recognizes the 5 token types without caring about semantics.
State Machine
Tracks heading depth, infers implicit subjects, and manages annotation scope across lines.
Quad Builder
Expands prefixes, resolves blank nodes, applies datatype and language-tag logic.
Origin Tracker
Records source file, line, and column for every quad. Powers round-trip regeneration.
Get Started

Zero setup. Just write.

Drop the annotation syntax into any Markdown file. The parser does the rest.

Install
$ npm install md-ld
// parse.js
import { parse } from 'md-ld'
const quads = parse(markdownString)
console.log(quads.length) // → 3