initial commit

docs/guides/html-rewriter/extract-links.mdx

@@ -0,0 +1,71 @@
+---
+title: Extract links from a webpage using HTMLRewriter
+sidebarTitle: Extract links using HTMLRewriter
+mode: center
+---
+
+## Extract links from a webpage
+
+Bun's [HTMLRewriter](/runtime/html-rewriter) API extracts links from HTML. Chain CSS selectors to match the elements, text, and attributes you want to process. Then pass `.transform` a `Response`, `ArrayBuffer`, or `string`.
+
+```ts extract-links.ts icon="/icons/typescript.svg"
+async function extractLinks(url: string) {
+  const links = new Set<string>();
+  const response = await fetch(url);
+
+  const rewriter = new HTMLRewriter().on("a[href]", {
+    element(el) {
+      const href = el.getAttribute("href");
+      if (href) {
+        links.add(href);
+      }
+    },
+  });
+
+  // Wait for the response to be processed
+  await rewriter.transform(response).blob();
+  console.log([...links]); // ["https://bun.com", "/docs", ...]
+}
+
+// Extract all links from the Bun website
+await extractLinks("https://bun.com");
+```
+
+---
+
+## Convert relative URLs to absolute
+
+When scraping websites, you often want to convert relative URLs (like `/docs`) to absolute URLs:
+
+{/* prettier-ignore */}
+```ts extract-links.ts icon="/icons/typescript.svg"
+async function extractLinksFromURL(url: string) {
+  const response = await fetch(url);
+  const links = new Set<string>();
+
+  const rewriter = new HTMLRewriter().on("a[href]", {
+    element(el) {
+      const href = el.getAttribute("href");
+      if (href) {
+        // Convert relative URLs to absolute // [!code ++]
+        try { // [!code ++]
+          const absoluteURL = new URL(href, url).href; // [!code ++]
+          links.add(absoluteURL);
+        } catch { // [!code ++]
+          links.add(href); // [!code ++]
+        } // [!code ++]
+      }
+    },
+  });
+
+  // Wait for the response to be processed
+  await rewriter.transform(response).blob();
+  return [...links];
+}
+
+const websiteLinks = await extractLinksFromURL("https://example.com");
+```
+
+---
+
+See [`HTMLRewriter`](/runtime/html-rewriter).

docs/guides/html-rewriter/extract-social-meta.mdx

@@ -0,0 +1,97 @@
+---
+title: Extract social share images and Open Graph tags
+sidebarTitle: OpenGraph tags
+mode: center
+---
+
+## Extract social share images and Open Graph tags
+
+Bun's [HTMLRewriter](/runtime/html-rewriter) API extracts social share images and Open Graph metadata from HTML by matching CSS selectors against the elements, text, and attributes you want to process. Use it to build link previews, social media cards, or web scrapers.
+
+```ts extract-social-meta.ts icon="/icons/typescript.svg"
+interface SocialMetadata {
+  title?: string;
+  description?: string;
+  image?: string;
+  url?: string;
+  site_name?: string;
+  type?: string;
+}
+
+async function extractSocialMetadata(url: string): Promise<SocialMetadata> {
+  const metadata: SocialMetadata = {};
+  const response = await fetch(url);
+
+  const rewriter = new HTMLRewriter()
+    // Extract Open Graph meta tags
+    .on('meta[property^="og:"]', {
+      element(el) {
+        const property = el.getAttribute("property");
+        const content = el.getAttribute("content");
+        if (property && content) {
+          // Convert "og:image" to "image" etc.
+          const key = property.replace("og:", "") as keyof SocialMetadata;
+          metadata[key] = content;
+        }
+      },
+    })
+    // Extract Twitter Card meta tags as fallback
+    .on('meta[name^="twitter:"]', {
+      element(el) {
+        const name = el.getAttribute("name");
+        const content = el.getAttribute("content");
+        if (name && content) {
+          const key = name.replace("twitter:", "") as keyof SocialMetadata;
+          // Only use Twitter Card data if nothing has set this key yet (OG tags always overwrite it)
+          if (!metadata[key]) {
+            metadata[key] = content;
+          }
+        }
+      },
+    })
+    // Fallback to regular meta tags
+    .on('meta[name="description"]', {
+      element(el) {
+        const content = el.getAttribute("content");
+        if (content && !metadata.description) {
+          metadata.description = content;
+        }
+      },
+    })
+    // Fallback to title tag
+    .on("title", {
+      text(text) {
+        if (!metadata.title) {
+          metadata.title = text.text;
+        }
+      },
+    });
+
+  // Process the response
+  await rewriter.transform(response).blob();
+
+  // Convert relative image URLs to absolute
+  if (metadata.image && !metadata.image.startsWith("http")) {
+    try {
+      metadata.image = new URL(metadata.image, url).href;
+    } catch {
+      // Keep the original URL if parsing fails
+    }
+  }
+
+  return metadata;
+}
+```
+
+```ts Example Usage icon="/icons/typescript.svg"
+// Example usage
+const metadata = await extractSocialMetadata("https://bun.com");
+console.log(metadata);
+// {
+//   title: "Bun — A fast all-in-one JavaScript runtime",
+//   description: "Bundle, install, and run JavaScript &amp; TypeScript — all in Bun. Bun is a fast JavaScript runtime &amp; toolkit with a bundler, test runner, and npm-compatible package manager built in.",
+//   image: "https://bun.com/share_v4.png",
+//   type: "website",
+//   ...
+// }
+```