Add number class annotation feature to HTML to Markdown conversion (#74)

This update introduces the `annotateNumberClasses` option, which, when
enabled, appends the CSS class name of number-bearing elements next to
the number in the markdown output. This preserves semantic meaning for
numbers, such as prices and ratings, while ensuring that nested numeric
parts do not add noise. The feature is accompanied by tests to verify
its functionality and is documented in the README.

Author: azhong-git

README.md

@@ -441,6 +441,7 @@ Main function to extract structured data from content.
 | `extractMainHtml` | `boolean` | When enabled for HTML content, attempts to extract the main content area, removing navigation bars, headers, footers, sidebars etc. using heuristics. Should be kept off when extracting details about a single item. | `false` |
 | `includeImages` | `boolean` | When enabled, images in the HTML will be included in the markdown output. Enable this when you need to extract image URLs or related content. | `false` |
 | `cleanUrls` | `boolean` | When enabled, removes tracking parameters and unnecessary URL components to produce cleaner links. Currently supports cleaning Amazon product URLs by removing `/ref=` parameters and everything after. This helps produce more readable URLs in the markdown output. | `false` |
+| `annotateNumberClasses` | `boolean` | When enabled, appends the CSS class name of number-bearing elements next to the number in the markdown (e.g. `22,99 {price-box__price__amount}`). Plain markdown discards the semantic meaning encoded in class names; this preserves whether a number is a price, rating, review count, etc. Only the outermost element whose text is purely a number is annotated, so nested integer/decimal parts don't add noise. | `false` |
 
 #### Return Value
 

src/converters.ts

@@ -69,6 +69,27 @@ function extractMainHtml(html: string): string {
   }
 }
 
+/**
+ * Matches a string that is "just a number" once whitespace is removed.
+ * Tolerates a leading currency symbol / sign, thousands and decimal
+ * separators (",", "."), and a trailing percent sign — e.g. "22,99",
+ * "$1,234.56", "4.5", "275", "99%".
+ */
+const NUMBER_LIKE_RE = /^[$€£¥₹+\-]?[\d.,]*\d[\d.,]*%?$/;
+
+/**
+ * Returns the whitespace-collapsed text when it represents a single number
+ * token (e.g. "22,99", "$1,234.56", "275"), otherwise an empty string. Used
+ * to decide whether an element's class name carries semantic meaning worth
+ * annotating onto the number, and to compare numbers across nested elements.
+ */
+function normalizeNumberText(text: string | null | undefined): string {
+  if (!text) return "";
+  const normalized = text.replace(/\s+/g, "");
+  if (!normalized || !/\d/.test(normalized)) return "";
+  return NUMBER_LIKE_RE.test(normalized) ? normalized : "";
+}
+
 /**
  * Convert HTML to Markdown
  */
@@ -114,6 +135,65 @@ export function htmlToMarkdown(
     replacement: () => "",
   });
 
+  if (options?.annotateNumberClasses) {
+    // Append the class name of number-bearing elements next to the number so
+    // the downstream LLM keeps the semantic meaning that plain Markdown drops
+    // (e.g. "22,99 {price-box__price__amount}").
+    //
+    // We pick the single element that best represents the number, navigating
+    // two opposing nesting patterns:
+    //   1. Composed numbers — the number is assembled from fragment children
+    //      (e.g. <span int>22</span><span decSep>,</span><sup dec>99</sup>).
+    //      None of the children holds the whole number, so we annotate the
+    //      parent where it comes together and skip the fragments.
+    //   2. Wrapped numbers — the same full number is duplicated through
+    //      single-purpose wrappers (e.g. layout div <div col-xs-6>
+    //      <div specs__value>125</div></div>). We annotate the innermost
+    //      element and skip the redundant outer wrappers, since the inner
+    //      class (page-product__specs__value) carries the meaning, not the
+    //      layout class (col-xs-6).
+    turnDownService.addRule("annotate-number-classes", {
+      filter: function (node: any) {
+        if (typeof node.getAttribute !== "function") return false;
+        const className = node.getAttribute("class");
+        if (!className || !className.trim()) return false;
+        const selfNumber = normalizeNumberText(node.textContent);
+        if (!selfNumber) return false;
+
+        // Wrapped-number case: if a child element already carries the same
+        // full number, that child is more specific — let it be annotated.
+        const childNodes = node.childNodes || [];
+        for (let i = 0; i < childNodes.length; i++) {
+          const child = childNodes[i];
+          if (
+            child.nodeType === 1 &&
+            normalizeNumberText(child.textContent) === selfNumber
+          ) {
+            return false;
+          }
+        }
+
+        // Composed-number case: if the parent is numeric but represents a
+        // different (larger) number, this element is only a fragment of it —
+        // let the parent be annotated instead.
+        const parent = node.parentNode;
+        if (parent && parent.nodeType === 1) {
+          const parentNumber = normalizeNumberText(parent.textContent);
+          if (parentNumber && parentNumber !== selfNumber) {
+            return false;
+          }
+        }
+
+        return true;
+      },
+      replacement: function (_content: string, node: any) {
+        const number = normalizeNumberText(node.textContent);
+        const className = node.getAttribute("class").trim().replace(/\s+/g, " ");
+        return `${number} {${className}}`;
+      },
+    });
+  }
+
   turnDownService.addRule("title-as-h1", {
     filter: ["title"],
     replacement: (innerText: string) => `${innerText}\n===============\n`,

src/types.ts

@@ -41,6 +41,20 @@ export interface HTMLExtractionOptions {
    * Disabled by default to preserve original URLs.
    */
   cleanUrls?: boolean;
+
+  /**
+   * When enabled, appends the CSS class name of number-bearing elements next to
+   * the number in the markdown output (e.g. `22,99 {price-box__price__amount}`).
+   *
+   * Plain markdown discards the semantic meaning encoded in class names, making
+   * it hard for the LLM to tell whether a number is a price, rating, review
+   * count, etc. This annotates the outermost element whose text is purely a
+   * number, preserving that signal while keeping nested numeric parts
+   * (integer / decimal / separator spans) from adding noise.
+   *
+   * Disabled by default.
+   */
+  annotateNumberClasses?: boolean;
 }
 
 /**

tests/unit/converters.test.ts

@@ -139,6 +139,95 @@ describe("HTML to Markdown converter", () => {
     expect(markdownWithoutExtraction).toContain("Footer content");
   });
 
+  describe("number class annotation", () => {
+    const priceHtml = `
+      <span class="price-box__price large ">
+        <span class="price-box__price__amount">
+          <span class="price-box__price__amount__integer">22</span>
+          <span class="price-box__price__amount__decSep">,</span>
+          <sup class="price-box__price__amount__decimal">99</sup>
+        </span>
+        <span class="price-box__price__spec">Chacun</span>
+      </span>`;
+
+    test("does not annotate numbers by default", () => {
+      const markdown = htmlToMarkdown(priceHtml);
+      expect(markdown).not.toContain("{");
+      expect(markdown).toContain("Chacun");
+    });
+
+    test("annotates the outermost numeric element with its class", () => {
+      const markdown = htmlToMarkdown(priceHtml, {
+        annotateNumberClasses: true,
+      });
+
+      // The fully-numeric amount span is annotated with its class...
+      expect(markdown).toContain("22,99 {price-box__price__amount}");
+      // ...while the nested integer / decimal parts are NOT annotated.
+      expect(markdown).not.toContain("__integer}");
+      expect(markdown).not.toContain("__decimal}");
+      // Non-numeric siblings are left untouched.
+      expect(markdown).toContain("Chacun");
+    });
+
+    test("annotates standalone numeric fields", () => {
+      const html = `
+        <div class="product">
+          <span class="rating">4.5</span>
+          <span class="review-count">275</span>
+          <div class="price">$1,234.56</div>
+        </div>`;
+      const markdown = htmlToMarkdown(html, { annotateNumberClasses: true });
+
+      expect(markdown).toContain("4.5 {rating}");
+      expect(markdown).toContain("275 {review-count}");
+      expect(markdown).toContain("$1,234.56 {price}");
+    });
+
+    test("annotates the innermost element for same-number wrappers", () => {
+      // The number is duplicated through a layout wrapper (col-xs-6) whose
+      // only content is the same value. The meaningful class lives on the
+      // inner element, not the grid wrapper.
+      const html = `
+        <div class="row">
+          <div class="col-xs-6">
+            <div class="page-product__specs__label">Weight</div>
+          </div>
+          <div class="col-xs-6">
+            <div class="page-product__specs__value">125</div>
+          </div>
+        </div>`;
+      const markdown = htmlToMarkdown(html, { annotateNumberClasses: true });
+
+      expect(markdown).toContain("125 {page-product__specs__value}");
+      expect(markdown).not.toContain("{col-xs-6}");
+    });
+
+    test("annotates the innermost element through deeply nested wrappers", () => {
+      const html = `
+        <section>
+          <div class="a"><div class="b"><div class="c">125</div></div></div>
+        </section>`;
+      const markdown = htmlToMarkdown(html, { annotateNumberClasses: true });
+
+      expect(markdown).toContain("125 {c}");
+      expect(markdown).not.toContain("{a}");
+      expect(markdown).not.toContain("{b}");
+    });
+
+    test("does not annotate non-numeric or classless elements", () => {
+      const html = `
+        <span class="label">In stock</span>
+        <span>42</span>`;
+      const markdown = htmlToMarkdown(html, { annotateNumberClasses: true });
+
+      // Text content is not a number → no annotation.
+      expect(markdown).not.toContain("{label}");
+      // Numeric but no class → no annotation.
+      expect(markdown).not.toContain("{");
+    });
+  });
+
   describe("URL handling", () => {
     test("should convert relative URLs to absolute URLs when sourceUrl is provided", () => {
       const html = `