Skip to Content

Parse Open Graph metadata

Parse or fetch Open Graph, Twitter Card, JSON-LD, favicon and canonical metadata in Node.js and TypeScript with parseHTML() and preview().

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="Example article">
<meta property="og:description" content="An example article description.">
<meta property="og:image" content="/images/preview.jpg">`;

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

result.title; // "Example article"
result.image; // "https://example.com/images/preview.jpg"

The parser uses a streaming SAX tokenizer rather than constructing a browser DOM. Title precedence is Open Graph, Twitter Card, Dublin Core, the document <title>, then JSON-LD from the page's main entity.

Resolve relative URLs

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:. When you parse fetched HTML, use the final response URL as the base, not a URL the caller supplied.

Parse metadata in the body

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

The default head-first mode stops tokenizing after the document head. Turn on includeBodyContent when a page puts its JSON-LD or its first useful image in the body and the extra work is worth it.

Fetch HTML with preview()

Use parseHTML() when your application already has the HTML. Use preview() when linkpeek should fetch the URL with timeouts, byte limits, redirect checks, content decoding, and private-address blocking.

import { preview } from "linkpeek";

const result = await preview("https://github.com");
console.log(result.title, result.image, result.twitterCard);

Try the parser

Edit the sample. parseHTML() runs locally in your browser with the published package.

Base URL https://example.com/. Nothing is fetched; the input stays in this page.

Result Sample output is shown.

{
  "title": "Example article",
  "description": "An example article description.",
  "image": "https://example.com/cover.png",
  "siteName": "example.com",
  "statusCode": 0
}

statusCode: 0 means the HTML was parsed without a network request.