From a2c8bd31c64b1716f4e550c82905e6484c97ece1 Mon Sep 17 00:00:00 2001
From: bendtherules <abhasbhattacharya2@gmail.com>
Date: Mon, 6 Apr 2026 13:39:43 +0530
Subject: [PATCH] feat(lists): alternate markdown list markers by nesting depth

Ordered lists switch between `1.` (even depth) and `A.` (odd depth).
Unordered lists switch between `-` (even depth) and `*` (odd depth).
Makes nested list structure visually distinct in extracted text.
---
 setup/textsplitters/HtmlTextSplitter.test.ts |  6 ++---
 setup/utils/formatHTMLForIngestion.test.ts   | 24 +++++++++---------
 setup/utils/formatHTMLForIngestion.ts        | 26 +++++++++++++++++++-
 3 files changed, 40 insertions(+), 16 deletions(-)

diff --git a/setup/textsplitters/HtmlTextSplitter.test.ts b/setup/textsplitters/HtmlTextSplitter.test.ts
index c737d9c..df2ea4c 100644
--- a/setup/textsplitters/HtmlTextSplitter.test.ts
+++ b/setup/textsplitters/HtmlTextSplitter.test.ts
@@ -334,8 +334,8 @@ describe("HTMLTextSplitter", () => {
     const html = [
       '<pre class="list-markdown">',
       "1. First",
-      "  1. Nested 1",
-      "  2. Nested 2",
+      "  A. Nested 1",
+      "  B. Nested 2",
       "2. Second",
       "</pre>",
     ].join("\n");
@@ -343,7 +343,7 @@ describe("HTMLTextSplitter", () => {
     const chunks = await splitter.splitText(html);
 
     expect(chunks).toEqual([
-      "1. First\n  1. Nested 1\n  2. Nested 2\n2. Second",
+      "1. First\n  A. Nested 1\n  B. Nested 2\n2. Second",
     ]);
   });
 });
diff --git a/setup/utils/formatHTMLForIngestion.test.ts b/setup/utils/formatHTMLForIngestion.test.ts
index 870f24a..93ab052 100644
--- a/setup/utils/formatHTMLForIngestion.test.ts
+++ b/setup/utils/formatHTMLForIngestion.test.ts
@@ -105,8 +105,8 @@ describe("formatHTMLForIngestion", () => {
       expect(lines).toEqual([
         "- Item 1",
         "- Item 2",
-        "  1. Subitem 1",
-        "  2. Subitem 2",
+        "  A. Subitem 1",
+        "  B. Subitem 2",
       ]);
     });
 
@@ -140,10 +140,10 @@ describe("formatHTMLForIngestion", () => {
       expect(lines).toEqual([
         "1. First",
         "2. Second",
-        "  - Alpha",
+        "  * Alpha",
         "    1. Deep 1",
         "    2. Deep 2",
-        "  - Beta",
+        "  * Beta",
       ]);
     });
 
@@ -172,8 +172,8 @@ describe("formatHTMLForIngestion", () => {
         .filter((l) => l.length > 0);
       expect(lines).toEqual([
         "- Item",
-        "  1. Ordered sub",
-        "  - Unordered sub",
+        "  A. Ordered sub",
+        "  * Unordered sub",
       ]);
     });
 
@@ -257,8 +257,8 @@ describe("formatHTMLForIngestion", () => {
         .filter((l) => l.length > 0);
       expect(lines).toEqual([
         "1. First",
-        "  1. Nested 1",
-        "  2. Nested 2",
+        "  A. Nested 1",
+        "  B. Nested 2",
         "2. Second",
       ]);
     });
@@ -351,10 +351,10 @@ describe("formatHTMLForIngestion", () => {
       expect(lines).toEqual([
         "1. First",
         "2. Second",
-        "  - Alpha",
+        "  * Alpha",
         "    1. Deep 1",
         "    2. Deep 2",
-        "  - Beta",
+        "  * Beta",
       ]);
     });
 
@@ -379,8 +379,8 @@ describe("formatHTMLForIngestion", () => {
         .filter((l) => l.length > 0);
       expect(lines).toEqual([
         "1. First",
-        "  1. Nested 1",
-        "  2. Nested 2",
+        "  A. Nested 1",
+        "  B. Nested 2",
         "2. Second",
       ]);
     });
diff --git a/setup/utils/formatHTMLForIngestion.ts b/setup/utils/formatHTMLForIngestion.ts
index 0fefdcd..729e82d 100644
--- a/setup/utils/formatHTMLForIngestion.ts
+++ b/setup/utils/formatHTMLForIngestion.ts
@@ -128,6 +128,30 @@ export function convertBlockCodeToMarkdown(
   });
 }
 
+/**
+ * Returns the markdown list item prefix based on list type and nesting depth.
+ * Alternates markers to visually distinguish nesting levels:
+ * - Ordered lists: `1.` at even depth, `A.` at odd depth
+ * - Unordered lists: `-` at even depth, `*` at odd depth
+ *
+ * @param isOrdered - Whether the list is ordered (ol) or unordered (ul)
+ * @param depth - Nesting depth (0 = top-level)
+ * @param index - Zero-based item index within its list
+ * @returns Prefix string like "1. ", "A. ", "- ", or "* "
+ */
+function getListItemPrefix(
+  isOrdered: boolean,
+  depth: number,
+  index: number,
+): string {
+  if (isOrdered) {
+    return depth % 2 === 0
+      ? `${index + 1}. `
+      : `${String.fromCharCode(65 + index)}. `;
+  }
+  return depth % 2 === 0 ? "- " : "* ";
+}
+
 function listToMarkdown(
   $: cheerio.CheerioAPI,
   elem: any,
@@ -139,7 +163,7 @@ function listToMarkdown(
   const lines: string[] = [];
 
   $elem.children("li").each((i, li) => {
-    const prefix = isOrdered ? `${i + 1}. ` : "- ";
+    const prefix = getListItemPrefix(isOrdered, depth, i);
     const $li = $(li);
 
     const nestedLists: string[] = [];