# 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

```ts
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

```ts
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.

```ts
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.

Related: [Quick start](https://linkpeek.js.org/quick-start/) · [parseHTML() reference](https://linkpeek.js.org/api/#parse) · [Get the image from a URL](https://linkpeek.js.org/guides/get-og-image-from-url/) · [Next.js route](https://linkpeek.js.org/integrations/nextjs/) · [Cloudflare Workers](https://linkpeek.js.org/integrations/cloudflare-workers/) · [All libraries compared](https://linkpeek.js.org/guides/link-preview-library-comparison/) · [Missing metadata](https://linkpeek.js.org/guides/troubleshooting/#missing)
