markdown-exit-s3-image 1.0.2 → 3.0.0

package/README.md

@@ -0,0 +1,60 @@
+# markdown-exit-s3-image
+
+A [markdown-exit](https://github.com/Efterklang/markdown-exit) plugin for S3 images with Bitiful CDN integration.
+
+## Features
+
+- **Progressive image loading** - Blurhash placeholders while images load
+- **Obsidian-style sizing** - `![alt|width]` or `![alt|widthxheight]` syntax
+- **Automatic srcset** - Responsive images with configurable widths
+- **Smart caching** - JSON-based metadata caching
+
+## Install
+
+```bash
+npm install markdown-exit-s3-image
+```
+
+## Usage
+
+```typescript
+import { MarkdownExit } from "markdown-exit";
+import { image } from "markdown-exit-s3-image";
+
+const md = new MarkdownExit({ html: true });
+md.use(image, {
+  bitiful_domains: ["demo.bitiful.com"],
+  progressive: { enable: true },
+});
+
+const html = await md.renderAsync(
+  "![girl](https://demo.bitiful.com/girl.jpeg)",
+);
+```
+
+## Options
+
+```typescript
+interface Options {
+  bitiful_domains: string[]; // Bitiful CDN domains
+  ignore_formats?: string[]; // Formats to skip (e.g., ["svg"])
+  progressive: {
+    enable: boolean; // Enable progressive loading
+    srcset_widths?: number[]; // Widths for srcset generation
+  };
+  cache_path?: string; // Path to cache file
+}
+```
+
+## Obsidian Sizing
+
+```markdown
+![alt|300]        <!-- width only -->
+![alt|640x480]    <!-- width x height -->
+```
+
+## License
+
+Credit: [Barbapapazes/markdown-exit-image: Erase images CLS automatically with this Markdown Exit plugin.](https://github.com/Barbapapazes/markdown-exit-image)
+
+MIT

package/dist/index.d.mts

@@ -1,7 +1,26 @@
-import { n as Options } from "./types-DK7PR0JE.mjs";
+import { Options } from "./types.mjs";
 import { MarkdownExit } from "markdown-exit";
 
 //#region src/index.d.ts
+/**
+ * Parsed result from Obsidian-style image alt text.
+ */
+interface ParsedImageAlt {
+  alt: string;
+  width?: number;
+  height?: number;
+}
+/**
+ * Parse Obsidian-style image dimensions from alt text.
+ * Supports formats: `![alt|width]`, `![alt|widthxheight]`
+ * Examples:
+ *   - `![image|300]` -> width: 300
+ *   - `![image|300x200]` -> width: 300, height: 200
+ *
+ * @param content The image alt text content
+ * @returns Parsed result with alt text and optional dimensions
+ */
+declare function parseObsidianImageAlt(content: string): ParsedImageAlt;
 declare function image(md: MarkdownExit, userOptions: Options): void;
 //#endregion
-export { image };
+export { image, parseObsidianImageAlt };

package/dist/index.mjs

@@ -1,6 +1,59 @@
-import { promises } from "node:fs";
+import sharp from "sharp";
 import { thumbHashToDataURL } from "thumbhash";
+import { promises } from "node:fs";
+
+//#region src/bitiful.ts
+/**
+* Bitiful CDN integration utilities
+*/
+/**
+* Check if URL belongs to Bitiful CDN.
+*/
+function isBitifulDomain(url, bitifulDomains) {
+	try {
+		const hostname = new URL(url).hostname;
+		return bitifulDomains.some((domain) => hostname.includes(domain));
+	} catch {
+		return false;
+	}
+}
+/**
+* Fetch dimension info from Bitiful API.
+*/
+async function getBitifulDimension(imageUrl) {
+	try {
+		const baseUrl = imageUrl.split("?")[0];
+		const response = await fetch(`${baseUrl}?fmt=info`);
+		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+		const { ImageWidth: width, ImageHeight: height } = await response.json();
+		if (typeof width === "number" && typeof height === "number") return {
+			width,
+			height
+		};
+		return null;
+	} catch (error) {
+		console.warn(`[Bitiful] Dimension error for ${imageUrl}:`, error instanceof Error ? error.message : String(error));
+		return null;
+	}
+}
+/**
+* Fetch thumbhash data URL from Bitiful API.
+*/
+async function getBitifulThumbhash(imageUrl) {
+	try {
+		const baseUrl = imageUrl.split("?")[0];
+		const response = await fetch(`${baseUrl}?fmt=thumbhash`);
+		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+		const base64String = await response.text();
+		const base64Data = thumbHashToDataURL(new Uint8Array(Buffer.from(base64String.trim(), "base64"))).replace(/^data:image\/\w+;base64,/, "");
+		return `data:image/webp;base64,${(await sharp(Buffer.from(base64Data, "base64")).webp({ quality: 80 }).toBuffer()).toString("base64")}`;
+	} catch (error) {
+		console.warn(`[Bitiful] Thumbhash error for ${imageUrl}:`, error instanceof Error ? error.message : String(error));
+		return null;
+	}
+}
 
+//#endregion
 //#region src/cache.ts
 var ImageCache = class {
 	cache = {};
@@ -108,58 +161,26 @@ function resolveOptions(userOptions = {}) {
 }
 
 //#endregion
-//#region src/bitiful.ts
-/**
-* Bitiful CDN integration utilities
-*/
-/**
-* Check if URL belongs to Bitiful CDN.
-*/
-function isBitifulDomain(url, bitifulDomains) {
-	try {
-		const hostname = new URL(url).hostname;
-		return bitifulDomains.some((domain) => hostname.includes(domain));
-	} catch {
-		return false;
-	}
-}
-/**
-* Fetch dimension info from Bitiful API.
-*/
-async function getBitifulDimension(imageUrl) {
-	try {
-		const baseUrl = imageUrl.split("?")[0];
-		const response = await fetch(`${baseUrl}?fmt=info`);
-		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-		const { ImageWidth: width, ImageHeight: height } = await response.json();
-		if (typeof width === "number" && typeof height === "number") return {
-			width,
-			height
-		};
-		return null;
-	} catch (error) {
-		console.warn(`[Bitiful] Dimension error for ${imageUrl}:`, error instanceof Error ? error.message : String(error));
-		return null;
-	}
-}
+//#region src/index.ts
 /**
-* Fetch thumbhash data URL from Bitiful API.
+* Parse Obsidian-style image dimensions from alt text.
+* Supports formats: `![alt|width]`, `![alt|widthxheight]`
+* Examples:
+*   - `![image|300]` -> width: 300
+*   - `![image|300x200]` -> width: 300, height: 200
+*
+* @param content The image alt text content
+* @returns Parsed result with alt text and optional dimensions
 */
-async function getBitifulThumbhash(imageUrl) {
-	try {
-		const baseUrl = imageUrl.split("?")[0];
-		const response = await fetch(`${baseUrl}?fmt=thumbhash`);
-		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-		const base64String = await response.text();
-		return thumbHashToDataURL(new Uint8Array(Buffer.from(base64String.trim(), "base64")));
-	} catch (error) {
-		console.warn(`[Bitiful] Thumbhash error for ${imageUrl}:`, error instanceof Error ? error.message : String(error));
-		return null;
-	}
+function parseObsidianImageAlt(content) {
+	const match = content.trim().match(/^(.*?)\|(\d+)(?:x(\d+))?$/);
+	if (!match) return { alt: content };
+	return {
+		alt: match[1].trim(),
+		width: parseInt(match[2], 10),
+		height: match[3] ? parseInt(match[3], 10) : void 0
+	};
 }
-
-//#endregion
-//#region src/index.ts
 /**
 * Check if file format should be ignored based on URL extension.
 */
@@ -169,24 +190,29 @@ function shouldIgnoreFormat(url, formats) {
 }
 function image(md, userOptions) {
 	const options = resolveOptions(userOptions);
-	if (!options.progressive.enable) return;
 	const cachePath = options.cache_path;
-	const cache = cachePath ? new ImageCache(cachePath) : null;
-	if (cache) cache.load().catch((err) => {
-		console.error("[ImageCache] Failed to load cache:", err);
-	});
-	process.once("beforeExit", () => {
-		if (cache) cache.save();
-	});
+	const cache = cachePath && options.progressive.enable ? new ImageCache(cachePath) : null;
+	if (cache) {
+		cache.load().catch((err) => {
+			console.error("[ImageCache] Failed to load cache:", err);
+		});
+		process.once("beforeExit", () => {
+			cache.save();
+		});
+	}
 	const imageRule = md.renderer.rules.image;
 	if (!imageRule) return;
 	md.renderer.rules.image = async (tokens, idx, info, env, self) => {
 		const token = tokens[idx];
 		const src = token.attrGet("src");
-		if (!src || !src.startsWith("http") || !isBitifulDomain(src, options.bitiful_domains) || shouldIgnoreFormat(src, options.ignore_formats) || process.env.NODE_ENV == "development") return imageRule(tokens, idx, info, env, self);
+		const parsedAlt = parseObsidianImageAlt(token.content);
+		if (!(options.progressive.enable && src && src.startsWith("http") && isBitifulDomain(src, options.bitiful_domains) && !shouldIgnoreFormat(src, options.ignore_formats) && process.env.NODE_ENV !== "development")) {
+			if (parsedAlt.width) return applyDimensionToHTML(await imageRule(tokens, idx, info, env, self), parsedAlt.width, parsedAlt.height);
+			return imageRule(tokens, idx, info, env, self);
+		}
 		if (cache) {
 			const cached = cache.get(src);
-			if (cached) return buildImageHTML(token.content, src, options, cached.width, cached.height, cached.dataURL);
+			if (cached) return buildImageHTML(parsedAlt, src, options, cached.width, cached.height, cached.dataURL);
 		}
 		let width;
 		let height;
@@ -204,25 +230,39 @@ function image(md, userOptions) {
 			height,
 			dataURL: placeholderUrl
 		});
-		return buildImageHTML(token.content, src, options, width, height, placeholderUrl);
+		return buildImageHTML(parsedAlt, src, options, width, height, placeholderUrl);
 	};
 }
+/**
+* Apply user-specified dimensions to existing HTML img tag.
+*/
+function applyDimensionToHTML(html, width, height) {
+	if (!width) return html;
+	let style = `max-width: ${width}px; width: ${width}px;`;
+	if (height) style += ` height: ${height}px;`;
+	if (html.includes("<img")) return html.replace(/<img\s/, `<img style="${style}" `);
+	return html;
+}
 function generateSrcset(src, width, srcsetWidths) {
 	const validWidths = srcsetWidths.filter((w) => w < width).concat(width);
 	return Array.from(new Set(validWidths)).sort((a, b) => a - b).map((w) => {
 		return `${w === width ? src : src.includes("?") ? `${src}&w=${w}` : `${src}?w=${w}`} ${w}w`;
 	}).join(", ");
 }
-function buildImageHTML(alt, src, options, width, height, dataURL) {
-	const srcset = generateSrcset(src, width, options.progressive.srcset_widths);
+function buildImageHTML(parsedAlt, src, options, originalWidth, originalHeight, dataURL) {
+	const displayWidth = parsedAlt.width || originalWidth;
+	const displayHeight = parsedAlt.height;
+	const srcset = generateSrcset(src, originalWidth, options.progressive.srcset_widths);
 	const mainImgAttrs = [
 		`src="${src}"`,
-		`alt="${alt}"`,
+		`alt="${parsedAlt.alt}"`,
 		`srcset="${srcset}"`,
 		`loading="lazy" decoding="async"`,
 		`style="width: 100%; height: 100%; object-fit: cover; opacity: 0; transition: opacity 0.6s ease-in-out;"`,
 		`onload="this.style.opacity=1; setTimeout(() => { this.parentElement.style.backgroundImage='none'; }, 600);"`
 	].filter(Boolean).join(" ");
+	const aspectWidth = displayWidth;
+	const aspectHeight = displayHeight || Math.round(originalHeight / originalWidth * displayWidth);
 	/**
 	* 3. 返回包装后的 HTML
 	* - 只有当有 dataURL 时才包装 div
@@ -232,11 +272,11 @@ function buildImageHTML(alt, src, options, width, height, dataURL) {
 			position: relative;
 			overflow: hidden;
 			width: 100%;
-			max-width: ${width}px;
+			max-width: ${displayWidth}px;
 			background-image: url('${dataURL}');
 			background-size: cover;
 			background-repeat: no-repeat;
-			aspect-ratio: ${width} / ${height};
+			aspect-ratio: ${aspectWidth} / ${aspectHeight};
 		">
 			<img ${mainImgAttrs}>
 		</div>`;
@@ -244,4 +284,4 @@ function buildImageHTML(alt, src, options, width, height, dataURL) {
 }
 
 //#endregion
-export { image };
+export { image, parseObsidianImageAlt };

package/dist/types.d.mts

@@ -1,2 +1,62 @@
-import { i as ResolvedOptions, n as Options, r as ProgressiveOptions, t as CachePathOption } from "./types-DK7PR0JE.mjs";
+//#region src/types.d.ts
+type CachePathOption = string | null;
+/**
+ * Options controlling progressive image loading.
+ */
+interface ProgressiveOptions {
+  /**
+   * Enable or disable progressive image loading.
+   * @default true
+   */
+  enable?: boolean;
+  /**
+   * An array of widths to generate for the srcset attribute.
+   * @default [400, 600, 800, 1200, 2000, 3000]
+   */
+  srcset_widths?: number[];
+  /**
+   * Optional value for the sizes attribute.
+   * @example "(max-width: 800px) 100vw, 800px"
+   */
+  sizes?: string;
+}
+/**
+ * Configuration options consumed by the plugin.
+ */
+interface Options {
+  /**
+   * Options for progressive image generation.
+   */
+  progressive?: ProgressiveOptions;
+  /**
+   * Domains that support Bitiful API for thumbhash and info.
+   * @default ["assets.vluv.space", "s3.bitiful.net", "bitiful.com"]
+   */
+  bitiful_domains?: string[];
+  /**
+   * Array of file format extensions to ignore (case-insensitive).
+   * @default ["svg"]
+   * @example ["svg", "gif"]
+   */
+  ignore_formats?: string[];
+  /**
+   * Path to the cache file. When unset, caching is disabled.
+   * @default null
+   * @example ".cache/thumbhash-cache.json"
+   */
+  cache_path?: CachePathOption;
+}
+/**
+ * Fully resolved options with defaults applied.
+ */
+interface ResolvedOptions extends Options {
+  progressive: ProgressiveOptions & {
+    enable: boolean;
+    srcset_widths: number[];
+  };
+  bitiful_domains: string[];
+  ignore_formats: string[];
+  cache_path: CachePathOption;
+}
+//#endregion
 export { CachePathOption, Options, ProgressiveOptions, ResolvedOptions };

package/package.json

@@ -2,7 +2,7 @@
   "name": "markdown-exit-s3-image",
   "type": "module",
   "author": "GnixAij",
-  "version": "1.0.2",
+  "version": "3.0.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -22,7 +22,8 @@
   "main": "dist/index.mjs",
   "types": "dist/index.d.mts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "engines": {
     "node": ">=20"
@@ -33,15 +34,16 @@
     "test:clean": "rm -f test/cache.json test/output.html"
   },
   "peerDependencies": {
-    "markdown-exit": "1.0.0-beta.6"
+    "markdown-exit": "1.0.0-beta.7"
   },
   "devDependencies": {
     "@tsconfig/node20": "^20.1.8",
-    "@types/node": "^24.10.1",
-    "tsdown": "^0.16.6",
+    "@types/node": "^25.1.0",
+    "tsdown": "^0.20.1",
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "sharp": "^0.34.5",
     "thumbhash": "^0.1.1"
   }
 }

package/dist/types-DK7PR0JE.d.mts

@@ -1,62 +0,0 @@
-//#region src/types.d.ts
-type CachePathOption = string | null;
-/**
- * Options controlling progressive image loading.
- */
-interface ProgressiveOptions {
-  /**
-   * Enable or disable progressive image loading.
-   * @default true
-   */
-  enable?: boolean;
-  /**
-   * An array of widths to generate for the srcset attribute.
-   * @default [400, 600, 800, 1200, 2000, 3000]
-   */
-  srcset_widths?: number[];
-  /**
-   * Optional value for the sizes attribute.
-   * @example "(max-width: 800px) 100vw, 800px"
-   */
-  sizes?: string;
-}
-/**
- * Configuration options consumed by the plugin.
- */
-interface Options {
-  /**
-   * Options for progressive image generation.
-   */
-  progressive?: ProgressiveOptions;
-  /**
-   * Domains that support Bitiful API for thumbhash and info.
-   * @default ["assets.vluv.space", "s3.bitiful.net", "bitiful.com"]
-   */
-  bitiful_domains?: string[];
-  /**
-   * Array of file format extensions to ignore (case-insensitive).
-   * @default ["svg"]
-   * @example ["svg", "gif"]
-   */
-  ignore_formats?: string[];
-  /**
-   * Path to the cache file. When unset, caching is disabled.
-   * @default null
-   * @example ".cache/thumbhash-cache.json"
-   */
-  cache_path?: CachePathOption;
-}
-/**
- * Fully resolved options with defaults applied.
- */
-interface ResolvedOptions extends Options {
-  progressive: ProgressiveOptions & {
-    enable: boolean;
-    srcset_widths: number[];
-  };
-  bitiful_domains: string[];
-  ignore_formats: string[];
-  cache_path: CachePathOption;
-}
-//#endregion
-export { ResolvedOptions as i, Options as n, ProgressiveOptions as r, CachePathOption as t };