Merge pull request #129 from link-assistant/issue-117-6f9cc6105c70

Stop deleting Google Docs images on `--keep-original-links` (empty-alt strip)

Author: konard

.gitkeep

@@ -1,3 +1,4 @@
 # .gitkeep file auto-generated at 2026-04-06T22:55:07.509Z for PR creation at branch issue-31-e38e38b91777 for issue https://github.com/link-assistant/web-capture/issues/31
 # Updated: 2026-04-14T15:38:45.969Z
-# Updated: 2026-05-11T11:39:08.824Z
+# Updated: 2026-05-11T11:39:08.824Z
+# Updated: 2026-05-11T12:31:37.540Z

js/.changeset/issue-117-strip-empty-alt-placeholder.md

@@ -0,0 +1,5 @@
+---
+'@link-assistant/web-capture': patch
+---
+
+Fix `stripBase64Images` (used by `--keep-original-links`) dropping every base64 image with empty alt text instead of leaving a visible placeholder. Google Docs HTML exports emit `<img alt="" src="data:image/png;base64,...">` for every image, so the previous behaviour silently deleted all images from the rendered markdown. Empty-alt now renders as `![]()` (a valid empty image reference); non-empty alt continues to render as `*[image: <alt>]*`.

js/src/extract-images.js

@@ -95,9 +95,16 @@ export function extractBase64ToBuffers(markdown, imagesDir = 'images') {
 }
 
 /**
- * Strip base64 data URI images from markdown, leaving only the alt text
- * as a placeholder. Used when keepOriginalLinks is enabled — base64 images
- * have no original URL to restore, so we remove the heavy data URI.
+ * Strip base64 data URI images from markdown, leaving a visible placeholder.
+ * Used when keepOriginalLinks is enabled — base64 images have no original URL
+ * to restore, so we remove the heavy data URI but still leave a marker so the
+ * reader can see that an image was here.
+ *
+ * Non-empty alt becomes `*[image: <alt>]*`. Empty alt — common for Google Docs
+ * HTML exports, which emit `<img alt="" src="data:...">` for every image —
+ * becomes `![]()`, an empty markdown image reference that renderers still
+ * surface as a slot. Emitting `''` for empty-alt would silently delete every
+ * image in the document (see issue #117).
  *
  * @param {string} markdown - Markdown content with data URI images
  * @returns {{markdown: string, stripped: number}}
@@ -108,7 +115,7 @@ export function stripBase64Images(markdown) {
     BASE64_IMAGE_REGEX,
     (_match, altText) => {
       stripped++;
-      return altText ? `*[image: ${altText}]*` : '';
+      return altText ? `*[image: ${altText}]*` : '![]()';
     }
   );
   return { markdown: updatedMarkdown, stripped };

js/tests/unit/extract-images.test.js

@@ -204,12 +204,18 @@ describe('extract-images module', () => {
       expect(result.markdown).not.toContain('data:image');
     });
 
-    it('strips base64 images with empty alt text', () => {
-      const md = `![](data:image/png;base64,${TINY_PNG})`;
+    it('leaves a visible placeholder when stripping a base64 image with empty alt', () => {
+      // Google Docs HTML exports emit `<img alt="" src="data:image/png;base64,...">`,
+      // which renders as `![](data:...)`. If stripping drops the markdown image
+      // entirely, every image in the doc vanishes from the output with no
+      // indication that anything was lost. Leave a visible placeholder so the
+      // reader can see that an image was here.
+      const md = `Hi.\n\n![](data:image/png;base64,${TINY_PNG})\n\nBye.\n`;
       const result = stripBase64Images(md);
 
       expect(result.stripped).toBe(1);
-      expect(result.markdown).toBe('');
+      expect(result.markdown).not.toMatch(/data:image/);
+      expect(result.markdown).toMatch(/!\[|\[image/);
     });
 
     it('preserves remote image URLs', () => {

rust/Cargo.lock

@@ -157,15 +157,21 @@ pub struct ImageBuffer {
     pub data: Vec<u8>,
 }
 
-/// Strip base64 data URI images from markdown, leaving alt text placeholders.
+/// Strip base64 data URI images from markdown, leaving a visible placeholder.
+///
+/// Non-empty alt becomes `*[image: <alt>]*`. Empty alt — common for Google
+/// Docs HTML exports, which emit `<img alt="" src="data:...">` for every
+/// image — becomes `![]()`, an empty markdown image reference that renderers
+/// still surface as a slot. Emitting `""` for empty-alt would silently delete
+/// every image in the document (see issue #117).
 #[must_use]
 pub fn strip_base64_images(markdown: &str) -> StrippedResult {
     let mut stripped = 0;
     let updated = base64_md_image_pattern().replace_all(markdown, |caps: &regex::Captures<'_>| {
         stripped += 1;
         let alt_text = &caps[1];
         if alt_text.is_empty() {
-            String::new()
+            "![]()".to_string()
         } else {
             format!("*[image: {alt_text}]*")
         }

rust/src/extract_images.rs

@@ -12,4 +12,5 @@ mod html2md_br_in_list_item;
 mod html2md_ol_numbering;
 mod markdown_no_empty_title;
 mod paragraph_vs_line_break;
+mod strip_base64_empty_alt;
 mod themed_image;

rust/tests/integration/mod.rs

@@ -0,0 +1,46 @@
+//! Regression test for #117 — `--keep-original-links` on Google Docs API
+//! exports stripped every image entirely because the HTML export emits
+//! `<img alt="" src="data:image/png;base64,...">`, the markdown converter
+//! rendered that as `![](data:...)`, and the strip helper only emitted a
+//! placeholder when `alt` was non-empty. The result was a silently
+//! image-less document with no indication that anything was lost.
+
+use web_capture::extract_images::strip_base64_images;
+
+// 1x1 red PNG pixel as base64.
+const TINY_PNG: &str = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
+
+#[test]
+fn strip_keeps_a_visible_placeholder_for_empty_alt() {
+    let md = format!("P1.\n\n![](data:image/png;base64,{TINY_PNG})\n\nP2.\n");
+    let r = strip_base64_images(&md);
+    assert_eq!(r.stripped, 1);
+    assert!(!r.markdown.contains("data:image"));
+    assert!(
+        r.markdown.contains("![") || r.markdown.contains("[image"),
+        "stripping must leave a visible placeholder; got:\n{}",
+        r.markdown
+    );
+}
+
+#[test]
+fn strip_keeps_empty_alt_placeholder_distinct_from_non_empty_alt() {
+    // Non-empty alt still produces the `*[image: ...]*` form so authors can
+    // read the alt text. Empty alt produces a structural placeholder so a
+    // human can still tell that an image was here.
+    let md = format!(
+        "![](data:image/png;base64,{TINY_PNG})\n\n![photo](data:image/png;base64,{TINY_PNG})\n"
+    );
+    let r = strip_base64_images(&md);
+    assert_eq!(r.stripped, 2);
+    assert!(!r.markdown.contains("data:image"));
+    assert!(r.markdown.contains("*[image: photo]*"));
+    // Empty-alt branch leaves an `![](...)` style placeholder, so the line
+    // count (and image count, when grepping for `![`) is preserved.
+    let placeholder_count = r.markdown.matches("![").count();
+    assert!(
+        placeholder_count >= 1,
+        "expected at least one `![` placeholder for the empty-alt image; got:\n{}",
+        r.markdown
+    );
+}

rust/tests/integration/strip_base64_empty_alt.rs

@@ -206,13 +206,23 @@ fn test_strip_base64_images_with_alt() {
 }
 
 #[test]
-fn test_strip_base64_images_empty_alt() {
-    let md = format!("![](data:image/png;base64,{TINY_PNG})");
+fn test_strip_base64_images_empty_alt_leaves_visible_placeholder() {
+    // Google Docs HTML exports emit `<img alt="" src="data:image/png;base64,...">`,
+    // which renders as `![](data:...)`. If the stripper drops the markdown image
+    // entirely, every image in the doc vanishes from the output with no
+    // indication that anything was lost. Leave a visible placeholder so the
+    // reader can see that an image was here.
+    let md = format!("Hi.\n\n![](data:image/png;base64,{TINY_PNG})\n\nBye.\n");
 
     let result = strip_base64_images(&md);
 
     assert_eq!(result.stripped, 1);
-    assert!(result.markdown.is_empty());
+    assert!(!result.markdown.contains("data:image"));
+    assert!(
+        result.markdown.contains("![") || result.markdown.contains("[image"),
+        "stripping must leave a visible placeholder; got:\n{}",
+        result.markdown
+    );
 }
 
 #[test]