From 15ecd5f9115279b80fb799002917b6c50709a530 Mon Sep 17 00:00:00 2001
From: Nick the Sick <computers@nickthesick.com>
Date: Wed, 6 May 2026 18:57:13 +0200
Subject: [PATCH 1/2] fix(a11y): use figure/figcaption for media block captions

Closes #2055. Supersedes #2056.

When a file/image/video/audio block has a caption, render the wrapper
as <figure> with a <figcaption> instead of a <div>+<p>. This matches
the WCAG-recommended semantic for caption-content association and
removes the need for ad-hoc ARIA fallbacks.

Image alt text logic is also tightened:
- caption present -> alt="" (the figcaption is the accessible name;
  this avoids screen readers double-announcing the caption)
- no caption, name present -> alt={name}
- neither -> alt="" (decorative; aria-hidden was dropped because it
  would have removed unintentionally-unlabeled images from the
  accessibility tree entirely)

Co-Authored-By: Cyril G <c.gromoff@gmail.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../helpers/render/createFileBlockWrapper.ts     |  9 +++++++--
 packages/core/src/blocks/Image/block.ts          | 11 +++++++++--
 .../File/helpers/render/FileBlockWrapper.tsx     | 14 +++++++++++---
 packages/react/src/blocks/Image/block.tsx        | 13 +++++++++----
 .../text/html/basicBlocksWithProps.html          |  2 +-
 .../copy/__snapshots__/text/html/image.html      |  2 +-
 .../__snapshots__/text/html/nestedImage.html     |  2 +-
 .../__snapshots__/blocknoteHTML/file/basic.html  |  6 +++---
 .../__snapshots__/blocknoteHTML/file/nested.html | 12 ++++++------
 .../__snapshots__/blocknoteHTML/file/noName.html |  6 +++---
 .../__snapshots__/blocknoteHTML/image.html       |  2 +-
 .../__snapshots__/blocknoteHTML/image/basic.html |  8 ++++----
 .../blocknoteHTML/image/nested.html              | 16 ++++++++--------
 .../blocknoteHTML/image/noName.html              |  8 ++++----
 .../blocknoteHTML/image/noPreview.html           |  6 +++---
 .../blocknoteHTML/image/withCaption.html         |  8 ++++----
 .../blocknoteHTML/video/withCaption.html         |  6 +++---
 .../export/__snapshots__/html/image.html         |  2 +-
 .../export/__snapshots__/html/image/basic.html   |  2 +-
 .../export/__snapshots__/html/image/nested.html  |  4 ++--
 .../export/__snapshots__/html/image/noName.html  |  2 +-
 .../__snapshots__/html/image/withCaption.html    |  2 +-
 .../export/__snapshots__/markdown/image.md       |  2 +-
 .../blocknoteHTML/reactFile/basic.html           |  6 +++---
 .../blocknoteHTML/reactFile/nested.html          | 12 ++++++------
 .../blocknoteHTML/reactFile/noName.html          |  6 +++---
 .../blocknoteHTML/reactImage/basic.html          |  8 ++++----
 .../blocknoteHTML/reactImage/nested.html         | 16 ++++++++--------
 .../blocknoteHTML/reactImage/noName.html         |  8 ++++----
 .../blocknoteHTML/reactImage/noPreview.html      |  6 +++---
 .../__snapshots__/html/reactImage/basic.html     |  2 +-
 .../__snapshots__/html/reactImage/nested.html    |  4 ++--
 .../__snapshots__/html/reactImage/noName.html    |  2 +-
 33 files changed, 120 insertions(+), 95 deletions(-)

diff --git a/packages/core/src/blocks/File/helpers/render/createFileBlockWrapper.ts b/packages/core/src/blocks/File/helpers/render/createFileBlockWrapper.ts
index cbb347acff..51de658d2c 100644
--- a/packages/core/src/blocks/File/helpers/render/createFileBlockWrapper.ts
+++ b/packages/core/src/blocks/File/helpers/render/createFileBlockWrapper.ts
@@ -26,7 +26,12 @@ export const createFileBlockWrapper = (
   element?: { dom: HTMLElement; destroy?: () => void },
   buttonIcon?: HTMLElement,
 ) => {
-  const wrapper = document.createElement("div");
+  // Use a <figure>/<figcaption> when the block has a caption, so the caption
+  // is semantically associated with its content for assistive tech. Falls back
+  // to a plain <div> when there is no caption (or the file has not been
+  // uploaded yet, since the upload UI never shows the caption).
+  const useFigure = block.props.url !== "" && !!block.props.caption;
+  const wrapper = document.createElement(useFigure ? "figure" : "div");
   wrapper.className = "bn-file-block-content-wrapper";
 
   // Show the add file button if the file has not been uploaded yet. Change to
@@ -73,7 +78,7 @@ export const createFileBlockWrapper = (
 
   // Show the caption if there is one.
   if (block.props.caption) {
-    const caption = document.createElement("p");
+    const caption = document.createElement("figcaption");
     caption.className = "bn-file-caption";
     caption.textContent = block.props.caption;
     wrapper.appendChild(caption);
diff --git a/packages/core/src/blocks/Image/block.ts b/packages/core/src/blocks/Image/block.ts
index 503c483527..fc6d4b3377 100644
--- a/packages/core/src/blocks/Image/block.ts
+++ b/packages/core/src/blocks/Image/block.ts
@@ -116,7 +116,11 @@ export const imageRender =
       image.src = block.props.url;
     }
 
-    image.alt = block.props.name || block.props.caption || "BlockNote image";
+    // When a caption is set, the wrapper renders a <figcaption> that serves as
+    // the image's accessible name, so an empty alt avoids double-announcement.
+    // Otherwise prefer the file name; fall back to "" (decorative) when neither
+    // is provided.
+    image.alt = block.props.caption ? "" : block.props.name || "";
     image.contentEditable = "false";
     image.draggable = false;
     imageWrapper.appendChild(image);
@@ -150,7 +154,10 @@ export const imageToExternalHTML =
     if (block.props.showPreview) {
       image = document.createElement("img");
       image.src = block.props.url;
-      image.alt = block.props.name || block.props.caption || "BlockNote image";
+      // When a caption is set, createFigureWithCaption wraps the image in a
+      // <figure>/<figcaption> below, which serves as the accessible name.
+      // An empty alt avoids screen readers announcing the caption twice.
+      image.alt = block.props.caption ? "" : block.props.name || "";
       if (block.props.previewWidth) {
         image.width = block.props.previewWidth;
       }
diff --git a/packages/react/src/blocks/File/helpers/render/FileBlockWrapper.tsx b/packages/react/src/blocks/File/helpers/render/FileBlockWrapper.tsx
index 6499b40ca0..f277db693f 100644
--- a/packages/react/src/blocks/File/helpers/render/FileBlockWrapper.tsx
+++ b/packages/react/src/blocks/File/helpers/render/FileBlockWrapper.tsx
@@ -29,8 +29,14 @@ export const FileBlockWrapper = (
 ) => {
   const showLoader = useUploadLoading(props.block.id);
 
+  // Use a <figure>/<figcaption> when the block has a caption, so the caption
+  // is semantically associated with its content for assistive tech.
+  const useFigure =
+    props.block.props.url !== "" && !!props.block.props.caption && !showLoader;
+  const Wrapper = useFigure ? "figure" : "div";
+
   return (
-    <div
+    <Wrapper
       className={"bn-file-block-content-wrapper"}
       onMouseEnter={props.onMouseEnter}
       onMouseLeave={props.onMouseLeave}
@@ -54,10 +60,12 @@ export const FileBlockWrapper = (
           )}
           {props.block.props.caption && (
             // Show the caption if there is one.
-            <p className={"bn-file-caption"}>{props.block.props.caption}</p>
+            <figcaption className={"bn-file-caption"}>
+              {props.block.props.caption}
+            </figcaption>
           )}
         </>
       )}
-    </div>
+    </Wrapper>
   );
 };
diff --git a/packages/react/src/blocks/Image/block.tsx b/packages/react/src/blocks/Image/block.tsx
index 92de17d8cc..9718301b1d 100644
--- a/packages/react/src/blocks/Image/block.tsx
+++ b/packages/react/src/blocks/Image/block.tsx
@@ -18,6 +18,10 @@ export const ImagePreview = (
 ) => {
   const resolved = useResolveUrl(props.block.props.url!);
 
+  // When a caption is set, FileBlockWrapper renders a <figcaption> that serves
+  // as the image's accessible name; an empty alt avoids double-announcement.
+  const alt = props.block.props.caption ? "" : props.block.props.name || "";
+
   return (
     <img
       className={"bn-visual-media"}
@@ -26,7 +30,7 @@ export const ImagePreview = (
           ? props.block.props.url
           : resolved.downloadUrl
       }
-      alt={props.block.props.caption || "BlockNote image"}
+      alt={alt}
       contentEditable={false}
       draggable={false}
     />
@@ -43,12 +47,13 @@ export const ImageToExternalHTML = (
     return <p>Add image</p>;
   }
 
+  // When a caption is set, the image is wrapped in <figure>/<figcaption>
+  // below; an empty alt avoids double-announcement of the caption text.
+  const alt = props.block.props.caption ? "" : props.block.props.name || "";
   const image = props.block.props.showPreview ? (
     <img
       src={props.block.props.url}
-      alt={
-        props.block.props.name || props.block.props.caption || "BlockNote image"
-      }
+      alt={alt}
       width={props.block.props.previewWidth}
     />
   ) : (
diff --git a/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/basicBlocksWithProps.html b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/basicBlocksWithProps.html
index 782aab8b66..4cb72b3758 100644
--- a/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/basicBlocksWithProps.html
+++ b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/basicBlocksWithProps.html
@@ -54,7 +54,7 @@ <h2 data-level="2">Heading 1</h2>
 >
   <img
     src="https://upload.wikimedia.org/wikipedia/commons/thumb/3/3f/Placeholder_view_vector.svg/1280px-Placeholder_view_vector.svg.png"
-    alt="1280px-Placeholder_view_vector.svg.png"
+    alt=""
     width="256"
   />
   <figcaption>Placeholder</figcaption>
diff --git a/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/image.html b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/image.html
index 8b48774f5b..dbeb38ec30 100644
--- a/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/image.html
+++ b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/image.html
@@ -1,5 +1,5 @@
 <img
   src="https://ralfvanveen.com/wp-content/uploads/2021/06/Placeholder-_-Glossary.svg"
-  alt="BlockNote image"
+  alt=""
   data-url="https://ralfvanveen.com/wp-content/uploads/2021/06/Placeholder-_-Glossary.svg"
  />
\ No newline at end of file
diff --git a/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/nestedImage.html b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/nestedImage.html
index ece8708071..45b2830cd7 100644
--- a/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/nestedImage.html
+++ b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/nestedImage.html
@@ -1,7 +1,7 @@
 <p>Paragraph 1</p>
 <img
   src="https://ralfvanveen.com/wp-content/uploads/2021/06/Placeholder-_-Glossary.svg"
-  alt="BlockNote image"
+  alt=""
   data-url="https://ralfvanveen.com/wp-content/uploads/2021/06/Placeholder-_-Glossary.svg"
   data-nesting-level="1"
  />
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/basic.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/basic.html
index 9974d8d975..d7802da3e3 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/basic.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/basic.html
@@ -9,7 +9,7 @@
         data-caption="Caption"
         data-file-block=""
       >
-        <div class="bn-file-block-content-wrapper">
+        <figure class="bn-file-block-content-wrapper">
           <div class="bn-file-name-with-icon">
             <div class="bn-file-icon">
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -20,8 +20,8 @@
             </div>
             <p class="bn-file-name">example</p>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/nested.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/nested.html
index 6553a5c4a8..c62486d27d 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/nested.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/nested.html
@@ -9,7 +9,7 @@
         data-caption="Caption"
         data-file-block=""
       >
-        <div class="bn-file-block-content-wrapper">
+        <figure class="bn-file-block-content-wrapper">
           <div class="bn-file-name-with-icon">
             <div class="bn-file-icon">
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -20,8 +20,8 @@
             </div>
             <p class="bn-file-name">example</p>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
       <div class="bn-block-group" data-node-type="blockGroup">
         <div class="bn-block-outer" data-node-type="blockOuter" data-id="2">
@@ -34,7 +34,7 @@
               data-caption="Caption"
               data-file-block=""
             >
-              <div class="bn-file-block-content-wrapper">
+              <figure class="bn-file-block-content-wrapper">
                 <div class="bn-file-name-with-icon">
                   <div class="bn-file-icon">
                     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -45,8 +45,8 @@
                   </div>
                   <p class="bn-file-name">example</p>
                 </div>
-                <p class="bn-file-caption">Caption</p>
-              </div>
+                <figcaption class="bn-file-caption">Caption</figcaption>
+              </figure>
             </div>
           </div>
         </div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/noName.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/noName.html
index 47ae5b3bf9..1ec20af747 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/noName.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/noName.html
@@ -8,7 +8,7 @@
         data-caption="Caption"
         data-file-block=""
       >
-        <div class="bn-file-block-content-wrapper">
+        <figure class="bn-file-block-content-wrapper">
           <div class="bn-file-name-with-icon">
             <div class="bn-file-icon">
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -19,8 +19,8 @@
             </div>
             <p class="bn-file-name"></p>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image.html
index cf93dca684..a17b1d3982 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image.html
@@ -15,7 +15,7 @@
             <img
               class="bn-visual-media"
               src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"
-              alt="BlockNote image"
+              alt=""
               draggable="false"
             />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/basic.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/basic.html
index 5c7411f3ed..1e6591a369 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/basic.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/basic.html
@@ -10,17 +10,17 @@
         data-preview-width="256"
         data-file-block=""
       >
-        <div
+        <figure
           class="bn-file-block-content-wrapper"
           style="position: relative; width: 256px;"
         >
           <div class="bn-visual-media-wrapper">
-            <img class="bn-visual-media" src="exampleURL" alt="example" draggable="false" />
+            <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/nested.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/nested.html
index 7eac772896..a5b2647bec 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/nested.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/nested.html
@@ -9,17 +9,17 @@
         data-preview-width="256"
         data-file-block=""
       >
-        <div
+        <figure
           class="bn-file-block-content-wrapper"
           style="position: relative; width: 256px;"
         >
           <div class="bn-visual-media-wrapper">
-            <img class="bn-visual-media" src="exampleURL" alt="Caption" draggable="false" />
+            <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
       <div class="bn-block-group" data-node-type="blockGroup">
         <div class="bn-block-outer" data-node-type="blockOuter" data-id="2">
@@ -32,17 +32,17 @@
               data-preview-width="256"
               data-file-block=""
             >
-              <div
+              <figure
                 class="bn-file-block-content-wrapper"
                 style="position: relative; width: 256px;"
               >
                 <div class="bn-visual-media-wrapper">
-                  <img class="bn-visual-media" src="exampleURL" alt="Caption" draggable="false" />
+                  <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
                   <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
                   <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
                 </div>
-                <p class="bn-file-caption">Caption</p>
-              </div>
+                <figcaption class="bn-file-caption">Caption</figcaption>
+              </figure>
             </div>
           </div>
         </div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/noName.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/noName.html
index 315d8db293..7032fc34e8 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/noName.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/noName.html
@@ -9,17 +9,17 @@
         data-preview-width="256"
         data-file-block=""
       >
-        <div
+        <figure
           class="bn-file-block-content-wrapper"
           style="position: relative; width: 256px;"
         >
           <div class="bn-visual-media-wrapper">
-            <img class="bn-visual-media" src="exampleURL" alt="Caption" draggable="false" />
+            <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/noPreview.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/noPreview.html
index 3e1f5a6264..59d65f82ae 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/noPreview.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/noPreview.html
@@ -11,7 +11,7 @@
         data-preview-width="256"
         data-file-block=""
       >
-        <div class="bn-file-block-content-wrapper" style="position: relative;">
+        <figure class="bn-file-block-content-wrapper" style="position: relative;">
           <div class="bn-file-name-with-icon">
             <div class="bn-file-icon">
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -22,8 +22,8 @@
             </div>
             <p class="bn-file-name">example</p>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/withCaption.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/withCaption.html
index bca753588e..5292742600 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/withCaption.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/withCaption.html
@@ -9,7 +9,7 @@
         data-caption="This is a caption"
         data-file-block=""
       >
-        <div
+        <figure
           class="bn-file-block-content-wrapper"
           style="position: relative; width: fit-content;"
         >
@@ -17,14 +17,14 @@
             <img
               class="bn-visual-media"
               src="https://example.com/image.png"
-              alt="Example Image"
+              alt=""
               draggable="false"
             />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
-          <p class="bn-file-caption">This is a caption</p>
-        </div>
+          <figcaption class="bn-file-caption">This is a caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/video/withCaption.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/video/withCaption.html
index 9de3da2aca..b85963a4e8 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/video/withCaption.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/video/withCaption.html
@@ -9,7 +9,7 @@
         data-caption="Video caption"
         data-file-block=""
       >
-        <div
+        <figure
           class="bn-file-block-content-wrapper"
           style="position: relative; width: fit-content;"
         >
@@ -24,8 +24,8 @@
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
-          <p class="bn-file-caption">Video caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Video caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image.html b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image.html
index ef7342fe92..a9efaefefc 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image.html
@@ -1,5 +1,5 @@
 <img
   src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"
-  alt="BlockNote image"
+  alt=""
   data-url="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"
  />
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/basic.html b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/basic.html
index 4f365f8d88..0fa5bf338c 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/basic.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/basic.html
@@ -4,6 +4,6 @@
   data-caption="Caption"
   data-preview-width="256"
 >
-  <img src="exampleURL" alt="example" width="256" />
+  <img src="exampleURL" alt="" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/nested.html b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/nested.html
index 04ccf17c56..667cef41ab 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/nested.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/nested.html
@@ -1,5 +1,5 @@
 <figure data-url="exampleURL" data-caption="Caption" data-preview-width="256">
-  <img src="exampleURL" alt="Caption" width="256" />
+  <img src="exampleURL" alt="" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
 <figure
@@ -8,6 +8,6 @@
   data-preview-width="256"
   data-nesting-level="1"
 >
-  <img src="exampleURL" alt="Caption" width="256" />
+  <img src="exampleURL" alt="" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/noName.html b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/noName.html
index 686fc7d4e5..47f0cbe255 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/noName.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/noName.html
@@ -1,4 +1,4 @@
 <figure data-url="exampleURL" data-caption="Caption" data-preview-width="256">
-  <img src="exampleURL" alt="Caption" width="256" />
+  <img src="exampleURL" alt="" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/withCaption.html b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/withCaption.html
index 3ecba73103..3a322f85b0 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/withCaption.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/withCaption.html
@@ -3,6 +3,6 @@
   data-name="Example Image"
   data-caption="This is a caption"
 >
-  <img src="https://example.com/image.png" alt="Example Image" />
+  <img src="https://example.com/image.png" alt="" />
   <figcaption>This is a caption</figcaption>
 </figure>
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image.md b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image.md
index 3219bb9f00..58d07ff1a4 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image.md
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image.md
@@ -1 +1 @@
-![BlockNote image](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)
+![](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/basic.html b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/basic.html
index 9974d8d975..d7802da3e3 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/basic.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/basic.html
@@ -9,7 +9,7 @@
         data-caption="Caption"
         data-file-block=""
       >
-        <div class="bn-file-block-content-wrapper">
+        <figure class="bn-file-block-content-wrapper">
           <div class="bn-file-name-with-icon">
             <div class="bn-file-icon">
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -20,8 +20,8 @@
             </div>
             <p class="bn-file-name">example</p>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/nested.html b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/nested.html
index 6553a5c4a8..c62486d27d 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/nested.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/nested.html
@@ -9,7 +9,7 @@
         data-caption="Caption"
         data-file-block=""
       >
-        <div class="bn-file-block-content-wrapper">
+        <figure class="bn-file-block-content-wrapper">
           <div class="bn-file-name-with-icon">
             <div class="bn-file-icon">
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -20,8 +20,8 @@
             </div>
             <p class="bn-file-name">example</p>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
       <div class="bn-block-group" data-node-type="blockGroup">
         <div class="bn-block-outer" data-node-type="blockOuter" data-id="2">
@@ -34,7 +34,7 @@
               data-caption="Caption"
               data-file-block=""
             >
-              <div class="bn-file-block-content-wrapper">
+              <figure class="bn-file-block-content-wrapper">
                 <div class="bn-file-name-with-icon">
                   <div class="bn-file-icon">
                     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -45,8 +45,8 @@
                   </div>
                   <p class="bn-file-name">example</p>
                 </div>
-                <p class="bn-file-caption">Caption</p>
-              </div>
+                <figcaption class="bn-file-caption">Caption</figcaption>
+              </figure>
             </div>
           </div>
         </div>
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/noName.html b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/noName.html
index 47ae5b3bf9..1ec20af747 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/noName.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactFile/noName.html
@@ -8,7 +8,7 @@
         data-caption="Caption"
         data-file-block=""
       >
-        <div class="bn-file-block-content-wrapper">
+        <figure class="bn-file-block-content-wrapper">
           <div class="bn-file-name-with-icon">
             <div class="bn-file-icon">
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -19,8 +19,8 @@
             </div>
             <p class="bn-file-name"></p>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/basic.html b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/basic.html
index 5c7411f3ed..1e6591a369 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/basic.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/basic.html
@@ -10,17 +10,17 @@
         data-preview-width="256"
         data-file-block=""
       >
-        <div
+        <figure
           class="bn-file-block-content-wrapper"
           style="position: relative; width: 256px;"
         >
           <div class="bn-visual-media-wrapper">
-            <img class="bn-visual-media" src="exampleURL" alt="example" draggable="false" />
+            <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/nested.html b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/nested.html
index 3a0d0d50b0..c26f90e9d4 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/nested.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/nested.html
@@ -10,17 +10,17 @@
         data-preview-width="256"
         data-file-block=""
       >
-        <div
+        <figure
           class="bn-file-block-content-wrapper"
           style="position: relative; width: 256px;"
         >
           <div class="bn-visual-media-wrapper">
-            <img class="bn-visual-media" src="exampleURL" alt="example" draggable="false" />
+            <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
       <div class="bn-block-group" data-node-type="blockGroup">
         <div class="bn-block-outer" data-node-type="blockOuter" data-id="2">
@@ -34,17 +34,17 @@
               data-preview-width="256"
               data-file-block=""
             >
-              <div
+              <figure
                 class="bn-file-block-content-wrapper"
                 style="position: relative; width: 256px;"
               >
                 <div class="bn-visual-media-wrapper">
-                  <img class="bn-visual-media" src="exampleURL" alt="example" draggable="false" />
+                  <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
                   <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
                   <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
                 </div>
-                <p class="bn-file-caption">Caption</p>
-              </div>
+                <figcaption class="bn-file-caption">Caption</figcaption>
+              </figure>
             </div>
           </div>
         </div>
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/noName.html b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/noName.html
index 315d8db293..7032fc34e8 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/noName.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/noName.html
@@ -9,17 +9,17 @@
         data-preview-width="256"
         data-file-block=""
       >
-        <div
+        <figure
           class="bn-file-block-content-wrapper"
           style="position: relative; width: 256px;"
         >
           <div class="bn-visual-media-wrapper">
-            <img class="bn-visual-media" src="exampleURL" alt="Caption" draggable="false" />
+            <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/noPreview.html b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/noPreview.html
index 3e1f5a6264..59d65f82ae 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/noPreview.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/noPreview.html
@@ -11,7 +11,7 @@
         data-preview-width="256"
         data-file-block=""
       >
-        <div class="bn-file-block-content-wrapper" style="position: relative;">
+        <figure class="bn-file-block-content-wrapper" style="position: relative;">
           <div class="bn-file-name-with-icon">
             <div class="bn-file-icon">
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -22,8 +22,8 @@
             </div>
             <p class="bn-file-name">example</p>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/basic.html b/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/basic.html
index 4f365f8d88..0fa5bf338c 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/basic.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/basic.html
@@ -4,6 +4,6 @@
   data-caption="Caption"
   data-preview-width="256"
 >
-  <img src="exampleURL" alt="example" width="256" />
+  <img src="exampleURL" alt="" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
\ No newline at end of file
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/nested.html b/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/nested.html
index 8dfc8061ff..a9fa90407d 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/nested.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/nested.html
@@ -4,7 +4,7 @@
   data-caption="Caption"
   data-preview-width="256"
 >
-  <img src="exampleURL" alt="example" width="256" />
+  <img src="exampleURL" alt="" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
 <figure
@@ -14,6 +14,6 @@
   data-preview-width="256"
   data-nesting-level="1"
 >
-  <img src="exampleURL" alt="example" width="256" />
+  <img src="exampleURL" alt="" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
\ No newline at end of file
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/noName.html b/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/noName.html
index 686fc7d4e5..47f0cbe255 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/noName.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/noName.html
@@ -1,4 +1,4 @@
 <figure data-url="exampleURL" data-caption="Caption" data-preview-width="256">
-  <img src="exampleURL" alt="Caption" width="256" />
+  <img src="exampleURL" alt="" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
\ No newline at end of file

From 28991e20bc21c954d0803238015d0303117923e8 Mon Sep 17 00:00:00 2001
From: Nick the Sick <computers@nickthesick.com>
Date: Wed, 6 May 2026 19:12:42 +0200
Subject: [PATCH 2/2] fix(a11y): reset figure default margins; refresh
 server-util snapshots
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two CI fixes for #2717:

- Block.css: add `margin: 0` to .bn-file-block-content-wrapper so the
  wrapper looks identical whether it renders as <figure> (captioned)
  or <div> (uncaptioned). Browser default <figure> margin is `1em 40px`,
  whereas the previous <div>+<p class="bn-file-caption"> structure had
  the <p> margins reset by .bn-default-styles. Without this reset the
  captioned-image visual snapshot grew by ~50px.
- server-util/ServerBlockNoteEditor.test.ts.snap: refresh — these
  snapshots cover the full HTML/markdown round-trip and were missed
  in the previous snapshot pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/core/src/blocks/Image/block.ts            | 14 +++++---------
 packages/core/src/editor/Block.css                 |  3 +++
 packages/react/src/blocks/Image/block.tsx          | 11 +++++------
 .../ServerBlockNoteEditor.test.ts.snap             |  2 +-
 .../text/html/basicBlocksWithProps.html            |  2 +-
 .../__snapshots__/blocknoteHTML/image/basic.html   |  2 +-
 .../__snapshots__/blocknoteHTML/image/urlOnly.html |  7 +------
 .../blocknoteHTML/image/withCaption.html           |  2 +-
 .../export/__snapshots__/html/image/basic.html     |  2 +-
 .../export/__snapshots__/html/image/urlOnly.html   |  2 +-
 .../__snapshots__/html/image/withCaption.html      |  2 +-
 .../export/__snapshots__/markdown/image/urlOnly.md |  2 +-
 .../blocknoteHTML/reactImage/basic.html            |  2 +-
 .../blocknoteHTML/reactImage/nested.html           |  4 ++--
 .../__snapshots__/html/reactImage/basic.html       |  2 +-
 .../__snapshots__/html/reactImage/nested.html      |  4 ++--
 16 files changed, 28 insertions(+), 35 deletions(-)

diff --git a/packages/core/src/blocks/Image/block.ts b/packages/core/src/blocks/Image/block.ts
index fc6d4b3377..9de973bb49 100644
--- a/packages/core/src/blocks/Image/block.ts
+++ b/packages/core/src/blocks/Image/block.ts
@@ -116,11 +116,10 @@ export const imageRender =
       image.src = block.props.url;
     }
 
-    // When a caption is set, the wrapper renders a <figcaption> that serves as
-    // the image's accessible name, so an empty alt avoids double-announcement.
-    // Otherwise prefer the file name; fall back to "" (decorative) when neither
-    // is provided.
-    image.alt = block.props.caption ? "" : block.props.name || "";
+    // alt describes image content (per WCAG H86); figcaption (when present)
+    // is the contextual caption. Fall back to "" so unlabelled images are
+    // marked decorative rather than getting a noisy generic fallback.
+    image.alt = block.props.name || "";
     image.contentEditable = "false";
     image.draggable = false;
     imageWrapper.appendChild(image);
@@ -154,10 +153,7 @@ export const imageToExternalHTML =
     if (block.props.showPreview) {
       image = document.createElement("img");
       image.src = block.props.url;
-      // When a caption is set, createFigureWithCaption wraps the image in a
-      // <figure>/<figcaption> below, which serves as the accessible name.
-      // An empty alt avoids screen readers announcing the caption twice.
-      image.alt = block.props.caption ? "" : block.props.name || "";
+      image.alt = block.props.name || "";
       if (block.props.previewWidth) {
         image.width = block.props.previewWidth;
       }
diff --git a/packages/core/src/editor/Block.css b/packages/core/src/editor/Block.css
index bba397ee58..990a856504 100644
--- a/packages/core/src/editor/Block.css
+++ b/packages/core/src/editor/Block.css
@@ -468,6 +468,9 @@ NESTED BLOCKS
   cursor: pointer;
   display: flex;
   flex-direction: column;
+  /* Reset default <figure> browser margins (the wrapper becomes a <figure>
+     when the block has a caption). */
+  margin: 0;
   user-select: none;
 }
 
diff --git a/packages/react/src/blocks/Image/block.tsx b/packages/react/src/blocks/Image/block.tsx
index 9718301b1d..be682b47c2 100644
--- a/packages/react/src/blocks/Image/block.tsx
+++ b/packages/react/src/blocks/Image/block.tsx
@@ -18,9 +18,10 @@ export const ImagePreview = (
 ) => {
   const resolved = useResolveUrl(props.block.props.url!);
 
-  // When a caption is set, FileBlockWrapper renders a <figcaption> that serves
-  // as the image's accessible name; an empty alt avoids double-announcement.
-  const alt = props.block.props.caption ? "" : props.block.props.name || "";
+  // alt describes image content (per WCAG H86); figcaption (when present)
+  // is the contextual caption. Fall back to "" so unlabelled images are
+  // marked decorative rather than getting a noisy generic fallback.
+  const alt = props.block.props.name || "";
 
   return (
     <img
@@ -47,9 +48,7 @@ export const ImageToExternalHTML = (
     return <p>Add image</p>;
   }
 
-  // When a caption is set, the image is wrapped in <figure>/<figcaption>
-  // below; an empty alt avoids double-announcement of the caption text.
-  const alt = props.block.props.caption ? "" : props.block.props.name || "";
+  const alt = props.block.props.name || "";
   const image = props.block.props.showPreview ? (
     <img
       src={props.block.props.url}
diff --git a/packages/server-util/src/context/__snapshots__/ServerBlockNoteEditor.test.ts.snap b/packages/server-util/src/context/__snapshots__/ServerBlockNoteEditor.test.ts.snap
index 6600cd0ead..777d7a773f 100644
--- a/packages/server-util/src/context/__snapshots__/ServerBlockNoteEditor.test.ts.snap
+++ b/packages/server-util/src/context/__snapshots__/ServerBlockNoteEditor.test.ts.snap
@@ -1,6 +1,6 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Test ServerBlockNoteEditor > converts to HTML (blocksToFullHTML) 1`] = `"<div class="bn-block-group" data-node-type="blockGroup"><div class="bn-block-outer" data-node-type="blockOuter" data-id="1"><div class="bn-block" data-node-type="blockContainer" data-id="1"><div class="bn-block-content" data-content-type="heading" data-background-color="blue" data-text-color="yellow" data-text-alignment="right" data-level="2"><h2 class="bn-inline-content"><strong><u>Heading </u></strong><em><s>2</s></em></h2></div><div class="bn-block-group" data-node-type="blockGroup"><div class="bn-block-outer" data-node-type="blockOuter" data-id="2"><div class="bn-block" data-node-type="blockContainer" data-id="2"><div class="bn-block-content" data-content-type="paragraph" data-background-color="red"><p class="bn-inline-content">Paragraph</p></div></div></div><div class="bn-block-outer" data-node-type="blockOuter" data-id="3"><div class="bn-block" data-node-type="blockContainer" data-id="3"><div class="bn-block-content" data-content-type="bulletListItem"><p class="bn-inline-content">list item</p></div></div></div></div></div></div><div class="bn-block-outer" data-node-type="blockOuter" data-id="4"><div class="bn-block" data-node-type="blockContainer" data-id="4"><div class="bn-block-content" data-content-type="image" data-name="Example" data-url="exampleURL" data-caption="Caption" data-preview-width="256" data-file-block=""><div class="bn-file-block-content-wrapper" style="position: relative; width: 256px;"><div class="bn-visual-media-wrapper"><img class="bn-visual-media" src="exampleURL" alt="Example" draggable="false"><div class="bn-resize-handle" style="left: 4px; display: none;"></div><div class="bn-resize-handle" style="right: 4px; display: none;"></div></div><p class="bn-file-caption">Caption</p></div></div></div></div><div class="bn-block-outer" data-node-type="blockOuter" data-id="5"><div class="bn-block" data-node-type="blockContainer" data-id="5"><div class="bn-block-content" data-content-type="image" data-name="Example" data-url="exampleURL" data-caption="Caption" data-show-preview="false" data-preview-width="256" data-file-block=""><div class="bn-file-block-content-wrapper" style="position: relative;"><div class="bn-file-name-with-icon"><div class="bn-file-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M3 8L9.00319 2H19.9978C20.5513 2 21 2.45531 21 2.9918V21.0082C21 21.556 20.5551 22 20.0066 22H3.9934C3.44476 22 3 21.5501 3 20.9932V8ZM10 4V9H5V20H19V4H10Z"></path></svg></div><p class="bn-file-name">Example</p></div><p class="bn-file-caption">Caption</p></div></div></div></div></div>"`;
+exports[`Test ServerBlockNoteEditor > converts to HTML (blocksToFullHTML) 1`] = `"<div class="bn-block-group" data-node-type="blockGroup"><div class="bn-block-outer" data-node-type="blockOuter" data-id="1"><div class="bn-block" data-node-type="blockContainer" data-id="1"><div class="bn-block-content" data-content-type="heading" data-background-color="blue" data-text-color="yellow" data-text-alignment="right" data-level="2"><h2 class="bn-inline-content"><strong><u>Heading </u></strong><em><s>2</s></em></h2></div><div class="bn-block-group" data-node-type="blockGroup"><div class="bn-block-outer" data-node-type="blockOuter" data-id="2"><div class="bn-block" data-node-type="blockContainer" data-id="2"><div class="bn-block-content" data-content-type="paragraph" data-background-color="red"><p class="bn-inline-content">Paragraph</p></div></div></div><div class="bn-block-outer" data-node-type="blockOuter" data-id="3"><div class="bn-block" data-node-type="blockContainer" data-id="3"><div class="bn-block-content" data-content-type="bulletListItem"><p class="bn-inline-content">list item</p></div></div></div></div></div></div><div class="bn-block-outer" data-node-type="blockOuter" data-id="4"><div class="bn-block" data-node-type="blockContainer" data-id="4"><div class="bn-block-content" data-content-type="image" data-name="Example" data-url="exampleURL" data-caption="Caption" data-preview-width="256" data-file-block=""><figure class="bn-file-block-content-wrapper" style="position: relative; width: 256px;"><div class="bn-visual-media-wrapper"><img class="bn-visual-media" src="exampleURL" alt="Example" draggable="false"><div class="bn-resize-handle" style="left: 4px; display: none;"></div><div class="bn-resize-handle" style="right: 4px; display: none;"></div></div><figcaption class="bn-file-caption">Caption</figcaption></figure></div></div></div><div class="bn-block-outer" data-node-type="blockOuter" data-id="5"><div class="bn-block" data-node-type="blockContainer" data-id="5"><div class="bn-block-content" data-content-type="image" data-name="Example" data-url="exampleURL" data-caption="Caption" data-show-preview="false" data-preview-width="256" data-file-block=""><figure class="bn-file-block-content-wrapper" style="position: relative;"><div class="bn-file-name-with-icon"><div class="bn-file-icon"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M3 8L9.00319 2H19.9978C20.5513 2 21 2.45531 21 2.9918V21.0082C21 21.556 20.5551 22 20.0066 22H3.9934C3.44476 22 3 21.5501 3 20.9932V8ZM10 4V9H5V20H19V4H10Z"></path></svg></div><p class="bn-file-name">Example</p></div><figcaption class="bn-file-caption">Caption</figcaption></figure></div></div></div></div>"`;
 
 exports[`Test ServerBlockNoteEditor > converts to and from HTML (blocksToHTMLLossy) 1`] = `"<h2 style="background-color: rgb(221, 235, 241); color: rgb(223, 171, 1); text-align: right;" data-background-color="blue" data-text-color="yellow" data-text-alignment="right" data-level="2"><strong><u>Heading </u></strong><em><s>2</s></em></h2><p style="background-color: rgb(251, 228, 228);" data-background-color="red" data-nesting-level="1">Paragraph</p><ul><li data-nesting-level="1"><p class="bn-inline-content">list item</p></li></ul><figure data-name="Example" data-url="exampleURL" data-caption="Caption" data-preview-width="256"><img src="exampleURL" alt="Example" width="256"><figcaption>Caption</figcaption></figure><div data-name="Example" data-url="exampleURL" data-caption="Caption" data-show-preview="false" data-preview-width="256"><a href="exampleURL">Example</a><p>Caption</p></div>"`;
 
diff --git a/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/basicBlocksWithProps.html b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/basicBlocksWithProps.html
index 4cb72b3758..782aab8b66 100644
--- a/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/basicBlocksWithProps.html
+++ b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/basicBlocksWithProps.html
@@ -54,7 +54,7 @@ <h2 data-level="2">Heading 1</h2>
 >
   <img
     src="https://upload.wikimedia.org/wikipedia/commons/thumb/3/3f/Placeholder_view_vector.svg/1280px-Placeholder_view_vector.svg.png"
-    alt=""
+    alt="1280px-Placeholder_view_vector.svg.png"
     width="256"
   />
   <figcaption>Placeholder</figcaption>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/basic.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/basic.html
index 1e6591a369..55c9555506 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/basic.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/basic.html
@@ -15,7 +15,7 @@
           style="position: relative; width: 256px;"
         >
           <div class="bn-visual-media-wrapper">
-            <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
+            <img class="bn-visual-media" src="exampleURL" alt="example" draggable="false" />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/urlOnly.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/urlOnly.html
index f529f9e2bb..6940729386 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/urlOnly.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/urlOnly.html
@@ -12,12 +12,7 @@
           style="position: relative; width: fit-content;"
         >
           <div class="bn-visual-media-wrapper">
-            <img
-              class="bn-visual-media"
-              src="exampleURL"
-              alt="BlockNote image"
-              draggable="false"
-            />
+            <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/withCaption.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/withCaption.html
index 5292742600..5844c98607 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/withCaption.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/withCaption.html
@@ -17,7 +17,7 @@
             <img
               class="bn-visual-media"
               src="https://example.com/image.png"
-              alt=""
+              alt="Example Image"
               draggable="false"
             />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/basic.html b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/basic.html
index 0fa5bf338c..4f365f8d88 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/basic.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/basic.html
@@ -4,6 +4,6 @@
   data-caption="Caption"
   data-preview-width="256"
 >
-  <img src="exampleURL" alt="" width="256" />
+  <img src="exampleURL" alt="example" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/urlOnly.html b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/urlOnly.html
index 80685a3c89..41960a99f8 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/urlOnly.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/urlOnly.html
@@ -1 +1 @@
-<img src="exampleURL" alt="BlockNote image" data-url="exampleURL" />
\ No newline at end of file
+<img src="exampleURL" alt="" data-url="exampleURL" />
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/withCaption.html b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/withCaption.html
index 3a322f85b0..3ecba73103 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/withCaption.html
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/withCaption.html
@@ -3,6 +3,6 @@
   data-name="Example Image"
   data-caption="This is a caption"
 >
-  <img src="https://example.com/image.png" alt="" />
+  <img src="https://example.com/image.png" alt="Example Image" />
   <figcaption>This is a caption</figcaption>
 </figure>
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/urlOnly.md b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/urlOnly.md
index dcf874d74c..f667f8e031 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/urlOnly.md
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/urlOnly.md
@@ -1 +1 @@
-![BlockNote image](exampleURL)
+![](exampleURL)
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/basic.html b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/basic.html
index 1e6591a369..55c9555506 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/basic.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/basic.html
@@ -15,7 +15,7 @@
           style="position: relative; width: 256px;"
         >
           <div class="bn-visual-media-wrapper">
-            <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
+            <img class="bn-visual-media" src="exampleURL" alt="example" draggable="false" />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/nested.html b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/nested.html
index c26f90e9d4..a6296f823b 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/nested.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/blocknoteHTML/reactImage/nested.html
@@ -15,7 +15,7 @@
           style="position: relative; width: 256px;"
         >
           <div class="bn-visual-media-wrapper">
-            <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
+            <img class="bn-visual-media" src="exampleURL" alt="example" draggable="false" />
             <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
             <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
           </div>
@@ -39,7 +39,7 @@
                 style="position: relative; width: 256px;"
               >
                 <div class="bn-visual-media-wrapper">
-                  <img class="bn-visual-media" src="exampleURL" alt="" draggable="false" />
+                  <img class="bn-visual-media" src="exampleURL" alt="example" draggable="false" />
                   <div class="bn-resize-handle" style="left: 4px; display: none;"></div>
                   <div class="bn-resize-handle" style="right: 4px; display: none;"></div>
                 </div>
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/basic.html b/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/basic.html
index 0fa5bf338c..4f365f8d88 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/basic.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/basic.html
@@ -4,6 +4,6 @@
   data-caption="Caption"
   data-preview-width="256"
 >
-  <img src="exampleURL" alt="" width="256" />
+  <img src="exampleURL" alt="example" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
\ No newline at end of file
diff --git a/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/nested.html b/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/nested.html
index a9fa90407d..8dfc8061ff 100644
--- a/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/nested.html
+++ b/tests/src/unit/react/formatConversion/export/__snapshots__/html/reactImage/nested.html
@@ -4,7 +4,7 @@
   data-caption="Caption"
   data-preview-width="256"
 >
-  <img src="exampleURL" alt="" width="256" />
+  <img src="exampleURL" alt="example" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
 <figure
@@ -14,6 +14,6 @@
   data-preview-width="256"
   data-nesting-level="1"
 >
-  <img src="exampleURL" alt="" width="256" />
+  <img src="exampleURL" alt="example" width="256" />
   <figcaption>Caption</figcaption>
 </figure>
\ No newline at end of file