TypeScript implementation of Linked Markdown.

TypeScript implementation of Linked Markdown, published through JSR.

See the wazootech/linked-markdown repository for the specification, conformance suite, and reference documentation.

Installation

Deno

deno add linked-markdown@jsr:@wazoo/linked-markdown

import { extract } from "linked-markdown";

Node (npm)

npx jsr add @wazoo/linked-markdown

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

Bun

bunx jsr add @wazoo/linked-markdown

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

Browser (CDN)

For no-build browser demos, import from esm.sh:

import { extract } from "https://esm.sh/@jsr/wazoo__linked-markdown@0.1.0";

API

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

const result = extract(markdown);
// => { attrs: { "@id": "...", "@type": "...", ... }, frontMatter: "...", body: "..." }

extract<T>(content: string): { attrs: T, frontMatter: string, body: string }

Parses frontmatter from a Linked Markdown document. Supports YAML (---, ---yaml, = yaml =), JSON (---, ---json, = json =), and TOML (---toml, +++, = toml =) formats.

• Strips UTF-8 BOM and normalizes CRLF to LF before parsing.
• Returns frontMatter with a trailing newline for non-empty frontmatter (matching the conformance spec).
• frontMatter is "" for empty frontmatter (---\n---).
• body has leading newlines stripped (after the closing delimiter).

LinkedMarkdownError

Thrown for all error conditions. Has a code property for programmatic handling:

Code	When
LMD_NO_FRONTMATTER	No frontmatter delimiters found
LMD_INVALID_FRONTMATTER	Unknown marker, unparseable content, non-object attrs, or no closing delimiter

try {
  extract(markdown);
} catch (e) {
  if (e instanceof LinkedMarkdownError && e.code === "LMD_NO_FRONTMATTER") {
    // handle
  }
}

RDF Compatibility

The attrs returned by extract() is valid JSON-LD, directly convertible to RDF/JS quads:

import jsonld from "jsonld";

const result = extract(markdown);
const quads = await jsonld.toRDF(result.attrs);

Development

git submodule update --init --recursive

# Run all tests
deno test --allow-read --allow-env=LMD_CONFORMANCE_ROOT

# Run unit tests only
deno test --allow-read src/

# Run conformance tests only
deno test --allow-read --allow-env=LMD_CONFORMANCE_ROOT test/conformance_test.ts

The conformance suite is consumed from the wazootech/linked-markdown spec repository as a git submodule.

Shoulders

This implementation stands on the shoulders of:

• @std/front-matter: front matter extraction for JSON, YAML, and TOML formats
• wazootech/linked-markdown: the Linked Markdown specification and conformance suite