@hutusi/amytis 1.13.0 → 1.15.0

package/public/next-image-export-optimizer-hashes.json

@@ -1,75 +1,16 @@
 {
-    "books/agentic-design-patterns/images/appendix-a/image1.png": "k8G1J92r2m-rIbN+EDXjtOtXL3Im9pfIF9E+N4gR6+o=",
-    "books/agentic-design-patterns/images/appendix-b/image1.png": "j7jY3StmUJFaDcCc37qmkMNApRPw-hqtxo6xGMEvvSI=",
-    "books/agentic-design-patterns/images/appendix-d/image1.png": "Jz-nZ-kZPaM1XYPAzWY8jJRrmZHH3TOZKMVX6hD-G0I=",
-    "books/agentic-design-patterns/images/appendix-d/image2.png": "flQCnHTEIqAftdXjvY3gwc+OYbcZDaqwr3rtxDU7PjE=",
-    "books/agentic-design-patterns/images/appendix-d/image3.png": "FPPSaVvnYJhlRplp25grIwI0+vmtc9NHl+6EcpXIAic=",
-    "books/agentic-design-patterns/images/appendix-d/image4.png": "TvxBNTKaZCho+W8eTm67fiYmSwDJzwj1AOOguIV+o04=",
-    "books/agentic-design-patterns/images/appendix-d/image5.png": "EPlVRP7VlPQqkF9fawSV43kQg7JKVsjy-dHLFH6LIBY=",
-    "books/agentic-design-patterns/images/appendix-d/image6.png": "s7zF5TgNEQfvkakIHhdHXQ7S5imi4+AOtaD+PG7w0xM=",
-    "books/agentic-design-patterns/images/appendix-g/image1.png": "r-KvQvaqGSwZrN+30Dg6KZx4dEUzKZwPJ+eezw-KH70=",
-    "books/agentic-design-patterns/images/chapter-1/image1.png": "yfUwbocNorvSCdvdxTqQZmmiZsoRWbsn9iby6iKJYFQ=",
-    "books/agentic-design-patterns/images/chapter-1/image2.png": "pisZVOmTdn1Y+qs7sAqTqn04BeR3UngCd17kApWgehk=",
-    "books/agentic-design-patterns/images/chapter-10/image1.png": "aKJwlDxhZkAglLFTGgT8qpjIAlNQ5gV5ovCAnBjwx7M=",
-    "books/agentic-design-patterns/images/chapter-11/image1.png": "n9ou0BpTuPt3kcTEnCJEQRnMKFd9lI666DBxWDJzd3A=",
-    "books/agentic-design-patterns/images/chapter-11/image2.png": "30uw9sGMGnE+jyt++vVURBUQNXe5ty+8i8h+PMw4GfM=",
-    "books/agentic-design-patterns/images/chapter-12/image1.png": "4e4AD2MJFSB3GByGxGVr4VCQ4H+eYkR3oq39KuZhzw8=",
-    "books/agentic-design-patterns/images/chapter-12/image2.png": "1MyjXYovLBeKJmUGnUnx38T-UgkhRfV5opzOcP+OEdw=",
-    "books/agentic-design-patterns/images/chapter-13/image1.png": "PB3msIGhOmq1Oyrv6ubGJZJCvO+dD7XNxZiw5Ck-834=",
-    "books/agentic-design-patterns/images/chapter-14/image1.png": "p-06-D2Vp2x7HMXwmkTNLneS9sjsfSvmTsLTlVUjY5k=",
-    "books/agentic-design-patterns/images/chapter-14/image2.png": "XvXKYbuijYChfq4+MlZYXLBpxTg11ddJ0AFnzvntLPw=",
-    "books/agentic-design-patterns/images/chapter-14/image3.png": "YhmOWyJo3pDKVbKW7RMgTbNrbmsE89RkmaJ2z76vhos=",
-    "books/agentic-design-patterns/images/chapter-14/image4.png": "QBNe+Wt65qdLfkC5MJqaiNBJGMa-DbCm3gCOqfB7ehk=",
-    "books/agentic-design-patterns/images/chapter-15/image1.png": "I90CSqCb8g-h1F0a3sDusDC+LmHdjJTBBk6iFw4ZnJY=",
-    "books/agentic-design-patterns/images/chapter-15/image2.png": "HaxOSZ1f67BhEPa3KXtYAlK0cNm3G4H24dnLXpcgyA0=",
-    "books/agentic-design-patterns/images/chapter-16/image1.png": "Blc0vDhlie6PM3f6QSUX3argbfezTNDOLYhmT9uuS6E=",
-    "books/agentic-design-patterns/images/chapter-16/image2.png": "9-KZ0VOekDwFVL1dEzB9aleyCYF+WU6bx1h3aVNoOAM=",
-    "books/agentic-design-patterns/images/chapter-17/image1.png": "jjGM2Ll5bdszl9xFThVxxJzcq76iYDM1zz8qq2MVVYE=",
-    "books/agentic-design-patterns/images/chapter-17/image2.png": "O1KLKrodQew2Pdd7k3vBZhE4dCiK9u6JLvXSXy7h1do=",
-    "books/agentic-design-patterns/images/chapter-17/image3.png": "Sd9qFn-U5g8dhinNPJEk5LaeaN8DFH2FCus1Wcm6oSg=",
-    "books/agentic-design-patterns/images/chapter-17/image4.png": "eV38Dg78Y2Qo-0sqlsvcK8-p19fgRJqwx42sBKTzC+s=",
-    "books/agentic-design-patterns/images/chapter-17/image5.png": "bgKPC1TSVlvfkCG5vILT-4j9gJU7LyeGFkXO+8OFdXE=",
-    "books/agentic-design-patterns/images/chapter-17/image6.png": "qMku-C8gxZEFQEl8Qq8Y1ld5zUntH1Q-2izcb4QxLA0=",
-    "books/agentic-design-patterns/images/chapter-17/image7.png": "20wopLVN59okB+C-F+U5vi79Lg0uH+5P6wIj72gV7wU=",
-    "books/agentic-design-patterns/images/chapter-18/image1.png": "kjCIoNU60icXMOHmYNXWNMjdi5nIdJZYDSp0WFnG2Es=",
-    "books/agentic-design-patterns/images/chapter-19/image1.png": "XrQVFAWWsMcwKHgcqx8jGLy4q+6RbiGZ5CuKpRlk4Y0=",
-    "books/agentic-design-patterns/images/chapter-19/image2.png": "URHY+cH5AR4KvA6HPnXPhZd5fwwGdlwvFvxgCdTkWjg=",
-    "books/agentic-design-patterns/images/chapter-19/image3.png": "VLp1qFNcaj126-RuATV6ikSsow8lrXsn3EuZotvR5N4=",
-    "books/agentic-design-patterns/images/chapter-19/image4.png": "CnyNMtPiFSdzqrewwLgPu2X1CKdgMqCl8T8+d7lw2Fw=",
-    "books/agentic-design-patterns/images/chapter-2/image1.png": "C6odPDB9zhN28YxfU909JAoQWe0mRm3lUsyG8NzHBWk=",
-    "books/agentic-design-patterns/images/chapter-20/image1.png": "qkzjKCUjVFD8IWyoZQXuBuZ4zFJ0Y0CQfKepVcrnEN0=",
-    "books/agentic-design-patterns/images/chapter-21/image1.png": "3KpW6uLQDru7DFDdgi6ntD5WhuGS383aYwlQLWoVX+w=",
-    "books/agentic-design-patterns/images/chapter-21/image2.png": "wSXMrRuAnhQcEM5fg-sJ5ZikM3olj0vz6FDKWKIUyW8=",
-    "books/agentic-design-patterns/images/chapter-3/image1.png": "iHnUE2kckwzB0xiIySSe4O34c6bIs3VlO7pUQBmV8iI=",
-    "books/agentic-design-patterns/images/chapter-3/image2.png": "9-G6F+aBymQVTnDQy4zwsXDZMkLaYKBe4xw26tC24R8=",
-    "books/agentic-design-patterns/images/chapter-4/image1.png": "8h0PBlqt+JFo7Y803cA9MgfTe8TZeZd6te9l+WEsIss=",
-    "books/agentic-design-patterns/images/chapter-4/image2.png": "p-arzpUPFdnKmzTOKaDQys5Eml0jHA7VuUV0FyLYpqM=",
-    "books/agentic-design-patterns/images/chapter-5/image1.png": "XE5qhAklrW-7eVf7T9x9vo4xQX3WesZjZ9IjuyeSUkc=",
-    "books/agentic-design-patterns/images/chapter-5/image2.png": "MqUdsG5aXQECft+lsCRTeMIJP-YzxWFHC8HdNzio6aw=",
-    "books/agentic-design-patterns/images/chapter-6/image1.png": "t6mFrbVSNJYF73t+Q+YydXdwRQr1c4yIUkySvCelw1I=",
-    "books/agentic-design-patterns/images/chapter-6/image2.png": "zvwqWis6Ad7Iv1-wgYtTgz2ItXsno2PetcHRHon0-wY=",
-    "books/agentic-design-patterns/images/chapter-6/image3.png": "al-H2S7UznxQzP3KT3N0lCTNd83B45bqbPppuhSphy0=",
-    "books/agentic-design-patterns/images/chapter-6/image4.png": "u2k2jHjTOABLTlJ3OsxkGyCoOR-fwHeDmTXMACbtQ+4=",
-    "books/agentic-design-patterns/images/chapter-7/image1.png": "izX9YjrJ+gHGOiR9RHbuMIupCE2zyB01w-gwJAJr4Is=",
-    "books/agentic-design-patterns/images/chapter-7/image2.png": "-0zrZR8CNZqtuyaBRwUbZSfthKwuqrBu4fLar9L4Clg=",
-    "books/agentic-design-patterns/images/chapter-7/image3.png": "dKr7VICWOTc-ZRhm4Aaokz+xPZ8IXS0SiDOJeF1Y03c=",
-    "books/agentic-design-patterns/images/chapter-8/image1.png": "GWG47Om+9GwRvl8x-X269Sa-Mv3rqkW2xkx1WIB-I-E=",
-    "books/agentic-design-patterns/images/chapter-9/image1.png": "fIZ4QE7EIQSAv0K2GmU99OmTBAkpvnYUsFFScCv6VPI=",
-    "books/agentic-design-patterns/images/chapter-9/image2.png": "6y-8OjY7oEedk5ZhUUU2YIU3tjMxIzpnxcDxIRWPGpI=",
-    "books/agentic-design-patterns/images/chapter-9/image3.png": "69nSkOOPfX9FkIJGhKIrhSuCOZt29L5UAukVXfMXN2E=",
-    "books/agentic-design-patterns/images/chapter-9/image4.png": "GQCpjBMz5DRxsHIA8-73IMsxeBPc5ZTMaIsx2iihMME=",
-    "books/agentic-design-patterns/images/cover.png": "R47dqw-ws79m6VBfzhWuLi9ihoCaU7JcezquBAB1-bQ=",
-    "images/amytis-screenshot.jpg": "t9tzciqJPsNz1hlixAFLrrvD4Fsaih2Kbd1Jd2C-fqs=",
-    "images/antelope-canyon.jpg": "xuP3HlbwqA4z1Hsq7s1u2u61yN3SHzIMUd6Wl5yqgK8=",
-    "images/avatar.jpg": "SUGxOhDUD96YiVxZJkVJ6ou4W5MdCJ9hTBQMSQanZOM=",
-    "images/cappadocia.jpg": "EE2Mt8d9ERKd40SfwyhjFsejZLhFx1SfSAQmlu+TQOo=",
-    "images/flowers.jpg": "Lq9dhpZvAIgkYnijDsFIzrKiv8trdM-cUnl-5Y86PuM=",
-    "images/galaxy.jpg": "-3YwMkU3PGsm4P2yNsA2S02XRL1j0KbBh6nWKwy0hYc=",
-    "images/lake.jpg": "imAORQhxpmoU3jzKBMNFJuFSa0UgiSf2Dmea5Rj8-8M=",
-    "images/mountains.jpg": "FsrkZws9EKMqHCk1Hc6i6nEIcTRcrMBa4ddgqR6oRaI=",
-    "images/screenshot.png": "FAqbAgLRbWbYq9yJ4iggq2aKxRD8hdeDICc3DI14yhg=",
-    "images/vibrant-waves.jpg": "vdBm72ev5ETPM5H2CDK6tqph5t8N5nTCSApBJp2lW6U=",
-    "images/wechat-qr.jpg": "DNIzz0Wcl8WP0h-jHHgZ9LEvf3ZKOXHgxlvpw3gK2ME=",
-    "posts/02-routing-mastery/assets/m-p-model.png": "fDmvlEkZnE-UCvPK4gmDkJD7SU8coOTl4iw5hpsmcWI=",
-    "posts/images/vibrant-waves.jpg": "YogfFJOm4PQV1g3iMRpCL1pKtjPXpMeJDFf6NTILcBQ="
+    "images/amytis-screenshot.jpg": "rWj-Nh3prlVpvj8efQnsSHJTSOOVzgz9PGnQRj98jXc=",
+    "images/antelope-canyon.jpg": "sub7CbOTPj1Vred2Ow9yJKMqjbP9+0nkjmmaaa5Di2k=",
+    "images/avatar.jpg": "4c7EI6nQ6UHOj9drx0D42heSmiYWTt0Gd3Nsri3BQeo=",
+    "images/cappadocia.jpg": "eDzJe+p3qkAP83ATa7x0m0od4LxwkZltWsVQ2s9rgDI=",
+    "images/flowers.jpg": "oxwbVQa8o5AcEu-vRbHj9o64BTZwCFxPOSA7D53n7tI=",
+    "images/galaxy.jpg": "yDGttkksBSUhLDWlVL2BFGg1al1+GHy3BXcEVp07bys=",
+    "images/lake.jpg": "NEaTNMMXdrgHLMU7CDEWEVwguVdv1E4y5FN8CMHqTvg=",
+    "images/mountains.jpg": "0YIE1wGkreZ1MzM8zGnXCQ9I-IcmA+zO52-dtfL4X94=",
+    "images/screenshot.png": "zuBVQ-P-dCmcM9tYPdDvixwAHo7rGTZQE1y+X4o2pJ4=",
+    "images/vibrant-waves.jpg": "uWywQzN1RbusnZFato8mb7pqvCUkAr4us50HU6rFYUg=",
+    "images/wechat-qr.jpg": "Vhxz8S8TDfXZUjB3M5o5jvis3hu2n8xJEdW3bPjtd+A=",
+    "posts/02-routing-mastery/assets/m-p-model.png": "LZQHFy9SfWdBHatT9DwrARlD1sRqLT2blB573YyTv-U=",
+    "posts/images/vibrant-waves.jpg": "J+C7EolOmfP3fHl-22UoIx-h0hImPk9iEhL+66I60P4=",
+    "posts/welcome-to-amytis/images/vibrant-waves.jpg": "gAUaQXipxs2k7jJ6OoyIJ1+hj9HjM5QeuUuWTQoByps="
 }

package/scripts/build-pagefind.ts

@@ -0,0 +1,172 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as pagefind from 'pagefind';
+
+interface PagefindManifest {
+  version: string;
+  sitePath: string;
+  outputPath: string;
+  files: Record<string, string>;
+}
+
+const PAGEFIND_MANIFEST_VERSION = '1';
+const pagefindCacheDir = path.join(process.cwd(), '.cache', 'pagefind');
+
+function parseArgs(argv: string[]): { sitePath: string; outputPath: string } {
+  let sitePath = 'out';
+  let outputPath = path.join('out', 'pagefind');
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--site') {
+      sitePath = argv[++i] ?? sitePath;
+      continue;
+    }
+    if (arg === '--output-path') {
+      outputPath = argv[++i] ?? outputPath;
+      continue;
+    }
+  }
+
+  return { sitePath, outputPath };
+}
+
+function walkHtmlFiles(rootDir: string): string[] {
+  const files: string[] = [];
+
+  const visit = (dir: string) => {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(fullPath);
+        continue;
+      }
+      if (entry.isFile() && entry.name.endsWith('.html')) {
+        files.push(fullPath);
+      }
+    }
+  };
+
+  if (fs.existsSync(rootDir)) {
+    visit(rootDir);
+  }
+
+  return files.sort();
+}
+
+export function collectHtmlFileHashes(sitePath: string): Record<string, string> {
+  const absoluteSitePath = path.resolve(sitePath);
+  const files = walkHtmlFiles(absoluteSitePath);
+  const hashes: Record<string, string> = {};
+
+  for (const filePath of files) {
+    const relativePath = path.relative(absoluteSitePath, filePath).replaceAll(path.sep, '/');
+    const content = fs.readFileSync(filePath);
+    hashes[relativePath] = createHash('sha1').update(content).digest('hex');
+  }
+
+  return hashes;
+}
+
+function getPagefindManifestPath(sitePath: string, outputPath: string): string {
+  const cacheKey = createHash('sha1')
+    .update(`${path.resolve(sitePath)}::${path.resolve(outputPath)}`)
+    .digest('hex');
+  return path.join(pagefindCacheDir, `${cacheKey}.json`);
+}
+
+export function getPagefindManifestPathForTests(sitePath: string, outputPath: string): string {
+  return getPagefindManifestPath(sitePath, outputPath);
+}
+
+function loadManifest(sitePath: string, outputPath: string): PagefindManifest | null {
+  const manifestPath = getPagefindManifestPath(sitePath, outputPath);
+  if (!fs.existsSync(manifestPath)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as PagefindManifest;
+  } catch {
+    return null;
+  }
+}
+
+function writeManifest(sitePath: string, outputPath: string, files: Record<string, string>): void {
+  const manifestPath = getPagefindManifestPath(sitePath, outputPath);
+  const manifest: PagefindManifest = {
+    version: PAGEFIND_MANIFEST_VERSION,
+    sitePath: path.resolve(sitePath),
+    outputPath: path.resolve(outputPath),
+    files,
+  };
+
+  try {
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest), 'utf8');
+  } catch (error) {
+    console.warn(`[pagefind] Failed to persist manifest at ${manifestPath}:`, error);
+  }
+}
+
+export function shouldSkipPagefindBuild(sitePath: string, outputPath: string, currentFiles: Record<string, string>): boolean {
+  const manifest = loadManifest(sitePath, outputPath);
+  if (!manifest) return false;
+  if (manifest.version !== PAGEFIND_MANIFEST_VERSION) return false;
+  if (manifest.sitePath !== path.resolve(sitePath)) return false;
+  if (manifest.outputPath !== path.resolve(outputPath)) return false;
+  if (!fs.existsSync(outputPath)) return false;
+
+  const previousEntries = Object.entries(manifest.files).sort(([a], [b]) => a.localeCompare(b));
+  const currentEntries = Object.entries(currentFiles).sort(([a], [b]) => a.localeCompare(b));
+  if (previousEntries.length !== currentEntries.length) return false;
+
+  return previousEntries.every(([file, hash], index) => {
+    const [currentFile, currentHash] = currentEntries[index];
+    return file === currentFile && hash === currentHash;
+  });
+}
+
+async function buildPagefind(sitePath: string, outputPath: string): Promise<void> {
+  const currentFiles = collectHtmlFileHashes(sitePath);
+
+  if (shouldSkipPagefindBuild(sitePath, outputPath, currentFiles)) {
+    console.log(`[pagefind] Skipping rebuild; no HTML changes detected for ${sitePath}.`);
+    return;
+  }
+
+  fs.rmSync(outputPath, { recursive: true, force: true });
+
+  const { index, errors } = await pagefind.createIndex();
+  if (errors.length > 0 || !index) {
+    throw new Error(`Failed to create Pagefind index: ${errors.join(', ') || 'unknown error'}`);
+  }
+
+  try {
+    const addResult = await index.addDirectory({ path: sitePath });
+    if (addResult.errors.length > 0) {
+      throw new Error(`Failed to index ${sitePath}: ${addResult.errors.join(', ')}`);
+    }
+
+    const writeResult = await index.writeFiles({ outputPath });
+    if (writeResult.errors.length > 0) {
+      throw new Error(`Failed to write Pagefind output: ${writeResult.errors.join(', ')}`);
+    }
+  } finally {
+    await pagefind.close();
+  }
+
+  writeManifest(sitePath, outputPath, currentFiles);
+}
+
+async function main() {
+  const { sitePath, outputPath } = parseArgs(Bun.argv.slice(2));
+  await buildPagefind(sitePath, outputPath);
+}
+
+if (import.meta.main) {
+  main().catch((error) => {
+    console.error('[pagefind] Build failed:', error);
+    process.exit(1);
+  });
+}

package/scripts/copy-assets.ts

@@ -9,45 +9,114 @@ const flowsSrcDir = path.join(process.cwd(), 'content', 'flows');
 const destDir = path.join(process.cwd(), 'public', 'posts');
 const booksDestDir = path.join(process.cwd(), 'public', 'books');
 const flowsDestDir = path.join(process.cwd(), 'public', 'flows');
+const optimizerDirName = 'nextImageExportOptimizer';
+const generatedAssetDestinations = new Set<string>();
+
+function copyFileOrThrow(srcPath: string, destPath: string, context: string) {
+  try {
+    fs.copyFileSync(srcPath, destPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`[copy-assets] Failed to copy ${context}: ${srcPath} -> ${destPath}: ${message}`);
+  }
+}
+
+function markGeneratedDestination(destPath: string) {
+  generatedAssetDestinations.add(path.resolve(destPath));
+}
+
+function shouldPreserveOptimizerDir(optimizerPath: string): boolean {
+  const optimizerParentPath = path.resolve(path.dirname(optimizerPath));
+  return [...generatedAssetDestinations].some((generatedDestination) =>
+    optimizerParentPath === generatedDestination ||
+    optimizerParentPath.startsWith(`${generatedDestination}${path.sep}`)
+  );
+}
+
+function pruneOrphanedOptimizerDirs(rootDir: string) {
+  if (!fs.existsSync(rootDir)) return;
+
+  const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(rootDir, entry.name);
+
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    if (entry.name === optimizerDirName) {
+      if (!shouldPreserveOptimizerDir(entryPath)) {
+        fs.rmSync(entryPath, { recursive: true, force: true });
+      }
+      continue;
+    }
+
+    pruneOrphanedOptimizerDirs(entryPath);
+  }
+}
+
+function resetGeneratedAssetDirs() {
+  generatedAssetDestinations.clear();
+  fs.mkdirSync(destDir, { recursive: true });
+  fs.mkdirSync(booksDestDir, { recursive: true });
+  fs.mkdirSync(flowsDestDir, { recursive: true });
+}
+
+function shouldSkipSourceFile(name: string): boolean {
+  return name.endsWith('.md') || name.endsWith('.mdx') || name.endsWith('.rst');
+}
 
-function copyRecursive(src: string, dest: string) {
+function shouldCopyBasedOnMtimeAndSize(srcPath: string, destPath: string): boolean {
+  if (!fs.existsSync(destPath)) {
+    return true;
+  }
+
+  const srcStat = fs.statSync(srcPath);
+  const destStat = fs.statSync(destPath);
+  return srcStat.mtimeMs > destStat.mtimeMs || srcStat.size !== destStat.size;
+}
+
+function syncRecursive(src: string, dest: string) {
   if (!fs.existsSync(src)) return;
-  
+
   if (!fs.existsSync(dest)) {
     fs.mkdirSync(dest, { recursive: true });
   }
 
-  const entries = fs.readdirSync(src, { withFileTypes: true });
+  const srcEntries = fs.readdirSync(src, { withFileTypes: true });
+  const srcNames = new Set(srcEntries.map((entry) => entry.name));
 
-  for (const entry of entries) {
+  for (const entry of srcEntries) {
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
 
     if (entry.isDirectory()) {
-      copyRecursive(srcPath, destPath);
+      syncRecursive(srcPath, destPath);
     } else {
-      // Copy all files except markdown source
-      if (!entry.name.endsWith('.md') && !entry.name.endsWith('.mdx')) {
-        let shouldCopy = true;
-        if (fs.existsSync(destPath)) {
-          const srcStat = fs.statSync(srcPath);
-          const destStat = fs.statSync(destPath);
-          if (srcStat.mtimeMs <= destStat.mtimeMs) {
-            shouldCopy = false;
-          }
-        }
+      if (shouldSkipSourceFile(entry.name)) {
+        continue;
+      }
 
-        if (shouldCopy) {
-          fs.copyFileSync(srcPath, destPath);
-          // console.log(`Copied: ${entry.name} -> ${destPath}`);
-        }
+      if (shouldCopyBasedOnMtimeAndSize(srcPath, destPath)) {
+        copyFileOrThrow(srcPath, destPath, 'recursive asset');
       }
     }
   }
+
+  const destEntries = fs.readdirSync(dest, { withFileTypes: true });
+  for (const entry of destEntries) {
+    if (entry.name === optimizerDirName) continue;
+
+    const destPath = path.join(dest, entry.name);
+
+    if (!srcNames.has(entry.name)) {
+      fs.rmSync(destPath, { recursive: true, force: true });
+    }
+  }
 }
 
 function getSlugFromFilename(filename: string): string {
-  const nameWithoutExt = filename.replace(/\.mdx?$/, '');
+  const nameWithoutExt = filename.replace(/\.(mdx?|rst)$/, '');
   const dateRegex = /^(\d{4}-\d{2}-\d{2})-(.*)$/;
   const match = nameWithoutExt.match(dateRegex);
 
@@ -57,6 +126,124 @@ function getSlugFromFilename(filename: string): string {
   return nameWithoutExt;
 }
 
+function isLocalAssetReference(rawPath: string): boolean {
+  const trimmed = rawPath.trim();
+  return Boolean(trimmed) &&
+    !trimmed.startsWith('#') &&
+    !trimmed.startsWith('/') &&
+    !trimmed.startsWith('http://') &&
+    !trimmed.startsWith('https://') &&
+    !trimmed.startsWith('data:') &&
+    !trimmed.startsWith('mailto:') &&
+    !trimmed.startsWith('javascript:');
+}
+
+function normalizeReferencedAssetPath(rawPath: string): string | null {
+  const trimmed = rawPath.trim().replace(/^['"]|['"]$/g, '');
+  const withoutFragment = trimmed.split('#')[0]?.split('?')[0]?.trim();
+  if (!withoutFragment || !isLocalAssetReference(withoutFragment)) {
+    return null;
+  }
+
+  return withoutFragment;
+}
+
+function extractReferencedAssetPaths(filePath: string): string[] {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const references = new Set<string>();
+  const patterns = [
+    /\!\[[^\]]*\]\(([^)]+)\)/g,
+    /\[[^\]]*\]\(([^)]+)\)/g,
+    /\b(?:src|href|poster)=["']([^"']+)["']/g,
+    /^\s*\.\.\s+(?:image|figure)::\s+(.+)$/gm,
+    /^coverImage:\s*['"]?([^'"\n]+)['"]?$/gm,
+  ];
+
+  for (const pattern of patterns) {
+    for (const match of content.matchAll(pattern)) {
+      const candidate = normalizeReferencedAssetPath(match[1] ?? '');
+      if (candidate) {
+        references.add(candidate);
+      }
+    }
+  }
+
+  return [...references];
+}
+
+function syncReferencedAssets(sourceFile: string, rootDir: string, destPostDir: string) {
+  const references = extractReferencedAssetPaths(sourceFile);
+  const desiredRelativePaths = new Set<string>();
+
+  if (!fs.existsSync(destPostDir)) {
+    fs.mkdirSync(destPostDir, { recursive: true });
+  }
+
+  references.forEach((reference) => {
+    const absolutePath = path.resolve(path.dirname(sourceFile), reference);
+    const relativeToRoot = path.relative(rootDir, absolutePath);
+
+    if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot) || !fs.existsSync(absolutePath)) {
+      return;
+    }
+
+    const sourceStat = fs.statSync(absolutePath);
+    if (sourceStat.isDirectory()) {
+      return;
+    }
+
+    if (absolutePath.endsWith('.md') || absolutePath.endsWith('.mdx') || absolutePath.endsWith('.rst')) {
+      return;
+    }
+
+    const destPath = path.join(destPostDir, relativeToRoot);
+    desiredRelativePaths.add(relativeToRoot.replaceAll(path.sep, '/'));
+    if (!fs.existsSync(path.dirname(destPath))) {
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    }
+
+    if (shouldCopyBasedOnMtimeAndSize(absolutePath, destPath)) {
+      copyFileOrThrow(absolutePath, destPath, `referenced asset from ${sourceFile}`);
+    }
+  });
+
+  function pruneDestDir(currentDir: string, relativeDir = '') {
+    if (!fs.existsSync(currentDir)) return;
+
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === optimizerDirName) continue;
+
+      const relativePath = relativeDir ? path.join(relativeDir, entry.name) : entry.name;
+      const normalizedRelativePath = relativePath.replaceAll(path.sep, '/');
+      const fullPath = path.join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        const hasDesiredDescendant = [...desiredRelativePaths].some((desiredPath) =>
+          desiredPath === normalizedRelativePath || desiredPath.startsWith(`${normalizedRelativePath}/`)
+        );
+
+        if (!hasDesiredDescendant) {
+          fs.rmSync(fullPath, { recursive: true, force: true });
+          continue;
+        }
+
+        pruneDestDir(fullPath, relativePath);
+        if (fs.existsSync(fullPath) && fs.readdirSync(fullPath).length === 0) {
+          fs.rmdirSync(fullPath);
+        }
+        continue;
+      }
+
+      if (!desiredRelativePaths.has(normalizedRelativePath)) {
+        fs.rmSync(fullPath, { force: true });
+      }
+    }
+  }
+
+  pruneDestDir(destPostDir);
+}
+
 function processPosts() {
   if (fs.existsSync(srcDir)) {
     const entries = fs.readdirSync(srcDir, { withFileTypes: true });
@@ -68,7 +255,19 @@ function processPosts() {
         const destPostDir = path.join(destDir, targetName);
 
         console.log(`Processing Post: ${entry.name} -> ${targetName}`);
-        copyRecursive(srcPostDir, destPostDir);
+        markGeneratedDestination(destPostDir);
+        syncRecursive(srcPostDir, destPostDir);
+      } else if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdx') || entry.name.endsWith('.rst'))) {
+        const targetName = getSlugFromFilename(entry.name);
+        const sourceFile = path.join(srcDir, entry.name);
+        const destPostDir = path.join(destDir, targetName);
+
+        console.log(`Processing Flat Post: ${entry.name} -> ${targetName}`);
+        markGeneratedDestination(destPostDir);
+        if (!fs.existsSync(destPostDir)) {
+          fs.mkdirSync(destPostDir, { recursive: true });
+        }
+        syncReferencedAssets(sourceFile, srcDir, destPostDir);
       }
     });
   }
@@ -77,12 +276,8 @@ function processPosts() {
 // Check if a directory is a post folder (contains index.md or index.mdx)
 function isPostFolder(dirPath: string): boolean {
   return fs.existsSync(path.join(dirPath, 'index.md')) ||
-         fs.existsSync(path.join(dirPath, 'index.mdx'));
-}
-
-// Check if a directory is an asset folder (not a post folder)
-function isAssetFolder(dirPath: string): boolean {
-  return !isPostFolder(dirPath);
+         fs.existsSync(path.join(dirPath, 'index.mdx')) ||
+         fs.existsSync(path.join(dirPath, 'index.rst'));
 }
 
 function processSeries() {
@@ -95,37 +290,23 @@ function processSeries() {
       const seriesPath = path.join(seriesSrcDir, seriesEntry.name);
       const items = fs.readdirSync(seriesPath, { withFileTypes: true });
 
-      // First pass: identify shared asset folders at series level (folders that are NOT posts)
-      const sharedAssetFolders = items
-        .filter(item => item.isDirectory() && isAssetFolder(path.join(seriesPath, item.name)))
-        .map(item => item.name);
-
       // Process items in series folder
       items.forEach(item => {
-        if (item.isFile() && (item.name.endsWith('.md') || item.name.endsWith('.mdx'))) {
+        if (item.isFile() && (item.name.endsWith('.md') || item.name.endsWith('.mdx') || item.name.endsWith('.rst'))) {
           // File-based post or series index
-          const targetSlug = item.name.startsWith('index.') ? seriesEntry.name : getSlugFromFilename(item.name);
+          const isSeriesIndex = item.name.startsWith('index.') || item.name.startsWith('README.');
+          const targetSlug = isSeriesIndex ? seriesEntry.name : getSlugFromFilename(item.name);
+          const sourceFile = path.join(seriesPath, item.name);
           const destPostDir = path.join(destDir, targetSlug);
 
           console.log(`Processing Series File: ${item.name} -> ${targetSlug}`);
+          markGeneratedDestination(destPostDir);
 
-          // Only copy shared asset folders (like images/, assets/), not sibling post folders
-          sharedAssetFolders.forEach(folderName => {
-            const srcPath = path.join(seriesPath, folderName);
-            const destPath = path.join(destPostDir, folderName);
-            copyRecursive(srcPath, destPath);
-          });
+          if (!fs.existsSync(destPostDir)) {
+            fs.mkdirSync(destPostDir, { recursive: true });
+          }
 
-          // Copy any non-markdown files at the series root level
-          items.filter(sub => sub.isFile() && !sub.name.endsWith('.md') && !sub.name.endsWith('.mdx'))
-            .forEach(sub => {
-              const srcPath = path.join(seriesPath, sub.name);
-              const destPath = path.join(destPostDir, sub.name);
-              if (!fs.existsSync(destPostDir)) {
-                fs.mkdirSync(destPostDir, { recursive: true });
-              }
-              fs.copyFileSync(srcPath, destPath);
-            });
+          syncReferencedAssets(sourceFile, seriesPath, destPostDir);
 
         } else if (item.isDirectory() && isPostFolder(path.join(seriesPath, item.name))) {
           // Folder-based post: copy only its own assets
@@ -134,6 +315,7 @@ function processSeries() {
           const destPostDir = path.join(destDir, targetSlug);
 
           console.log(`Processing Series Post Folder: ${item.name} -> ${targetSlug}`);
+          markGeneratedDestination(destPostDir);
 
           // Copy everything from the post folder EXCEPT markdown files
           const subItems = fs.readdirSync(itemSrcPath, { withFileTypes: true });
@@ -142,12 +324,14 @@ function processSeries() {
             const destPath = path.join(destPostDir, sub.name);
 
             if (sub.isDirectory()) {
-              copyRecursive(srcPath, destPath);
-            } else if (!sub.name.endsWith('.md') && !sub.name.endsWith('.mdx')) {
+              syncRecursive(srcPath, destPath);
+            } else if (!shouldSkipSourceFile(sub.name)) {
               if (!fs.existsSync(destPostDir)) {
                 fs.mkdirSync(destPostDir, { recursive: true });
               }
-              fs.copyFileSync(srcPath, destPath);
+              if (shouldCopyBasedOnMtimeAndSize(srcPath, destPath)) {
+                copyFileOrThrow(srcPath, destPath, `series post asset from ${itemSrcPath}`);
+              }
             }
           });
         }
@@ -167,7 +351,8 @@ function processBooks() {
       const destBookDir = path.join(booksDestDir, entry.name);
 
       console.log(`Processing Book: ${entry.name}`);
-      copyRecursive(srcBookDir, destBookDir);
+      markGeneratedDestination(destBookDir);
+      syncRecursive(srcBookDir, destBookDir);
     }
   });
 }
@@ -197,15 +382,20 @@ function processFlows() {
         const destFlowDir = path.join(flowsDestDir, yearEntry.name, monthEntry.name, rawName);
 
         console.log(`Processing Flow: ${yearEntry.name}/${monthEntry.name}/${rawName}`);
-        copyRecursive(srcFlowDir, destFlowDir);
+        markGeneratedDestination(destFlowDir);
+        syncRecursive(srcFlowDir, destFlowDir);
       }
     }
   }
 }
 
 console.log('Copying assets...');
+resetGeneratedAssetDirs();
 processPosts();
 processSeries();
 processBooks();
 processFlows();
-console.log('Assets copied successfully.');
+pruneOrphanedOptimizerDirs(destDir);
+pruneOrphanedOptimizerDirs(booksDestDir);
+pruneOrphanedOptimizerDirs(flowsDestDir);
+console.log('Assets copied successfully.');