linkpeek
npm GitHub
Documentation

Guide

Parse Open Graph metadata without a DOM.

parseHTML() extracts Open Graph, Twitter Card, JSON-LD, favicon, canonical, media, and oEmbed discovery fields from HTML you already have. It does not fetch a URL or execute page JavaScript.

Parse an HTML string

import { parseHTML } from "linkpeek";

const html = `<!doctype html>
<meta property="og:title" content="A typed preview">
<meta property="og:description" content="Parsed without a DOM">
<meta property="og:image" content="/images/preview.jpg">`;

const result = parseHTML(html, "https://example.com/posts/one");

result.title; // "A typed preview"
result.image; // "https://example.com/images/preview.jpg"

The parser uses a streaming SAX tokenizer rather than constructing a browser DOM. Title precedence starts with Open Graph, then Twitter Card, JSON-LD, Dublin Core, and the document title.

Give relative metadata a trustworthy base URL

The second argument resolves relative image, favicon, canonical, video, audio, and oEmbed URLs. Extracted URLs are returned only when they resolve to http: or https:. Use the final response URL—not an untrusted caller-supplied substitute—as the base when parsing fetched HTML.

Opt into body metadata when needed

const result = parseHTML(html, baseUrl, {
	includeBodyContent: true,
});

The default head-first mode stops tokenizing after the document head. Enable body content when a page places JSON-LD or its first useful image in the body and the additional work is worth it.

Choose preview() for arbitrary URLs

Use parseHTML() when your application already owns the HTML. Use preview() when linkpeek should fetch the URL with timeouts, byte ceilings, redirect checks, content decoding, and its safe-by-default network policy.

Fetch a first preview →Full parser API →