perf: improve Core Web Vitals across iot-hub, pricing, blog, and docs

astro.config.ts

@@ -6,6 +6,7 @@ import { redirects } from './astro.redirects';
 import { sidebar } from './astro.sidebar';
 import { devServerFileWatcher } from './config/integrations/dev-server-file-watcher';
 import { sitemap } from './config/integrations/sitemap';
+import { rehypeBlogImages } from './config/plugins/rehype-blog-images';
 import { rehypeMdxIncludeHeadings } from './config/plugins/rehype-mdx-include-headings';
 import { rehypeTasklistEnhancer } from './config/plugins/rehype-tasklist-enhancer';
 import { PROD_ORIGIN } from './src/consts';
@@ -150,7 +151,7 @@ export default defineConfig({
             // @ts-expect-error — `remark-smartypants` type is not matching Astro's for some reason even though they both use unified's `Plugin` type
             [remarkSmartypants, { dashes: false }],
         ],
-        rehypePlugins: [rehypeSlug, rehypeTasklistEnhancer(), rehypeMdxIncludeHeadings()],
+        rehypePlugins: [rehypeSlug, rehypeTasklistEnhancer(), rehypeMdxIncludeHeadings(), rehypeBlogImages()],
     },
     image: {
         domains: ['avatars.githubusercontent.com'],

config/plugins/rehype-blog-images.ts

@@ -0,0 +1,97 @@
+import { join } from 'node:path';
+import type { Root } from 'hast';
+import sharp from 'sharp';
+import type { Plugin, Transformer } from 'unified';
+import { visit } from 'unist-util-visit';
+
+/**
+ * Rehype plugin for blog-post body images (scoped to `src/content/blog/`).
+ *
+ * Markdown images render as bare `<img>` tags with no dimensions and eager
+ * loading. This plugin:
+ *
+ * 1. Injects intrinsic `width`/`height` (read from the file in `public/`) so
+ *    the browser reserves layout space before the image downloads.
+ * 2. Keeps the first body image eager (it is the usual LCP candidate) and
+ *    lazy-loads every following image; all get `decoding="async"`.
+ *
+ * Images that already declare `loading`, `width`, or `height` are left as
+ * authored. External URLs and unresolvable files are skipped gracefully.
+ */
+
+interface Dims {
+	width: number;
+	height: number;
+}
+
+// Module-level cache: many posts reuse images, and metadata reads repeat
+// across dozens of posts on every build. `null` marks a failed read so broken
+// paths aren't retried per occurrence. The cache is never invalidated, so in
+// `pnpm dev` an edited image serves stale width/height until a server restart.
+const dimsCache = new Map<string, Dims | null>();
+
+async function readDims(absPath: string): Promise<Dims | null> {
+	const cached = dimsCache.get(absPath);
+	if (cached !== undefined) return cached;
+	let dims: Dims | null = null;
+	try {
+		const meta = await sharp(absPath).metadata();
+		if (meta.width && meta.height) dims = { width: meta.width, height: meta.height };
+	} catch {
+		// Missing or unreadable file — leave dimensions off, keep the attrs.
+	}
+	dimsCache.set(absPath, dims);
+	return dims;
+}
+
+export function rehypeBlogImages(): Plugin<[], Root> {
+	const transformer: Transformer<Root> = async (tree, file) => {
+		const sourcePath = (file.path ?? file.history?.[0] ?? '').replaceAll('\\', '/');
+		if (!sourcePath.includes('/src/content/blog/')) return;
+
+		// Collect in document order first; async work inside a visitor is unsafe.
+		const images: { properties: Record<string, unknown> }[] = [];
+		visit(tree, 'element', (node) => {
+			if (node.tagName !== 'img') return;
+			node.properties ??= {};
+			images.push(node as { properties: Record<string, unknown> });
+		});
+
+		let isFirst = true;
+		for (const img of images) {
+			const props = img.properties;
+			const first = isFirst;
+			isFirst = false;
+
+			// Respect explicitly authored loading behavior.
+			if (props.loading == null) {
+				props.loading = first ? 'eager' : 'lazy';
+				props.decoding ??= 'async';
+			}
+
+			const src = typeof props.src === 'string' ? props.src : '';
+			// Only local, root-relative assets ('/images/…', not '//host/…').
+			if (!src.startsWith('/') || src.startsWith('//')) continue;
+			if (props.width != null || props.height != null) continue;
+
+			// Malformed percent-encoding (a literal `%` in a filename) makes
+			// decodeURIComponent throw — degrade to skipping dimensions, like
+			// every other failure path here.
+			let cleanPath: string;
+			try {
+				cleanPath = decodeURIComponent(src.split(/[?#]/)[0] ?? '');
+			} catch {
+				continue;
+			}
+			const dims = await readDims(join(process.cwd(), 'public', cleanPath));
+			if (dims) {
+				props.width = dims.width;
+				props.height = dims.height;
+			}
+		}
+	};
+
+	return function attacher() {
+		return transformer;
+	};
+}

package.json

@@ -6,9 +6,9 @@
   "scripts": {
     "dev": "astro dev",
     "start": "astro dev",
-    "build": "NODE_OPTIONS=--max-old-space-size=8192 astro build",
-    "build:fast": "SKIP_OG=true NODE_OPTIONS=--max-old-space-size=8192 astro build",
-    "build:linkcheck": "SKIP_OG=true SKIP_LLMS=true SKIP_IMG=true NODE_OPTIONS=--max-old-space-size=8192 astro build",
+    "build": "node ./scripts/generate-nav-sprite.mjs && NODE_OPTIONS=--max-old-space-size=8192 astro build",
+    "build:fast": "node ./scripts/generate-nav-sprite.mjs && SKIP_OG=true NODE_OPTIONS=--max-old-space-size=8192 astro build",
+    "build:linkcheck": "node ./scripts/generate-nav-sprite.mjs && SKIP_OG=true SKIP_LLMS=true SKIP_IMG=true NODE_OPTIONS=--max-old-space-size=8192 astro build",
     "preview": "astro preview",
     "check": "astro check",
     "format": "pnpm run format:code",
@@ -23,7 +23,8 @@
     "lint:redirects": "node --experimental-transform-types ./scripts/check-redirect-chains.ts",
     "netlify:build": "pnpm ${NETLIFY_BUILD_SCRIPT:-build}",
     "lunaria:build": "node --experimental-transform-types ./scripts/lunaria.mts",
-    "generate:redirects": "node --experimental-transform-types ./scripts/generate-redirects.ts"
+    "generate:redirects": "node --experimental-transform-types ./scripts/generate-redirects.ts",
+    "generate:nav-sprite": "node ./scripts/generate-nav-sprite.mjs"
   },
   "devDependencies": {
     "@actions/core": "^1.11.1",