From 9d81c2e349f2ef99d58e9210fbc7b9829e3de080 Mon Sep 17 00:00:00 2001
From: Nick the Sick <computers@nickthesick.com>
Date: Thu, 7 May 2026 06:18:02 +0200
Subject: [PATCH 1/4] fix(markdown): stable round-trip for tables, captions,
 and audio
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Headerless tables no longer grow an empty row each save (#739): emit no
  `<thead>` when every header cell is blank.
- Image/video captions now round-trip via raw `<figure>`+`<figcaption>` HTML
  so the `caption` prop is preserved (and not duplicated as a stray
  paragraph below the image). The descriptor (alt / data-name) is dropped
  when it would duplicate the caption text.
- Audio blocks serialize to raw `<audio>` HTML instead of `[](url)` link
  syntax, so they round-trip back into an audio block instead of being
  lost as a link.
- Markdown video parser routes alt text into `data-name` and
  `parseVideoElement` reads it back, mirroring image alt → name.
- `audio` added to HTML block-tag set so a standalone `<audio>` line is
  recognized as a block.
- Adds round-trip snapshot tests covering all default blocks
  (`markdown/defaultBlocks`), tables with header rows
  (`markdown/tableWithHeaderRow`), and the no-name/no-caption image case
  (`image/urlOnly`).
---
 .../api/exporters/markdown/htmlToMarkdown.ts  | 104 +++-
 .../api/parsers/markdown/markdownToHtml.ts    |  57 ++-
 .../src/blocks/Video/parseVideoElement.ts     |   3 +-
 .../blocknoteHTML/image/urlOnly.html          |  28 ++
 .../__snapshots__/html/image/urlOnly.html     |   1 +
 .../__snapshots__/markdown/audio/basic.md     |   2 +-
 .../__snapshots__/markdown/audio/noName.md    |   2 +-
 .../__snapshots__/markdown/image/basic.md     |   4 +-
 .../__snapshots__/markdown/image/nested.md    |   8 +-
 .../__snapshots__/markdown/image/noName.md    |   4 +-
 .../__snapshots__/markdown/image/urlOnly.md   |   1 +
 .../markdown/image/withCaption.md             |   4 +-
 .../markdown/video/withCaption.md             |   4 +-
 .../__snapshots__/nodes/image/urlOnly.json    |  22 +
 .../export/exportTestInstances.ts             |  17 +
 .../markdown/markdown/defaultBlocks.json      | 474 ++++++++++++++++++
 .../markdown/markdown/table.json              |  28 +-
 .../markdown/markdown/tableWithHeaderRow.json |  97 ++++
 .../markdown/markdown/video.json              |   2 +-
 .../exportParseEqualityTestInstances.ts       | 162 ++++++
 .../parse/__snapshots__/markdown/video.json   |   2 +-
 21 files changed, 931 insertions(+), 95 deletions(-)
 create mode 100644 tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/urlOnly.html
 create mode 100644 tests/src/unit/core/formatConversion/export/__snapshots__/html/image/urlOnly.html
 create mode 100644 tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/urlOnly.md
 create mode 100644 tests/src/unit/core/formatConversion/export/__snapshots__/nodes/image/urlOnly.json
 create mode 100644 tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/defaultBlocks.json
 create mode 100644 tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/tableWithHeaderRow.json

diff --git a/packages/core/src/api/exporters/markdown/htmlToMarkdown.ts b/packages/core/src/api/exporters/markdown/htmlToMarkdown.ts
index da63166851..7faa154dc6 100644
--- a/packages/core/src/api/exporters/markdown/htmlToMarkdown.ts
+++ b/packages/core/src/api/exporters/markdown/htmlToMarkdown.ts
@@ -520,8 +520,10 @@ function serializeVideo(el: HTMLElement, ctx: SerializeContext): string {
 function serializeAudio(el: HTMLElement, ctx: SerializeContext): string {
   const src = el.getAttribute("src") || "";
   if (!src) {return "\n\n";}
-  // Audio has no visible representation in markdown; output as link with empty text
-  return ctx.indent + `[](${src})\n\n`;
+  // Audio has no markdown syntax, so emit raw HTML. The markdown parser
+  // passes <audio> blocks through verbatim and BlockNote's audio block parser
+  // recognizes them, giving a clean round-trip.
+  return ctx.indent + `<audio src="${escapeHtmlAttr(src)}" controls></audio>\n\n`;
 }
 
 function serializeEmbed(el: HTMLElement, ctx: SerializeContext): string {
@@ -531,41 +533,97 @@ function serializeEmbed(el: HTMLElement, ctx: SerializeContext): string {
 }
 
 function serializeFigure(el: HTMLElement, ctx: SerializeContext): string {
-  let result = "";
-
-  // Find the media element
   const img = el.querySelector("img");
   const video = el.querySelector("video");
   const audio = el.querySelector("audio");
   const link = el.querySelector("a");
 
+  const figcaption = el.querySelector("figcaption");
+  const captionText = figcaption?.textContent?.trim() || "";
+
   if (img) {
-    const src = img.getAttribute("src") || "";
-    const alt = img.getAttribute("alt") || "";
-    result += ctx.indent + `![${alt}](${src})\n\n`;
-  } else if (video) {
+    return serializeMediaFigure(
+      "img",
+      img.getAttribute("src") || "",
+      img.getAttribute("alt") || "",
+      captionText,
+      ctx,
+    );
+  }
+  if (video) {
     const src =
       video.getAttribute("src") || video.getAttribute("data-url") || "";
     const name =
       video.getAttribute("data-name") || video.getAttribute("title") || "";
-    result += ctx.indent + `![${name}](${src})\n\n`;
-  } else if (audio) {
-    const src = audio.getAttribute("src") || "";
-    result += ctx.indent + `[](${src})\n\n`;
-  } else if (link) {
-    result += serializeBlockLink(link as HTMLElement, ctx);
+    return serializeMediaFigure("video", src, name, captionText, ctx);
+  }
+  if (audio) {
+    return serializeMediaFigure(
+      "audio",
+      audio.getAttribute("src") || "",
+      "",
+      captionText,
+      ctx,
+    );
+  }
+  if (link) {
+    return serializeBlockLink(link as HTMLElement, ctx);
   }
+  return "";
+}
 
-  // Caption
-  const figcaption = el.querySelector("figcaption");
-  if (figcaption) {
-    const caption = figcaption.textContent?.trim() || "";
-    if (caption) {
-      result += ctx.indent + caption + "\n\n";
-    }
+function serializeMediaFigure(
+  kind: "img" | "video" | "audio",
+  src: string,
+  descriptor: string,
+  captionText: string,
+  ctx: SerializeContext,
+): string {
+  if (!src) {return "";}
+
+  // No caption + has a markdown shorthand → use it.
+  if (!captionText && kind !== "audio") {
+    return ctx.indent + `![${descriptor}](${src})\n\n`;
   }
 
-  return result;
+  // The descriptor (alt / data-name) is dropped when it duplicates the
+  // caption text; otherwise on round-trip both `name` and `caption` would
+  // get set to the same string (BlockNote's HTML exporter writes alt =
+  // name || caption, so a caption-only image has alt === figcaption text).
+  const showDescriptor = descriptor && descriptor !== captionText;
+  const descAttr =
+    !showDescriptor
+      ? ""
+      : kind === "img"
+        ? ` alt="${escapeHtmlAttr(descriptor)}"`
+        : kind === "video"
+          ? ` data-name="${escapeHtmlAttr(descriptor)}"`
+          : "";
+
+  const tag =
+    kind === "img"
+      ? `<img${descAttr} src="${escapeHtmlAttr(src)}">`
+      : `<${kind} src="${escapeHtmlAttr(src)}"${descAttr} controls></${kind}>`;
+
+  const captionPart = captionText
+    ? `<figcaption>${escapeHtmlText(captionText)}</figcaption>`
+    : "";
+  return ctx.indent + `<figure>${tag}${captionPart}</figure>\n\n`;
+}
+
+function escapeHtmlAttr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function escapeHtmlText(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
 }
 
 function serializeBlockLink(el: HTMLElement, ctx: SerializeContext): string {
diff --git a/packages/core/src/api/parsers/markdown/markdownToHtml.ts b/packages/core/src/api/parsers/markdown/markdownToHtml.ts
index 450f403ea6..6cf94bf4b8 100644
--- a/packages/core/src/api/parsers/markdown/markdownToHtml.ts
+++ b/packages/core/src/api/parsers/markdown/markdownToHtml.ts
@@ -321,9 +321,13 @@ function parseImage(
   );
 
   if (isVideoUrl(url)) {
-    // Match remark-rehype behavior: data-name comes from the title, not alt
+    // Use the alt text as the video's display name (falling back to the
+    // title) so a video link written with the standard `![name](url)` form
+    // round-trips into BlockNote's video block. Captioned videos go through
+    // raw `<figure>` HTML instead, see htmlToMarkdown.serializeMediaFigure.
+    const name = alt || title;
     return {
-      html: `<video src="${escapeHtml(url)}"${title !== undefined ? ` data-name="${escapeHtml(title)}"` : ""} data-url="${escapeHtml(url)}" controls></video>`,
+      html: `<video src="${escapeHtml(url)}"${name ? ` data-name="${escapeHtml(name)}"` : ""} data-url="${escapeHtml(url)}" controls></video>`,
       end: parenEnd + 1,
     };
   }
@@ -573,19 +577,21 @@ type Token =
   | RawHtmlToken;
 
 /**
- * HTML block-level tag names (from the CommonMark type-6 list). When a line
- * starts with `<` followed by one of these tag names, the run of non-blank
- * lines is emitted verbatim as raw HTML rather than wrapped in a paragraph.
+ * HTML block-level tag names (from the CommonMark type-6 list, plus `audio`
+ * which BlockNote serializes as raw HTML since markdown has no shorthand
+ * for it). When a line starts with `<` followed by one of these tag names,
+ * the run of non-blank lines is emitted verbatim as raw HTML rather than
+ * wrapped in a paragraph.
  */
 const HTML_BLOCK_TAGS = new Set([
-  "address", "article", "aside", "base", "basefont", "blockquote", "body",
-  "caption", "center", "col", "colgroup", "dd", "details", "dialog", "dir",
-  "div", "dl", "dt", "fieldset", "figcaption", "figure", "footer", "form",
-  "frame", "frameset", "h1", "h2", "h3", "h4", "h5", "h6", "head", "header",
-  "hr", "html", "iframe", "legend", "li", "link", "main", "menu", "menuitem",
-  "nav", "noframes", "ol", "optgroup", "option", "p", "param", "section",
-  "source", "summary", "table", "tbody", "td", "tfoot", "th", "thead",
-  "title", "tr", "track", "ul",
+  "address", "article", "aside", "audio", "base", "basefont", "blockquote",
+  "body", "caption", "center", "col", "colgroup", "dd", "details", "dialog",
+  "dir", "div", "dl", "dt", "fieldset", "figcaption", "figure", "footer",
+  "form", "frame", "frameset", "h1", "h2", "h3", "h4", "h5", "h6", "head",
+  "header", "hr", "html", "iframe", "legend", "li", "link", "main", "menu",
+  "menuitem", "nav", "noframes", "ol", "optgroup", "option", "p", "param",
+  "section", "source", "summary", "table", "tbody", "td", "tfoot", "th",
+  "thead", "title", "tr", "track", "ul",
 ]);
 
 function isHtmlBlockStart(line: string): boolean {
@@ -1140,21 +1146,28 @@ function getEffectiveListType(
 function emitTable(table: TableToken): string {
   let html = "<table>";
 
-  // Header row
-  html += "<thead><tr>";
-  for (let c = 0; c < table.headers.length; c++) {
-    const align = table.alignments[c];
-    const alignAttr = align ? ` align="${align}"` : "";
-    html += `<th${alignAttr}>${parseInline(table.headers[c])}</th>`;
+  // BlockNote tables have no required header row, but the markdown table
+  // syntax does. When we serialize a headerless BlockNote table to markdown
+  // we emit an empty header row; on re-parse, treat that empty header as
+  // "no header" so the round-trip is stable (issue #739).
+  const headerIsEmpty = table.headers.every((h) => h.trim() === "");
+  const colCount = table.headers.length;
+
+  if (!headerIsEmpty) {
+    html += "<thead><tr>";
+    for (let c = 0; c < colCount; c++) {
+      const align = table.alignments[c];
+      const alignAttr = align ? ` align="${align}"` : "";
+      html += `<th${alignAttr}>${parseInline(table.headers[c])}</th>`;
+    }
+    html += "</tr></thead>";
   }
-  html += "</tr></thead>";
 
-  // Body rows
   if (table.rows.length > 0) {
     html += "<tbody>";
     for (const row of table.rows) {
       html += "<tr>";
-      for (let c = 0; c < table.headers.length; c++) {
+      for (let c = 0; c < colCount; c++) {
         const cell = c < row.length ? row[c] : "";
         const align = table.alignments[c];
         const alignAttr = align ? ` align="${align}"` : "";
diff --git a/packages/core/src/blocks/Video/parseVideoElement.ts b/packages/core/src/blocks/Video/parseVideoElement.ts
index 4b11481d48..7852866d4b 100644
--- a/packages/core/src/blocks/Video/parseVideoElement.ts
+++ b/packages/core/src/blocks/Video/parseVideoElement.ts
@@ -1,6 +1,7 @@
 export const parseVideoElement = (videoElement: HTMLVideoElement) => {
   const url = videoElement.src || undefined;
   const previewWidth = videoElement.width || undefined;
+  const name = videoElement.getAttribute("data-name") || undefined;
 
-  return { url, previewWidth };
+  return { url, previewWidth, name };
 };
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
new file mode 100644
index 0000000000..f529f9e2bb
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/image/urlOnly.html
@@ -0,0 +1,28 @@
+<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="image"
+        data-url="exampleURL"
+        data-file-block=""
+      >
+        <div
+          class="bn-file-block-content-wrapper"
+          style="position: relative; width: fit-content;"
+        >
+          <div class="bn-visual-media-wrapper">
+            <img
+              class="bn-visual-media"
+              src="exampleURL"
+              alt="BlockNote image"
+              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>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
\ 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
new file mode 100644
index 0000000000..80685a3c89
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/image/urlOnly.html
@@ -0,0 +1 @@
+<img src="exampleURL" alt="BlockNote image" data-url="exampleURL" />
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/audio/basic.md b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/audio/basic.md
index b459dbd5a9..cdcf0dde54 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/audio/basic.md
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/audio/basic.md
@@ -1 +1 @@
-[](https://example.com/audio.mp3)
+<audio src="https://example.com/audio.mp3" controls></audio>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/audio/noName.md b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/audio/noName.md
index b459dbd5a9..cdcf0dde54 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/audio/noName.md
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/audio/noName.md
@@ -1 +1 @@
-[](https://example.com/audio.mp3)
+<audio src="https://example.com/audio.mp3" controls></audio>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/basic.md b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/basic.md
index b350ae21e0..5a88869a1b 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/basic.md
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/basic.md
@@ -1,3 +1 @@
-![example](exampleURL)
-
-Caption
+<figure><img alt="example" src="exampleURL"><figcaption>Caption</figcaption></figure>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/nested.md b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/nested.md
index 7a13551364..99ff1825d4 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/nested.md
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/nested.md
@@ -1,7 +1,3 @@
-![Caption](exampleURL)
+<figure><img src="exampleURL"><figcaption>Caption</figcaption></figure>
 
-Caption
-
-![Caption](exampleURL)
-
-Caption
+<figure><img src="exampleURL"><figcaption>Caption</figcaption></figure>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/noName.md b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/noName.md
index c6b5864d90..ba1c350f13 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/noName.md
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/noName.md
@@ -1,3 +1 @@
-![Caption](exampleURL)
-
-Caption
+<figure><img src="exampleURL"><figcaption>Caption</figcaption></figure>
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
new file mode 100644
index 0000000000..dcf874d74c
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/urlOnly.md
@@ -0,0 +1 @@
+![BlockNote image](exampleURL)
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/withCaption.md b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/withCaption.md
index d68bd090a4..fb8426fd87 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/withCaption.md
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/image/withCaption.md
@@ -1,3 +1 @@
-![Example Image](https://example.com/image.png)
-
-This is a caption
+<figure><img alt="Example Image" src="https://example.com/image.png"><figcaption>This is a caption</figcaption></figure>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/video/withCaption.md b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/video/withCaption.md
index 3f50812477..78cb313b4b 100644
--- a/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/video/withCaption.md
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/markdown/video/withCaption.md
@@ -1,3 +1 @@
-![](https://example.com/video.mp4)
-
-Video caption
+<figure><video src="https://example.com/video.mp4" controls></video><figcaption>Video caption</figcaption></figure>
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/nodes/image/urlOnly.json b/tests/src/unit/core/formatConversion/export/__snapshots__/nodes/image/urlOnly.json
new file mode 100644
index 0000000000..3d56a77d23
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/nodes/image/urlOnly.json
@@ -0,0 +1,22 @@
+[
+  {
+    "attrs": {
+      "id": "1",
+    },
+    "content": [
+      {
+        "attrs": {
+          "backgroundColor": "default",
+          "caption": "",
+          "name": "",
+          "previewWidth": undefined,
+          "showPreview": true,
+          "textAlignment": "left",
+          "url": "exampleURL",
+        },
+        "type": "image",
+      },
+    ],
+    "type": "blockContainer",
+  },
+]
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/exportTestInstances.ts b/tests/src/unit/core/formatConversion/export/exportTestInstances.ts
index e30cea7272..bd8cb77493 100644
--- a/tests/src/unit/core/formatConversion/export/exportTestInstances.ts
+++ b/tests/src/unit/core/formatConversion/export/exportTestInstances.ts
@@ -1101,6 +1101,23 @@ export const exportTestInstancesBlockNoteHTML: TestInstance<
     },
     executeTest: testExportBlockNoteHTML,
   },
+  {
+    // Image with only a URL — no name, no caption. Confirms markdown export
+    // stays as plain `![](url)` without wrapping in a `<figure>` (the figure
+    // form is only used to carry caption text through the round-trip).
+    testCase: {
+      name: "image/urlOnly",
+      content: [
+        {
+          type: "image",
+          props: {
+            url: "exampleURL",
+          },
+        },
+      ],
+    },
+    executeTest: testExportBlockNoteHTML,
+  },
   {
     testCase: {
       name: "image/noPreview",
diff --git a/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/defaultBlocks.json b/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/defaultBlocks.json
new file mode 100644
index 0000000000..69bef1f3f3
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/defaultBlocks.json
@@ -0,0 +1,474 @@
+[
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "Welcome to this demo!",
+        "type": "text",
+      },
+    ],
+    "id": "1",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "paragraph",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {
+          "bold": true,
+        },
+        "text": "Blocks:",
+        "type": "text",
+      },
+    ],
+    "id": "2",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "paragraph",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "Paragraph",
+        "type": "text",
+      },
+    ],
+    "id": "3",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "paragraph",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "Heading",
+        "type": "text",
+      },
+    ],
+    "id": "4",
+    "props": {
+      "backgroundColor": "default",
+      "isToggleable": false,
+      "level": 1,
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "heading",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "Toggle Heading",
+        "type": "text",
+      },
+    ],
+    "id": "5",
+    "props": {
+      "backgroundColor": "default",
+      "isToggleable": false,
+      "level": 1,
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "heading",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "Quote",
+        "type": "text",
+      },
+    ],
+    "id": "6",
+    "props": {
+      "backgroundColor": "default",
+      "textColor": "default",
+    },
+    "type": "quote",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "Bullet List Item",
+        "type": "text",
+      },
+    ],
+    "id": "7",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "bulletListItem",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "Numbered List Item",
+        "type": "text",
+      },
+    ],
+    "id": "8",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "numberedListItem",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "Check List Item",
+        "type": "text",
+      },
+    ],
+    "id": "9",
+    "props": {
+      "backgroundColor": "default",
+      "checked": false,
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "checkListItem",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "Toggle List Item",
+        "type": "text",
+      },
+    ],
+    "id": "10",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "bulletListItem",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "console.log('Hello, world!');",
+        "type": "text",
+      },
+    ],
+    "id": "11",
+    "props": {
+      "language": "javascript",
+    },
+    "type": "codeBlock",
+  },
+  {
+    "children": [],
+    "content": {
+      "columnWidths": [
+        undefined,
+        undefined,
+        undefined,
+      ],
+      "headerCols": undefined,
+      "headerRows": undefined,
+      "rows": [
+        {
+          "cells": [
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Table Cell",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Table Cell",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Table Cell",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+          ],
+        },
+        {
+          "cells": [
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Table Cell",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Table Cell",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Table Cell",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+          ],
+        },
+        {
+          "cells": [
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Table Cell",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Table Cell",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Table Cell",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+          ],
+        },
+      ],
+      "type": "tableContent",
+    },
+    "id": "12",
+    "props": {
+      "textColor": "default",
+    },
+    "type": "table",
+  },
+  {
+    "children": [],
+    "content": undefined,
+    "id": "13",
+    "props": {
+      "backgroundColor": "default",
+      "caption": "From https://placehold.co/332x322.jpg",
+      "name": "",
+      "showPreview": true,
+      "textAlignment": "left",
+      "url": "https://placehold.co/332x322.jpg",
+    },
+    "type": "image",
+  },
+  {
+    "children": [],
+    "content": undefined,
+    "id": "14",
+    "props": {
+      "backgroundColor": "default",
+      "caption": "From https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm",
+      "name": "",
+      "showPreview": true,
+      "textAlignment": "left",
+      "url": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm",
+    },
+    "type": "video",
+  },
+  {
+    "children": [],
+    "content": undefined,
+    "id": "15",
+    "props": {
+      "backgroundColor": "default",
+      "caption": "From https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
+      "name": "",
+      "showPreview": true,
+      "url": "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
+    },
+    "type": "audio",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {
+          "bold": true,
+        },
+        "text": "Inline Content:",
+        "type": "text",
+      },
+    ],
+    "id": "16",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "paragraph",
+  },
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {
+          "bold": true,
+          "italic": true,
+        },
+        "text": "Styled Text",
+        "type": "text",
+      },
+      {
+        "styles": {},
+        "text": " ",
+        "type": "text",
+      },
+      {
+        "content": [
+          {
+            "styles": {},
+            "text": "Link",
+            "type": "text",
+          },
+        ],
+        "href": "https://www.blocknotejs.org",
+        "type": "link",
+      },
+    ],
+    "id": "17",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "paragraph",
+  },
+]
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/table.json b/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/table.json
index c96eefda40..7fb20ea004 100644
--- a/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/table.json
+++ b/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/table.json
@@ -7,34 +7,8 @@
         undefined,
       ],
       "headerCols": undefined,
-      "headerRows": 1,
+      "headerRows": undefined,
       "rows": [
-        {
-          "cells": [
-            {
-              "content": [],
-              "props": {
-                "backgroundColor": "default",
-                "colspan": 1,
-                "rowspan": 1,
-                "textAlignment": "left",
-                "textColor": "default",
-              },
-              "type": "tableCell",
-            },
-            {
-              "content": [],
-              "props": {
-                "backgroundColor": "default",
-                "colspan": 1,
-                "rowspan": 1,
-                "textAlignment": "left",
-                "textColor": "default",
-              },
-              "type": "tableCell",
-            },
-          ],
-        },
         {
           "cells": [
             {
diff --git a/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/tableWithHeaderRow.json b/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/tableWithHeaderRow.json
new file mode 100644
index 0000000000..7944f66a18
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/tableWithHeaderRow.json
@@ -0,0 +1,97 @@
+[
+  {
+    "children": [],
+    "content": {
+      "columnWidths": [
+        undefined,
+        undefined,
+      ],
+      "headerCols": undefined,
+      "headerRows": 1,
+      "rows": [
+        {
+          "cells": [
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Header 1",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Header 2",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+          ],
+        },
+        {
+          "cells": [
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Cell 1",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+            {
+              "content": [
+                {
+                  "styles": {},
+                  "text": "Cell 2",
+                  "type": "text",
+                },
+              ],
+              "props": {
+                "backgroundColor": "default",
+                "colspan": 1,
+                "rowspan": 1,
+                "textAlignment": "left",
+                "textColor": "default",
+              },
+              "type": "tableCell",
+            },
+          ],
+        },
+      ],
+      "type": "tableContent",
+    },
+    "id": "1",
+    "props": {
+      "textColor": "default",
+    },
+    "type": "table",
+  },
+]
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/video.json b/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/video.json
index d7fdf700aa..57607adfdf 100644
--- a/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/video.json
+++ b/tests/src/unit/core/formatConversion/exportParseEquality/__snapshots__/markdown/markdown/video.json
@@ -6,7 +6,7 @@
     "props": {
       "backgroundColor": "default",
       "caption": "",
-      "name": "",
+      "name": "Example",
       "showPreview": true,
       "textAlignment": "left",
       "url": "https://example.com/video.mp4",
diff --git a/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts b/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts
index b6cf5672fa..0ad9312605 100644
--- a/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts
+++ b/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts
@@ -712,6 +712,32 @@ export const exportParseEqualityTestInstancesMarkdown: TestInstance<
     },
     executeTest: testExportParseEqualityMarkdown,
   },
+  {
+    // Regression test for https://github.com/TypeCellOS/BlockNote/issues/739:
+    // a table with no header row must round-trip without acquiring an extra
+    // empty row + header on each export → import cycle.
+    testCase: {
+      name: "markdown/tableWithHeaderRow",
+      content: [
+        {
+          type: "table",
+          content: {
+            type: "tableContent",
+            headerRows: 1,
+            rows: [
+              {
+                cells: ["Header 1", "Header 2"],
+              },
+              {
+                cells: ["Cell 1", "Cell 2"],
+              },
+            ],
+          },
+        },
+      ],
+    },
+    executeTest: testExportParseEqualityMarkdown,
+  },
   {
     testCase: {
       name: "markdown/quote",
@@ -928,4 +954,140 @@ export const exportParseEqualityTestInstancesMarkdown: TestInstance<
     },
     executeTest: testExportParseEqualityMarkdown,
   },
+  {
+    // Mirrors the default-blocks demo (examples/01-basic/04-default-blocks)
+    // so we get a single round-trip snapshot covering every default block
+    // type. Markdown is lossy (colors/alignment/captions/file blocks/toggle
+    // affordances are dropped), so the snapshot documents what survives.
+    testCase: {
+      name: "markdown/defaultBlocks",
+      content: [
+        {
+          type: "paragraph",
+          content: "Welcome to this demo!",
+        },
+        {
+          type: "paragraph",
+          content: [
+            {
+              type: "text",
+              text: "Blocks:",
+              styles: { bold: true },
+            },
+          ],
+        },
+        {
+          type: "paragraph",
+          content: "Paragraph",
+        },
+        {
+          type: "heading",
+          content: "Heading",
+        },
+        {
+          type: "heading",
+          props: { isToggleable: true },
+          content: "Toggle Heading",
+        },
+        {
+          type: "quote",
+          content: "Quote",
+        },
+        {
+          type: "bulletListItem",
+          content: "Bullet List Item",
+        },
+        {
+          type: "numberedListItem",
+          content: "Numbered List Item",
+        },
+        {
+          type: "checkListItem",
+          content: "Check List Item",
+        },
+        {
+          type: "toggleListItem",
+          content: "Toggle List Item",
+        },
+        {
+          type: "codeBlock",
+          props: { language: "javascript" },
+          content: "console.log('Hello, world!');",
+        },
+        {
+          type: "table",
+          content: {
+            type: "tableContent",
+            rows: [
+              { cells: ["Table Cell", "Table Cell", "Table Cell"] },
+              { cells: ["Table Cell", "Table Cell", "Table Cell"] },
+              { cells: ["Table Cell", "Table Cell", "Table Cell"] },
+            ],
+          },
+        },
+        {
+          type: "file",
+        },
+        {
+          type: "image",
+          props: {
+            url: "https://placehold.co/332x322.jpg",
+            caption: "From https://placehold.co/332x322.jpg",
+          },
+        },
+        {
+          type: "video",
+          props: {
+            url: "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm",
+            caption:
+              "From https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm",
+          },
+        },
+        {
+          type: "audio",
+          props: {
+            url: "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
+            caption:
+              "From https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
+          },
+        },
+        {
+          type: "paragraph",
+          content: [
+            {
+              type: "text",
+              text: "Inline Content:",
+              styles: { bold: true },
+            },
+          ],
+        },
+        {
+          type: "paragraph",
+          content: [
+            {
+              type: "text",
+              text: "Styled Text",
+              styles: {
+                bold: true,
+                italic: true,
+                textColor: "red",
+                backgroundColor: "blue",
+              },
+            },
+            {
+              type: "text",
+              text: " ",
+              styles: {},
+            },
+            {
+              type: "link",
+              content: "Link",
+              href: "https://www.blocknotejs.org",
+            },
+          ],
+        },
+      ],
+    },
+    executeTest: testExportParseEqualityMarkdown,
+  },
 ];
diff --git a/tests/src/unit/core/formatConversion/parse/__snapshots__/markdown/video.json b/tests/src/unit/core/formatConversion/parse/__snapshots__/markdown/video.json
index 5070e1873e..55635684d9 100644
--- a/tests/src/unit/core/formatConversion/parse/__snapshots__/markdown/video.json
+++ b/tests/src/unit/core/formatConversion/parse/__snapshots__/markdown/video.json
@@ -6,7 +6,7 @@
     "props": {
       "backgroundColor": "default",
       "caption": "",
-      "name": "",
+      "name": "Video",
       "showPreview": true,
       "textAlignment": "left",
       "url": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm",

From 67ffdcf6271e2e8c6458b34db9047357c0300896 Mon Sep 17 00:00:00 2001
From: Nick the Sick <computers@nickthesick.com>
Date: Thu, 7 May 2026 06:26:48 +0200
Subject: [PATCH 2/4] test(server-util): regenerate ServerBlockNoteEditor
 markdown snapshot

The image-with-caption case now serializes to raw `<figure>` HTML and
parses back with `caption: "Caption"` preserved (previously the caption
was lost into a stray paragraph block).
---
 .../ServerBlockNoteEditor.test.ts.snap        | 27 +++----------------
 1 file changed, 4 insertions(+), 23 deletions(-)

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 db260108b3..6600cd0ead 100644
--- a/packages/server-util/src/context/__snapshots__/ServerBlockNoteEditor.test.ts.snap
+++ b/packages/server-util/src/context/__snapshots__/ServerBlockNoteEditor.test.ts.snap
@@ -135,9 +135,7 @@ Paragraph
 
 * list item
 
-![Example](exampleURL)
-
-Caption
+<figure><img alt="Example" src="exampleURL"><figcaption>Caption</figcaption></figure>
 
 [Example](exampleURL)
 
@@ -221,7 +219,7 @@ exports[`Test ServerBlockNoteEditor > converts to and from markdown (blocksToMar
     "id": "3",
     "props": {
       "backgroundColor": "default",
-      "caption": "",
+      "caption": "Caption",
       "name": "Example",
       "showPreview": true,
       "textAlignment": "left",
@@ -229,23 +227,6 @@ exports[`Test ServerBlockNoteEditor > converts to and from markdown (blocksToMar
     },
     "type": "image",
   },
-  {
-    "children": [],
-    "content": [
-      {
-        "styles": {},
-        "text": "Caption",
-        "type": "text",
-      },
-    ],
-    "id": "4",
-    "props": {
-      "backgroundColor": "default",
-      "textAlignment": "left",
-      "textColor": "default",
-    },
-    "type": "paragraph",
-  },
   {
     "children": [],
     "content": [
@@ -261,7 +242,7 @@ exports[`Test ServerBlockNoteEditor > converts to and from markdown (blocksToMar
         "type": "link",
       },
     ],
-    "id": "5",
+    "id": "4",
     "props": {
       "backgroundColor": "default",
       "textAlignment": "left",
@@ -278,7 +259,7 @@ exports[`Test ServerBlockNoteEditor > converts to and from markdown (blocksToMar
         "type": "text",
       },
     ],
-    "id": "6",
+    "id": "5",
     "props": {
       "backgroundColor": "default",
       "textAlignment": "left",

From 7512b1c07c74b1e896816b92fed00d752b25ed02 Mon Sep 17 00:00:00 2001
From: Nick Perez <nick@blocknotejs.org>
Date: Thu, 7 May 2026 06:43:09 +0200
Subject: [PATCH 3/4] chore: update
 tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---
 .../exportParseEquality/exportParseEqualityTestInstances.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts b/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts
index 0ad9312605..5d491d3bce 100644
--- a/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts
+++ b/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts
@@ -713,9 +713,9 @@ export const exportParseEqualityTestInstancesMarkdown: TestInstance<
     executeTest: testExportParseEqualityMarkdown,
   },
   {
-    // Regression test for https://github.com/TypeCellOS/BlockNote/issues/739:
-    // a table with no header row must round-trip without acquiring an extra
-    // empty row + header on each export → import cycle.
+    // Complementary check for https://github.com/TypeCellOS/BlockNote/issues/739:
+    // a table WITH a real header row must round-trip with the header preserved
+    // (i.e. non-empty headers must not be treated as the empty-header case).
     testCase: {
       name: "markdown/tableWithHeaderRow",
       content: [

From f92ca8e8374fc202d673545c8c707f173c09568f Mon Sep 17 00:00:00 2001
From: Nick the Sick <computers@nickthesick.com>
Date: Thu, 7 May 2026 06:44:02 +0200
Subject: [PATCH 4/4] docs(test): correct markdown/defaultBlocks comment about
 caption survival
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Captions on image/video/audio now survive round-trip via raw `<figure>`
HTML — they shouldn't have been listed as a dropped feature.
---
 .../exportParseEquality/exportParseEqualityTestInstances.ts    | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts b/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts
index 5d491d3bce..b9dcba4828 100644
--- a/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts
+++ b/tests/src/unit/core/formatConversion/exportParseEquality/exportParseEqualityTestInstances.ts
@@ -957,8 +957,9 @@ export const exportParseEqualityTestInstancesMarkdown: TestInstance<
   {
     // Mirrors the default-blocks demo (examples/01-basic/04-default-blocks)
     // so we get a single round-trip snapshot covering every default block
-    // type. Markdown is lossy (colors/alignment/captions/file blocks/toggle
+    // type. Markdown is lossy (colors/alignment/file blocks/toggle
     // affordances are dropped), so the snapshot documents what survives.
+    // Image/video/audio captions are preserved via raw `<figure>` HTML.
     testCase: {
       name: "markdown/defaultBlocks",
       content: [