Linked Markdown

Linked Markdown is a specification for Markdown documents with semantic frontmatter. It lets ordinary Markdown pages carry typed JSON-LD-style attributes that can be validated, queried, and loaded into RDF tooling such as Wazoo Worlds.

Example

---
{
  "@id": "https://example.org/docs/ethan-davidson",
  "@type": "schema:Person",
  "@context": { "schema": "https://schema.org/" },
  "schema:givenName": "Ethan",
  "schema:familyName": "Davidson",
}
---

# Ethan Davidson

Ethan Davidson is a
[knowledge graph engineer](./roles/knowledge-graph-engineer.md).

Markdown to JSON-LD

Before: a plain Markdown page with no machine-readable structure.

# Ethan Davidson

Ethan Davidson is a knowledge graph engineer.

After: the same content as a Linked Markdown document, where the frontmatter block parses as JSON-LD.

---
{
  "@id": "https://example.org/docs/ethan-davidson",
  "@type": "schema:Person",
  "@context": { "schema": "https://schema.org/" },
  "schema:givenName": "Ethan",
  "schema:familyName": "Davidson",
  "schema:jobTitle": "Knowledge graph engineer",
}
---

# Ethan Davidson

Ethan Davidson is a knowledge graph engineer.

The frontmatter parses directly into JSON-LD attributes via extract:

{
  "@id": "https://example.org/docs/ethan-davidson",
  "@type": "schema:Person",
  "@context": { "schema": "https://schema.org/" },
  "schema:givenName": "Ethan",
  "schema:familyName": "Davidson",
  "schema:jobTitle": "Knowledge graph engineer"
}

What it unlocks

Markdown that remains pleasant for humans to write.
Frontmatter that machines can interpret as semantic data.
Compatibility with JSON-LD, RDFLib, and RDF graph workflows.
Shared conformance tests across language implementations.

Repositories

Repository	Purpose
linked-markdown	Specification, paper, conformance suite, and community materials
linked-markdown-ts	TypeScript implementation published on JSR
linked-markdown-py	Python implementation published on PyPI

Install

npx jsr add @wazoo/linked-markdown

deno add jsr:@wazoo/linked-markdown

pnpm dlx jsr add @wazoo/linked-markdown

yarn dlx jsr add @wazoo/linked-markdown

bunx jsr add @wazoo/linked-markdown

pip install linked-markdown

Parse frontmatter

Use extract to read semantic attributes from a Markdown document:

import { extract } from "@wazoo/linked-markdown";

const result = extract(`---
{
  "@id": "https://example.org/docs/alice",
  "@type": "schema:Person"
}
---

# Alice
`);

console.log(result.attrs);
// { "@id": "https://example.org/docs/alice", "@type": "schema:Person" }

from linked_markdown import extract

result = extract("""---
{
  "@id": "https://example.org/docs/alice",
  "@type": "schema:Person"
}
---

# Alice
""")

print(result.attrs)
# {'@id': 'https://example.org/docs/alice', '@type': 'schema:Person'}

RDF compatibility

The attrs data returned by extract() is valid JSON-LD, ready for loading into RDF graph stores:

import json
import rdflib
from linked_markdown import extract

result = extract(markdown)
graph = rdflib.Graph()
graph.parse(data=json.dumps(result.attrs), format="json-ld")

import jsonld from "jsonld";
import { extract } from "@wazoo/linked-markdown";

const result = extract(markdown);
const quads = await jsonld.toRDF(result.attrs);
// quads is an Array of RDF/JS quads, directly loadable into RDF quad stores

Welcome

Platform

Skills

Ecosystem

Worlds

Guides

Console

Wazoo CLI

Integrations

Comparisons

Open source

Platform API

Worlds API

Example

Markdown to JSON-LD

What it unlocks

Repositories

Install

Parse frontmatter

RDF compatibility

​Example

​Markdown to JSON-LD

​What it unlocks

​Repositories

​Install

​Parse frontmatter

​RDF compatibility

Example

Markdown to JSON-LD

What it unlocks

Repositories

Install

Parse frontmatter

RDF compatibility