@link-assistant/web-capture 1.7.19 → 1.7.20

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/web-capture
 
+## 1.7.20
+
+### Patch Changes
+
+- 5a3e588: Preserve hierarchical heading numbering (e.g. 13, 13.1) in API-path Markdown conversion. Numbered headings wrapped in `<ol><li><hN>` no longer get renumbered to 1, and sub-numbered headings render with their original number on a clean line.
+
 ## 1.7.19
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/web-capture",
-  "version": "1.7.19",
+  "version": "1.7.20",
   "description": "CLI and microservice to render web pages as HTML, Markdown, or PNG",
   "main": "src/index.js",
   "bin": {

package/src/lib.js

@@ -52,6 +52,13 @@ export function convertHtmlToMarkdown(html, baseUrl) {
     }
   });
 
+  // Preserve hierarchical heading numbering in source text (e.g. 13, 13.1).
+  // 1) <ol><li><hN>13. Foo</hN></li></ol> → <ol start="13"><li><hN>Foo</hN></li></ol>
+  //    Then Turndown emits "13.  #### Foo" instead of restarting at "1.".
+  // 2) <hN>13.1 Bar</hN> (sub-numbering with decimal) → <p><strong>13.1 Bar</strong></p>
+  //    Demoting avoids ATX heading prefix, leaving the sub-number on a clean line.
+  preserveLeadingHeadingNumbering($);
+
   // Remove <a> tags with no direct text content (including only whitespace or only child elements)
   $('a').each(function () {
     // Get all text nodes directly under this <a>
@@ -172,6 +179,100 @@ export function convertHtmlToMarkdown(html, baseUrl) {
   return he.decode(turndown.turndown($.html())).replace(/\u00A0/g, '&nbsp;');
 }
 
+function preserveLeadingHeadingNumbering($) {
+  // Hoist the OL counter onto a heading inside its first <li>.
+  // Example: <ol><li><h4>13. Foo</h4></li></ol> → <ol start="13"><li><h4>Foo</h4></li></ol>
+  $('ol > li').each(function () {
+    const $li = $(this);
+    const $heading = $li.children('h1, h2, h3, h4, h5, h6').first();
+    if (!$heading.length) {
+      return;
+    }
+    // Only act when the <li> has just one heading child and no other meaningful text.
+    if ($li.children().length !== 1) {
+      return;
+    }
+    const text = $heading.text();
+    const m = text.match(/^\s*(\d+)\.\s+(.*)$/s);
+    if (!m) {
+      return;
+    }
+    const [, num, rest] = m;
+    const $ol = $li.parent();
+    if ($ol.children('li').length !== 1) {
+      return;
+    }
+    if (!$ol.attr('start')) {
+      $ol.attr('start', num);
+    }
+    stripLeadingTextFromHeading($, $heading, m[0].length - rest.length);
+  });
+
+  // Demote <hN> with sub-numbering text (e.g. "13.1 Foo") to a bold paragraph.
+  // Avoids emitting `##### 13.1 Foo` (which collides with renderers that strip
+  // numbering or blockquote-wrap subsections downstream).
+  $('h1, h2, h3, h4, h5, h6').each(function () {
+    const $h = $(this);
+    const text = $h.text();
+    if (!/^\s*\d+\.\d+/.test(text)) {
+      return;
+    }
+    const inner = $h.html() || '';
+    const $p = $('<p></p>');
+    if (/^\s*<strong[\s>]/i.test(inner)) {
+      $p.html(inner);
+    } else {
+      $p.html(`<strong>${inner}</strong>`);
+    }
+    $h.replaceWith($p);
+  });
+}
+
+function stripLeadingTextFromHeading($, $heading, prefixLen) {
+  // Walk text nodes from the start of the heading and remove prefixLen characters.
+  let remaining = prefixLen;
+  const stack = [$heading.get(0)];
+  while (stack.length && remaining > 0) {
+    const node = stack.shift();
+    const children = node.children || [];
+    for (const child of children) {
+      if (remaining <= 0) {
+        break;
+      }
+      if (child.type === 'text') {
+        const data = child.data || '';
+        if (data.length <= remaining) {
+          remaining -= data.length;
+          child.data = '';
+        } else {
+          child.data = data.slice(remaining);
+          remaining = 0;
+        }
+      } else {
+        stack.push(child);
+      }
+    }
+  }
+  // Trim leading whitespace from the first non-empty text node.
+  const walk = (node) => {
+    const children = node.children || [];
+    for (const child of children) {
+      if (child.type === 'text') {
+        if (child.data) {
+          child.data = child.data.replace(/^\s+/, '');
+          if (child.data) {
+            return true;
+          }
+        }
+      } else if (walk(child)) {
+        return true;
+      }
+    }
+    return false;
+  };
+  walk($heading.get(0));
+}
+
 function preserveTableCellLineBreaks(turndown) {
   turndown.addRule('tableCellLineBreak', {
     filter(node) {
@@ -402,6 +503,9 @@ export function convertHtmlToMarkdownEnhanced(html, baseUrl, options = {}) {
     }
   });
 
+  // Preserve hierarchical heading numbering (see convertHtmlToMarkdown).
+  preserveLeadingHeadingNumbering($);
+
   // Remove empty links (same logic as convertHtmlToMarkdown)
   $('a').each(function () {
     const directText = $(this)

package/tests/fixtures/heading-numbering.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html>
+  <body>
+    <ol>
+      <li>
+        <h4><strong>13. Top-level numbered heading in source</strong></h4>
+      </li>
+    </ol>
+
+    <h5><strong>13.1 First subsection heading</strong></h5>
+    <p>Where it activates: ...</p>
+
+    <h5><strong>13.2 Second subsection heading</strong></h5>
+    <p>Where it activates: ...</p>
+
+    <h5><strong>13.3 Third subsection heading</strong></h5>
+    <p>Where it activates: ...</p>
+  </body>
+</html>

package/tests/unit/heading-numbering.test.js

@@ -0,0 +1,28 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { convertHtmlToMarkdown } from '../../src/lib.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const HTML = fs.readFileSync(
+  path.join(__dirname, '..', 'fixtures', 'heading-numbering.html'),
+  'utf8'
+);
+
+it('preserves hierarchical heading numbering (13, 13.1, 13.2, 13.3)', () => {
+  const md = convertHtmlToMarkdown(HTML);
+
+  // Parent number 13 must survive — either as Markdown heading or as numbered-list item.
+  expect(md).toMatch(/(^|\n)#{1,6}\s+13\.|(^|\n)13\.\s/);
+
+  // Sub-numbers 13.1, 13.2, 13.3 must each appear in heading-like context (line start, not buried mid-paragraph).
+  for (const sub of ['13.1', '13.2', '13.3']) {
+    expect(md).toMatch(
+      new RegExp(`(^|\\n)\\s*\\*{0,3}\\s*${sub.replace('.', '\\.')}`, 'm')
+    );
+  }
+
+  // Subsections must NOT be wrapped in markdown blockquotes — there is no <blockquote> in the fixture.
+  expect(md).not.toMatch(/^>\s+\*{1,3}13\.\d/m);
+});