rehype-og-card 3.1.16 → 4.0.0

package/README.md

@@ -2,20 +2,20 @@
 
 Rehype plugin to convert text links to link cards inspired by [remark-link-card](https://github.com/gladevise/remark-link-card). Bare links are converted to link cards, but not links in lists or non-bare links.
 
-| Features                                       |                                     remark-link-card                                      | rehype-og-card |
-| :--------------------------------------------- | :---------------------------------------------------------------------------------------: | :------------: |
-| Plugin type                                    |                                          Remark                                           |     Rehype     |
-| TypeScript support                             |                                             ❌                                             |       ✅        |
-| Convert bare links to link cards               |                                             ✅                                             |       ✅        |
-| Shorten URLs displayed on link cards           |                                             ✅                                             |       ✅        |
-| Server-side cache for images                   |                                             ✅                                             |       ✅        |
-| Cache images with long URLs                    | ❌ ([implemented](https://github.com/gladevise/remark-link-card/pull/16) but not released) |       ✅        |
-| Build cache for Open Graph metadata and images |                                             ❌                                             |       ✅        |
-| Exclude links in lists from conversion         |                                             ❌                                             |       ✅        |
-| Exclude specific domains from conversion       |                                             ❌                                             |       ✅        |
-| Lazy loading images                            |                                             ❌                                             |       ✅        |
-| Async decoding images                          |                                             ❌                                             |       ✅        |
-| Customize the crawler's user agent string      |                                             ❌                                             |       ✅        |
+| Features                                       |                                      remark-link-card                                      | rehype-og-card |
+| :--------------------------------------------- | :----------------------------------------------------------------------------------------: | :------------: |
+| Plugin type                                    |                                           Remark                                           |     Rehype     |
+| TypeScript support                             |                                             ❌                                             |       ✅       |
+| Convert bare links to link cards               |                                             ✅                                             |       ✅       |
+| Shorten URLs displayed on link cards           |                                             ✅                                             |       ✅       |
+| Server-side cache for images                   |                                             ✅                                             |       ✅       |
+| Cache images with long URLs                    | ❌ ([implemented](https://github.com/gladevise/remark-link-card/pull/16) but not released) |       ✅       |
+| Build cache for Open Graph metadata and images |                                             ❌                                             |       ✅       |
+| Exclude links in lists from conversion         |                                             ❌                                             |       ✅       |
+| Exclude specific domains from conversion       |                                             ❌                                             |       ✅       |
+| Lazy loading images                            |                                             ❌                                             |       ✅       |
+| Async decoding images                          |                                             ❌                                             |       ✅       |
+| Customize the crawler's user agent string      |                                             ❌                                             |       ✅       |
 
 ## Installation
 
@@ -113,7 +113,7 @@ Whether to cache the OG metadata and images for the next build. `buildCache` opt
 Path to save the build cache. For Astro projects, specify the `./node_modules/.astro` directory.
 
 - Type: `string`
-- Default: `"./.cache/og-card"`
+- Default: `"./node_modules/.cache"`
 
 ### `buildCacheMaxAge`
 
@@ -200,3 +200,24 @@ Whether to shorten the displayed URL.
 
 - Type: `boolean`
 - Default: `true`
+
+### `svgHandling`
+
+How to handle SVG OG images and favicons when `serverCache` is enabled.
+
+- Type: `"omit" | "preserve" | "rasterize"`
+- Default: `"rasterize"`
+
+| Value         | Behavior                                                               |
+| ------------- | ---------------------------------------------------------------------- |
+| `"omit"`      | Treat SVG as a missing image. The rest of the card is still generated. |
+| `"preserve"`  | Save the original SVG without modification.                            |
+| `"rasterize"` | Convert SVG to a PNG. Omit the image if conversion fails.              |
+
+If the `"rasterize"` option is selected, external resources referenced by the target SVG image will not be loaded. If `serverCache: false` is set, the image URL remains unchanged in the output, and the `svgHandling` settings are not applied.
+
+#### Security Considerations
+
+rehype-og-card embeds images using `<img>` tags. If `svgHandling: "preserve"` is selected, there is a risk that any scripts contained within an embedded SVG file could be executed if a user opens that file directly. It is recommended to clear the server cache after switching the `svgHandling` mode.
+
+When `serverCache: true` is enabled, your server controls the response headers for cached images. Please ensure that the correct `Content-Type` and `X-Content-Type-Options: nosniff` headers are included when serving these images.

package/dist/index.js

@@ -1,9 +1,11 @@
 import { convertTextToAnchorElement, createOGCard, isAnchorElement, isTextNode } from "./util/hast.js";
-import { checkFileExistsSync, createDirectorySync } from "./util/file.js";
 import { downloadImage, getOGData, isValidURL } from "./util/network.js";
+import { join, posix } from "node:path";
 import { restoreBuildCache, restoreOGDataBuildCache, saveBuildCacheFile, saveOGDataBuildCache } from "./util/cache.js";
+import { createDirectorySync } from "./util/file.js";
+import { existsSync } from "node:fs";
 import { isElement } from "hast-util-is-element";
-import path from "path";
+// oxlint-disable-next-line import/max-dependencies
 import { visitParents } from "unist-util-visit-parents";
 // oxlint-disable-next-line no-magic-numbers
 const ONE_DAY_MS = 24 * 60 * 60 * 1000;
@@ -23,7 +25,8 @@ const DEFAULT_OPTIONS = {
     serverCache: true,
     serverCacheMaxAge: DEFAULT_CACHE_MAX_AGE_MS,
     serverCachePath: "./public",
-    shortenURL: true
+    shortenURL: true,
+    svgHandling: "rasterize"
 };
 /**
  * Rehype plugin to create OG card from bare links.
@@ -39,9 +42,9 @@ const rehypeOGCard = (options) => {
     if (mergedOptions.buildCache && !mergedOptions.serverCache) {
         throw new Error("[rehype-og-card] `buildCache` option requires `serverCache` option to be enabled.");
     }
-    mergedOptions.serverCachePath = path.posix.join(mergedOptions.serverCachePath, "./rehype-og-card/");
-    mergedOptions.buildCachePath = path.posix.join(mergedOptions.buildCachePath, "./rehype-og-card/");
-    const buildCacheExists = checkFileExistsSync(mergedOptions.buildCachePath);
+    mergedOptions.serverCachePath = posix.join(mergedOptions.serverCachePath, "./rehype-og-card/");
+    mergedOptions.buildCachePath = posix.join(mergedOptions.buildCachePath, "./rehype-og-card/");
+    const buildCacheExists = existsSync(mergedOptions.buildCachePath);
     if (mergedOptions.buildCache) {
         if (buildCacheExists) {
             restoreBuildCache(mergedOptions.buildCachePath, mergedOptions.serverCachePath, mergedOptions.buildCacheMaxAge);
@@ -105,22 +108,23 @@ const rehypeOGCard = (options) => {
                     if (!OGData)
                         return;
                     if (mergedOptions.buildCache) {
-                        void saveOGDataBuildCache(anchorNode.properties.href, OGData, mergedOptions.buildCachePath);
+                        await saveOGDataBuildCache(anchorNode.properties.href, OGData, mergedOptions.buildCachePath);
                     }
                 }
                 if (OGData.OGImageURL && mergedOptions.serverCache) {
                     const filename = await downloadImage({
                         cacheMaxAge: mergedOptions.serverCacheMaxAge,
                         directory: mergedOptions.serverCachePath,
+                        svgHandling: mergedOptions.svgHandling,
                         url: OGData.OGImageURL,
                         userAgent: mergedOptions.crawlerUserAgent
                     });
                     if (filename) {
-                        OGData.OGImageURL = path.posix.join("/rehype-og-card", filename);
+                        OGData.OGImageURL = posix.join("/rehype-og-card", filename);
                         if (mergedOptions.buildCache) {
-                            const downloadedFilePath = path.join(mergedOptions.serverCachePath, filename);
-                            const buildCachePath = path.join(mergedOptions.buildCachePath, filename);
-                            void saveBuildCacheFile(downloadedFilePath, buildCachePath);
+                            const downloadedFilePath = join(mergedOptions.serverCachePath, filename);
+                            const buildCachePath = join(mergedOptions.buildCachePath, filename);
+                            await saveBuildCacheFile(downloadedFilePath, buildCachePath);
                         }
                     }
                     else {
@@ -131,15 +135,16 @@ const rehypeOGCard = (options) => {
                     const filename = await downloadImage({
                         cacheMaxAge: mergedOptions.serverCacheMaxAge,
                         directory: mergedOptions.serverCachePath,
+                        svgHandling: mergedOptions.svgHandling,
                         url: OGData.faviconURL,
                         userAgent: mergedOptions.crawlerUserAgent
                     });
                     if (filename) {
-                        OGData.faviconURL = path.posix.join("/rehype-og-card", filename);
+                        OGData.faviconURL = posix.join("/rehype-og-card", filename);
                         if (mergedOptions.buildCache) {
-                            const downloadedFilePath = path.join(mergedOptions.serverCachePath, filename);
-                            const buildCachePath = path.join(mergedOptions.buildCachePath, filename);
-                            void saveBuildCacheFile(downloadedFilePath, buildCachePath);
+                            const downloadedFilePath = join(mergedOptions.serverCachePath, filename);
+                            const buildCachePath = join(mergedOptions.buildCachePath, filename);
+                            await saveBuildCacheFile(downloadedFilePath, buildCachePath);
                         }
                     }
                     else {

package/dist/types.d.ts

@@ -39,6 +39,18 @@ interface RehypeOGCardOptions {
      * @default true
      */
     serverCache?: boolean;
+    /**
+     * How to handle SVG OG images and favicons when server caching is enabled.
+     *
+     * - `"omit"`: Treat SVG as a missing image. The rest of the card is still generated.
+     * - `"preserve"`: Save the original SVG without modification.
+     * - `"rasterize"`: Convert SVG to a PNG. Omit the image if conversion fails.
+     *
+     * If the `"rasterize"` option is selected, external resources referenced by the target SVG image will not be loaded.
+     * If `serverCache: false` is set, the image URL remains unchanged in the output, and the `svgHandling` settings are not applied.
+     * @default "rasterize"
+     */
+    svgHandling?: "omit" | "preserve" | "rasterize";
     /**
      * Path to save the server cache.
      * Specify the directory whose contents will be copied to the root.

package/dist/util/cache.js

@@ -1,10 +1,10 @@
 /* oxlint-disable max-lines */
 import { parseCacheIndex } from "../types.js";
 import { checkFileExists, generateFilename } from "./file.js";
-import fs from "fs/promises";
-import fsSync from "fs";
-import path from "path";
-import { setTimeout } from "timers/promises";
+import { closeSync, cpSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { copyFile, mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { setTimeout } from "node:timers/promises";
 import { type } from "arktype";
 /**
  * Check whether a cache entry is expired.
@@ -60,10 +60,10 @@ const acquireCacheIndexLock = async (directory) => {
      */
     const tryAcquire = async (attempt) => {
         try {
-            const handle = await fs.open(lockPath, "wx");
+            const handle = await open(lockPath, "wx");
             await handle.close();
             return async () => {
-                await fs.rm(lockPath, { force: true });
+                await rm(lockPath, { force: true });
             };
         }
         catch (error) {
@@ -96,10 +96,10 @@ const acquireCacheIndexLockSync = (directory) => {
      */
     const tryAcquire = (attempt) => {
         try {
-            const fd = fsSync.openSync(lockPath, "wx");
-            fsSync.closeSync(fd);
+            const fd = openSync(lockPath, "wx");
+            closeSync(fd);
             return () => {
-                fsSync.rmSync(lockPath, { force: true });
+                rmSync(lockPath, { force: true });
             };
         }
         catch (error) {
@@ -122,7 +122,7 @@ const acquireCacheIndexLockSync = (directory) => {
 const readCacheIndexSync = (directory) => {
     const indexPath = getCacheIndexPath(directory);
     try {
-        const raw = fsSync.readFileSync(indexPath, "utf-8");
+        const raw = readFileSync(indexPath, "utf-8");
         const validated = parseCacheIndex(raw);
         if (validated instanceof type.errors)
             return {};
@@ -142,8 +142,8 @@ const writeCacheIndexSync = (directory, index) => {
     const tempPath = `${indexPath}.tmp`;
     const releaseLock = acquireCacheIndexLockSync(directory);
     try {
-        fsSync.writeFileSync(tempPath, JSON.stringify(index));
-        fsSync.renameSync(tempPath, indexPath);
+        writeFileSync(tempPath, JSON.stringify(index));
+        renameSync(tempPath, indexPath);
     }
     finally {
         releaseLock?.();
@@ -160,7 +160,7 @@ const readCacheIndex = async (directory) => {
     if (!exists)
         return {};
     try {
-        const raw = await fs.readFile(indexPath, "utf-8");
+        const raw = await readFile(indexPath, "utf-8");
         const validated = parseCacheIndex(raw);
         if (validated instanceof type.errors)
             return {};
@@ -180,8 +180,8 @@ const writeCacheIndex = async (directory, index) => {
     const tempPath = `${indexPath}.tmp`;
     const releaseLock = await acquireCacheIndexLock(directory);
     try {
-        await fs.writeFile(tempPath, JSON.stringify(index));
-        await fs.rename(tempPath, indexPath);
+        await writeFile(tempPath, JSON.stringify(index));
+        await rename(tempPath, indexPath);
     }
     finally {
         await releaseLock?.();
@@ -194,7 +194,7 @@ const writeCacheIndex = async (directory, index) => {
  */
 const removeCacheEntrySync = (directory, filename) => {
     const filePath = path.join(directory, filename);
-    fsSync.rmSync(filePath, { force: true });
+    rmSync(filePath, { force: true });
 };
 /**
  * Remove expired cache files synchronously.
@@ -205,11 +205,11 @@ const removeCacheEntrySync = (directory, filename) => {
 const pruneExpiredCacheFilesSync = (directory, maxAgeMs) => {
     if (maxAgeMs === false)
         return;
-    if (!fsSync.existsSync(directory))
+    if (!existsSync(directory))
         return;
     const index = readCacheIndexSync(directory);
     let indexUpdated = false;
-    const entries = fsSync.readdirSync(directory, { withFileTypes: true });
+    const entries = readdirSync(directory, { withFileTypes: true });
     for (const entry of entries) {
         const entryPath = path.join(directory, entry.name);
         if (entry.isDirectory()) {
@@ -222,19 +222,19 @@ const pruneExpiredCacheFilesSync = (directory, maxAgeMs) => {
             continue;
         if (entry.name.endsWith(".json")) {
             try {
-                const raw = fsSync.readFileSync(entryPath, "utf-8");
+                const raw = readFileSync(entryPath, "utf-8");
                 const data = JSON.parse(raw);
                 if (typeof data.cachedAt !== "number") {
-                    fsSync.rmSync(entryPath, { force: true });
+                    rmSync(entryPath, { force: true });
                     // oxlint-disable-next-line no-continue
                     continue;
                 }
                 if (isCacheExpired(data.cachedAt, maxAgeMs)) {
-                    fsSync.rmSync(entryPath, { force: true });
+                    rmSync(entryPath, { force: true });
                 }
             }
             catch {
-                fsSync.rmSync(entryPath, { force: true });
+                rmSync(entryPath, { force: true });
             }
             // oxlint-disable-next-line no-continue
             continue;
@@ -258,20 +258,15 @@ const pruneExpiredCacheFilesSync = (directory, maxAgeMs) => {
  */
 const saveBuildCacheFile = async (serverCachePath, buildCachePath) => {
     const serverCacheExists = await checkFileExists(serverCachePath);
-    const buildCacheExists = await checkFileExists(buildCachePath);
-    if (serverCacheExists && !buildCacheExists) {
-        await fs.copyFile(serverCachePath, buildCachePath);
-    }
-    const buildCacheExistsAfter = await checkFileExists(buildCachePath);
-    if (!buildCacheExistsAfter)
+    if (!serverCacheExists)
         return;
+    await copyFile(serverCachePath, buildCachePath);
     const serverDirectory = path.dirname(serverCachePath);
     const buildDirectory = path.dirname(buildCachePath);
     const filename = path.basename(buildCachePath);
     const serverIndex = readCacheIndexSync(serverDirectory);
-    const cachedAt = typeof serverIndex[filename]?.createdAt === "number" ? serverIndex[filename].createdAt : Date.now();
     const buildIndex = readCacheIndexSync(buildDirectory);
-    buildIndex[filename] = { createdAt: cachedAt };
+    buildIndex[filename] = { createdAt: serverIndex[filename]?.createdAt ?? Date.now() };
     writeCacheIndexSync(buildDirectory, buildIndex);
 };
 /**
@@ -281,13 +276,13 @@ const saveBuildCacheFile = async (serverCachePath, buildCachePath) => {
  * @param maxAgeMs Cache expiration time in milliseconds.
  */
 const restoreBuildCache = (buildCachePath, serverCachePath, maxAgeMs) => {
-    if (!fsSync.existsSync(buildCachePath))
+    if (!existsSync(buildCachePath))
         return;
     pruneExpiredCacheFilesSync(buildCachePath, maxAgeMs);
-    if (!fsSync.existsSync(serverCachePath)) {
-        fsSync.mkdirSync(serverCachePath, { recursive: true });
+    if (!existsSync(serverCachePath)) {
+        mkdirSync(serverCachePath, { recursive: true });
     }
-    fsSync.cpSync(buildCachePath, serverCachePath, { recursive: true });
+    cpSync(buildCachePath, serverCachePath, { recursive: true });
 };
 /**
  * Save OG data to build cache.
@@ -300,10 +295,10 @@ const saveOGDataBuildCache = async (url, OGData, buildCachePath) => {
     const savePath = `${path.join(buildCachePath, filename)}.json`;
     const cacheDirectoryExists = await checkFileExists(buildCachePath);
     if (!cacheDirectoryExists) {
-        await fs.mkdir(buildCachePath, { recursive: true });
+        await mkdir(buildCachePath, { recursive: true });
     }
     const payload = { ...OGData, cachedAt: Date.now() };
-    await fs.writeFile(savePath, JSON.stringify(payload));
+    await writeFile(savePath, JSON.stringify(payload));
 };
 /**
  * Restore OG data from build cache.
@@ -316,18 +311,18 @@ const restoreOGDataBuildCache = async (url, buildCachePath, maxAgeMs) => {
     const filename = generateFilename(url, false);
     const savePath = `${path.join(buildCachePath, filename)}.json`;
     try {
-        const data = await fs.readFile(savePath, "utf-8");
+        const data = await readFile(savePath, "utf-8");
         const parsed = JSON.parse(data);
         if (typeof parsed.cachedAt !== "number") {
             if (maxAgeMs === false) {
                 const { cachedAt: __, ...rest } = parsed;
                 return rest;
             }
-            await fs.rm(savePath, { force: true });
+            await rm(savePath, { force: true });
             return null;
         }
         if (isCacheExpired(parsed.cachedAt, maxAgeMs)) {
-            await fs.rm(savePath, { force: true });
+            await rm(savePath, { force: true });
             return null;
         }
         const { cachedAt: __, ...rest } = parsed;

package/dist/util/file.d.ts

@@ -4,12 +4,6 @@
  * @returns `true` if the file exists, `false` otherwise.
  */
 declare const checkFileExists: (filePath: string) => Promise<boolean>;
-/**
- * Check if the file exists.
- * @param filePath Path to check.
- * @returns `true` if the file exists, `false` otherwise.
- */
-declare const checkFileExistsSync: (filePath: string) => boolean;
 /**
  * Create directory.
  * @param dir Directory path.
@@ -28,4 +22,4 @@ declare const copyDirectory: (source: string, destination: string) => void;
  * @returns Generated filename.
  */
 declare const generateFilename: (url: string, extension?: boolean) => string;
-export { checkFileExists, checkFileExistsSync, createDirectorySync, copyDirectory, generateFilename };
+export { checkFileExists, createDirectorySync, copyDirectory, generateFilename };

package/dist/util/file.js

@@ -1,6 +1,7 @@
-import { createHash } from "crypto";
-import fs from "fs";
-import path from "path";
+import { cp, existsSync, mkdirSync } from "node:fs";
+import { access } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
 /**
  * Check if the file exists.
  * @param filePath Path to check.
@@ -8,36 +9,19 @@ import path from "path";
  */
 const checkFileExists = async (filePath) => {
     try {
-        await fs.promises.access(filePath);
+        await access(filePath);
         return true;
     }
     catch {
         return false;
     }
 };
-/**
- * Check if the file exists.
- * @param filePath Path to check.
- * @returns `true` if the file exists, `false` otherwise.
- */
-const checkFileExistsSync = (filePath) => {
-    let result = false;
-    fs.access(filePath, (error) => {
-        result = !error;
-    });
-    return result;
-};
 /**
  * Create directory.
  * @param dir Directory path.
  */
 const createDirectorySync = (dir) => {
-    fs.mkdir(dir, { recursive: true }, (error) => {
-        if (error) {
-            // oxlint-disable-next-line no-console
-            console.error("[rehype-og-card] Failed to copy files: ", error);
-        }
-    });
+    mkdirSync(dir, { recursive: true });
 };
 /**
  * Copy directory from source to destination.
@@ -45,14 +29,14 @@ const createDirectorySync = (dir) => {
  * @param destination Destination directory.
  */
 const copyDirectory = (source, destination) => {
-    const sourceExists = checkFileExistsSync(source);
+    const sourceExists = existsSync(source);
     if (!sourceExists)
         return;
-    const destinationExists = checkFileExistsSync(destination);
+    const destinationExists = existsSync(destination);
     if (!destinationExists) {
         createDirectorySync(destination);
     }
-    fs.cp(source, destination, { recursive: true }, (error) => {
+    cp(source, destination, { recursive: true }, (error) => {
         if (error) {
             // oxlint-disable-next-line no-console
             console.error("[rehype-og-card] Failed to copy files: ", error);
@@ -75,4 +59,4 @@ const generateFilename = (url, extension = true) => {
     const filename = extension ? hash + extensionString : hash;
     return filename;
 };
-export { checkFileExists, checkFileExistsSync, createDirectorySync, copyDirectory, generateFilename };
+export { checkFileExists, createDirectorySync, copyDirectory, generateFilename };

package/dist/util/network.d.ts

@@ -1,4 +1,4 @@
-import type { OGCardData } from "../types.js";
+import type { OGCardData, RehypeOGCardOptions } from "../types.js";
 /**
  * Check if the URL is valid.
  * @param url URL to check.
@@ -30,6 +30,11 @@ interface DownloadImageOptions {
      * Set to `false` to disable expiration.
      */
     cacheMaxAge: number | false;
+    /**
+     * How to handle SVG images.
+     * @default "rasterize"
+     */
+    svgHandling?: RehypeOGCardOptions["svgHandling"];
 }
 /**
  * Download image from given URL. If the image already exists, return the filename.

package/dist/util/network.js

@@ -1,8 +1,9 @@
 import { checkFileExists, generateFilename } from "./file.js";
 import { isCacheExpired, readCacheIndex, writeCacheIndex } from "./cache.js";
 import fetch from "node-fetch";
-import fs from "fs/promises";
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { rasterizeSVG } from "./svg.js";
 import scraper from "open-graph-scraper";
 /**
  * Check if the URL is valid.
@@ -67,6 +68,28 @@ const getOGData = async (url, userAgent) => {
         return null;
     }
 };
+/**
+ * Restore an unexpired cached image.
+ * @param options Image cache options.
+ * @param filenames Possible cached image filenames.
+ * @returns Cached filename, or `null` if no valid file exists.
+ */
+const restoreImageCache = async (options, filenames) => {
+    const index = await readCacheIndex(options.directory);
+    const cached = await Promise.all([...filenames].map(async (filename) => {
+        const cachedPath = path.join(options.directory, filename);
+        if (!(await checkFileExists(cachedPath)))
+            return null;
+        const cachedAt = index[filename]?.createdAt;
+        if (options.cacheMaxAge === false ||
+            (typeof cachedAt === "number" && !isCacheExpired(cachedAt, options.cacheMaxAge))) {
+            return filename;
+        }
+        await fs.rm(cachedPath, { force: true });
+        return null;
+    }));
+    return cached.find((filename) => filename !== null) ?? null;
+};
 /**
  * Download image from given URL. If the image already exists, return the filename.
  * @param options Options to download image.
@@ -80,26 +103,13 @@ const downloadImage = async (options) => {
         return null;
     }
     try {
-        const filename = generateFilename(options.url);
-        const savePath = path.posix.join(options.directory, filename);
-        // If the file already exists, return the filename.
-        const fileExists = await checkFileExists(savePath);
-        if (fileExists) {
-            if (options.cacheMaxAge === false)
-                return filename;
-            const index = await readCacheIndex(options.directory);
-            const entry = index[filename];
-            const cachedAt = entry?.createdAt;
-            const maxAge = options.cacheMaxAge;
-            if (typeof cachedAt === "number" && !isCacheExpired(cachedAt, maxAge))
-                return filename;
-            if (typeof entry !== "undefined") {
-                // oxlint-disable-next-line @typescript-eslint/no-dynamic-delete
-                delete index[filename];
-                await writeCacheIndex(options.directory, index);
-            }
-            await fs.rm(savePath, { force: true });
-        }
+        const svgHandling = options.svgHandling ?? "rasterize";
+        const stem = generateFilename(options.url, false);
+        let filename = generateFilename(options.url);
+        const candidates = new Set([filename, `${stem}.png`]);
+        const cachedFilename = await restoreImageCache(options, candidates);
+        if (cachedFilename)
+            return cachedFilename;
         const response = await fetch(options.url, {
             headers: {
                 "user-agent": options.userAgent
@@ -110,19 +120,25 @@ const downloadImage = async (options) => {
         if (!response.ok)
             return null;
         const contentType = response.headers.get("content-type");
-        const normalizedContentType = contentType?.split(";")[0]?.trim().toLowerCase();
-        if (!normalizedContentType?.startsWith("image/")) {
+        const normalizedContentType = contentType?.replace(/;.*/u, "").trim().toLowerCase();
+        const isSVG = normalizedContentType === "image/svg+xml" ||
+            [options.url, response.url].some((url) => path.extname(new URL(url).pathname).toLowerCase() === ".svg");
+        if (isSVG && svgHandling === "omit")
+            return null;
+        if (!isSVG && !normalizedContentType?.startsWith("image/")) {
             // oxlint-disable-next-line no-console
             console.error("[rehype-og-card] Invalid image content type:", contentType ?? "unknown", "for", options.url);
             return null;
         }
         const arrayBuffer = await response.arrayBuffer();
         const buffer = Buffer.from(arrayBuffer);
-        const saveDirectoryExists = await checkFileExists(options.directory);
-        if (!saveDirectoryExists) {
-            await fs.mkdir(options.directory, { recursive: true });
+        const shouldRasterize = isSVG && svgHandling === "rasterize";
+        const imageBuffer = shouldRasterize ? await rasterizeSVG(buffer) : buffer;
+        if (shouldRasterize) {
+            filename = `${stem}.png`;
         }
-        await fs.writeFile(savePath, buffer);
+        await fs.mkdir(options.directory, { recursive: true });
+        await fs.writeFile(path.join(options.directory, filename), imageBuffer);
         const cachedAt = Date.now();
         const index = await readCacheIndex(options.directory);
         index[filename] = { createdAt: cachedAt };

package/dist/util/svg.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Convert SVG to PNG without loading resources referenced by the SVG.
+ * @param buffer Downloaded SVG.
+ * @returns PNG within the link card image bounds.
+ */
+declare const rasterizeSVG: (buffer: Buffer) => Promise<Buffer>;
+export { rasterizeSVG };

package/dist/util/svg.js

@@ -0,0 +1,20 @@
+import sharp from "sharp";
+const MAX_WIDTH = 1200;
+const MAX_HEIGHT = 628;
+/**
+ * Convert SVG to PNG without loading resources referenced by the SVG.
+ * @param buffer Downloaded SVG.
+ * @returns PNG within the link card image bounds.
+ */
+const rasterizeSVG = async (buffer) => 
+// Buffer input leaves librsvg's base URL unset, preventing external file references.
+sharp(buffer)
+    .resize({
+    fit: "inside",
+    height: MAX_HEIGHT,
+    width: MAX_WIDTH,
+    withoutEnlargement: true
+})
+    .png()
+    .toBuffer();
+export { rasterizeSVG };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rehype-og-card",
-  "version": "3.1.16",
+  "version": "4.0.0",
   "description": "Rehype plugin to convert text links to link cards",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,7 +13,7 @@
   },
   "scripts": {
     "test": "vitest",
-    "lint": "oxlint ./src",
+    "lint": "oxlint src",
     "format": "prettier --write ./src/**/*",
     "format:check": "prettier --check ./src/**/*",
     "build": "tsc",
@@ -42,26 +42,27 @@
   "devDependencies": {
     "@changesets/changelog-github": "^1.0.1",
     "@changesets/cli": "^3.0.3",
-    "@robot-inventor/oxlint-config": "^0.4.0",
+    "@robot-inventor/oxlint-config": "^0.5.2",
     "@robot-inventor/tsconfig-base": "^7.2.0",
-    "@types/node": "^26.6.2",
+    "@types/node": "^26.6.5",
     "hast-util-to-html": "^9.0.5",
-    "oxlint": "^1.85.0",
-    "prettier": "^3.9.8",
+    "oxlint": "^1.89.0",
+    "prettier": "^3.9.10",
     "rehype-stringify": "^10.0.1",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "typescript": "^7.0.2",
     "unified": "^11.0.5",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.5"
   },
   "dependencies": {
     "@types/hast": "^3.0.5",
-    "arktype": "^2.2.3",
+    "arktype": "^2.2.9",
     "hast-util-is-element": "^3.0.0",
     "hastscript": "^9.0.1",
     "node-fetch": "^3.3.2",
     "open-graph-scraper": "^6.12.0",
+    "sharp": "^0.35.5",
     "unist-util-visit-parents": "^6.0.2"
   }
 }