From 34de90f81bd19eb6beed3e7f8f133f4ff135df2f Mon Sep 17 00:00:00 2001
From: rcarteraz <robert.l.carter2@gmail.com>
Date: Tue, 20 Oct 2026 10:48:28 -0700
Subject: [PATCH 1/2] fix(docs): keep screenshots versioned docs still link

The docs sync prunes every image in static/img/android/docs/ that no current page references. Frozen Docusaurus snapshots under versioned_docs/ link the same files, so a screenshot dropped from the app breaks the site build: meshtastic/meshtastic#2728 fails on three images the 2.7 snapshot still uses. Skip pruning any image a versioned_docs/ page links.
---
 scripts/sync-android-docs.js | 32 ++++++++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/scripts/sync-android-docs.js b/scripts/sync-android-docs.js
index 7a29cddcd36..e5d717a1608 100755
--- a/scripts/sync-android-docs.js
+++ b/scripts/sync-android-docs.js
@@ -17,7 +17,8 @@
 //   static/img/android/docs/*.webp (or .png/.svg if not converting)
 //
 // Only screenshots a synced page actually references are published; any other
-// file already under those two directories is pruned at the end of the run.
+// file already under those two directories is pruned at the end of the run,
+// except screenshots a frozen versioned_docs/ snapshot still links.
 
 "use strict";
 
@@ -52,6 +53,9 @@ if (!fs.existsSync(SRC_DOCS_DIR)) {
 // Output directories (relative to CWD, which should be the meshtastic/meshtastic repo)
 const DEST_DOCS_DIR = path.join("docs", "software", "android");
 const DEST_IMAGES_DIR = path.join("static", "img", "android", "docs");
+// Docusaurus version snapshots. They link the same /img/android/docs/ files as the
+// current pages, but no sync rewrites them, so their images must outlive the app's.
+const VERSIONED_DOCS_DIR = "versioned_docs";
 
 // Derive sibling page slugs from the filesystem (no manual sync needed)
 const KNOWN_USER_SLUGS = discoverSlugs(SRC_DOCS_DIR, "user");
@@ -345,13 +349,29 @@ function collectFiles(dir) {
     return results;
 }
 
+/**
+ * Collect the screenshot basenames that frozen version snapshots still link.
+ * Pruning one of these breaks the site build, since Docusaurus fails on a
+ * Markdown image it cannot resolve.
+ */
+function collectVersionedImageReferences() {
+    const names = new Set();
+    for (const file of collectFiles(VERSIONED_DOCS_DIR)) {
+        const ext = path.extname(file).toLowerCase();
+        if (ext !== ".md" && ext !== ".mdx") continue;
+        collectImageReferences(fs.readFileSync(path.join(VERSIONED_DOCS_DIR, file), "utf-8"), names);
+    }
+    return names;
+}
+
 /**
  * Remove destination files this run did not produce, so renamed or deleted
  * source pages (and the screenshots they referenced) don't linger on the site.
  * Mirrors the Apple sync's cleanup pass. Scoped to docs pages (.md/.mdx) and
- * images under the directories this script owns.
+ * images under the directories this script owns. Images in `keepImageNames`
+ * survive even when no current page references them.
  */
-function pruneStale(expectedDocPaths, expectedImageNames) {
+function pruneStale(expectedDocPaths, expectedImageNames, keepImageNames) {
     for (const file of collectFiles(DEST_DOCS_DIR)) {
         const ext = path.extname(file).toLowerCase();
         if (ext !== ".md" && ext !== ".mdx") continue;
@@ -368,6 +388,10 @@ function pruneStale(expectedDocPaths, expectedImageNames) {
         if (!IMAGE_EXTENSIONS.has(path.extname(file).toLowerCase())) continue;
         if (expectedImageNames.has(path.basename(file))) continue;
         const target = path.join(DEST_IMAGES_DIR, file);
+        if (keepImageNames.has(path.basename(file))) {
+            console.log(`Kept image a versioned snapshot still links: ${target}`);
+            continue;
+        }
         if (DRY_RUN) {
             console.log(`[dry-run] Would remove stale image: ${target}`);
         } else {
@@ -503,7 +527,7 @@ function main() {
     const expectedImageNames = processImages(referencedImages);
 
     // Remove anything left over from a previous sync or the old hand-written docs.
-    pruneStale(expectedDocPaths, expectedImageNames);
+    pruneStale(expectedDocPaths, expectedImageNames, collectVersionedImageReferences());
 
     console.log("\nSync complete.");
 }

From f4b8b609a0d9b5e6fb31e4adb85d25e6a5fe1b21 Mon Sep 17 00:00:00 2001
From: rcarteraz <robert.l.carter2@gmail.com>
Date: Tue, 20 Oct 2026 11:03:10 -0700
Subject: [PATCH 2/2] fix(docs): ignore query strings when matching linked
 images

A link such as /img/android/docs/old.webp?v=2 was recorded as old.webp?v=2, so it never matched the file and the image was pruned anyway. Strip any ?query or #fragment before taking the basename.
---
 scripts/sync-android-docs.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/sync-android-docs.js b/scripts/sync-android-docs.js
index e5d717a1608..933274c9943 100755
--- a/scripts/sync-android-docs.js
+++ b/scripts/sync-android-docs.js
@@ -248,7 +248,8 @@ function collectImageReferences(content, into) {
     const re = /\/img\/android\/docs\/([^)"'\s>]+)/g;
     let match;
     while ((match = re.exec(content)) !== null) {
-        into.add(path.basename(match[1]));
+        // Drop any ?query or #fragment so the name matches the file on disk.
+        into.add(path.basename(match[1].split(/[?#]/, 1)[0]));
     }
 }