@link-assistant/web-capture 1.7.19 → 1.7.21

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/web-capture
 
+## 1.7.21
+
+### Patch Changes
+
+- b8ad97d: Number consecutive top-level `<ol>`s continuously across the document (1, 2, 3, ... N) so JS and Rust HTML→Markdown converters agree. `<ol start="N">` resets the counter and is honoured by both implementations. Nested ordered lists keep their own per-list numbering.
+
+## 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.21",
   "description": "CLI and microservice to render web pages as HTML, Markdown, or PNG",
   "main": "src/index.js",
   "bin": {

package/src/gdocs-preprocess.js

@@ -245,6 +245,12 @@ function renderNestedListGroup($, group, classStyles) {
   const openTags = [];
   const itemOpen = [];
 
+  const topLevelStart =
+    group[0]?.tagName?.toLowerCase() === 'ol'
+      ? $(group[0]).attr('start')
+      : undefined;
+  let topLevelOpened = false;
+
   const closeItem = (level) => {
     if (itemOpen[level]) {
       html += '</li>';
@@ -261,7 +267,21 @@ function renderNestedListGroup($, group, classStyles) {
   const openList = (level, tagName) => {
     openTags[level] = tagName;
     itemOpen[level] = false;
-    html += `<${tagName}>`;
+    if (
+      level === 0 &&
+      !topLevelOpened &&
+      tagName === 'ol' &&
+      topLevelStart !== undefined &&
+      topLevelStart !== ''
+    ) {
+      html += `<ol start="${topLevelStart}">`;
+      topLevelOpened = true;
+    } else {
+      if (level === 0) {
+        topLevelOpened = true;
+      }
+      html += `<${tagName}>`;
+    }
   };
 
   for (const list of group) {

package/src/lib.js

@@ -52,6 +52,17 @@ 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($);
+
+  // Number consecutive top-level <ol>s continuously across the document
+  // (1, 2, 3 ... N) so JS and Rust agree. <ol start="N"> resets the counter.
+  applyContinuousOrderedListNumbering($);
+
   // 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 +183,122 @@ 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);
+  });
+}
+
+// Walk every top-level <ol> in document order and assign a `start` attribute
+// so consecutive lists number continuously (1, 2, 3, ... N). An explicit
+// `start="N"` resets the running counter to N and is preserved.
+//
+// Top-level here means "not inside another <ol> or <ul>" — nested ordered
+// lists keep their own numbering and Turndown's per-list start handling.
+function applyContinuousOrderedListNumbering($) {
+  let counter = 1;
+  $('ol').each(function () {
+    if ($(this).parents('ol, ul').length > 0) {
+      return;
+    }
+    const explicitStart = parseInt($(this).attr('start') ?? '', 10);
+    if (Number.isFinite(explicitStart)) {
+      counter = explicitStart;
+    } else {
+      $(this).attr('start', String(counter));
+    }
+    counter += $(this).children('li').length;
+  });
+}
+
+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 +529,12 @@ export function convertHtmlToMarkdownEnhanced(html, baseUrl, options = {}) {
     }
   });
 
+  // Preserve hierarchical heading numbering (see convertHtmlToMarkdown).
+  preserveLeadingHeadingNumbering($);
+
+  // Continuous numbering across consecutive top-level <ol>s (see convertHtmlToMarkdown).
+  applyContinuousOrderedListNumbering($);
+
   // 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/fixtures/ol-continuous-numbering.html

@@ -0,0 +1,12 @@
+<ol>
+  <li><strong>First</strong></li>
+  <li><strong>Second</strong></li>
+</ol>
+<p>Some prose between lists.</p>
+<ol>
+  <li><strong>Third</strong></li>
+  <li><strong>Fourth</strong></li>
+</ol>
+<ol start="13">
+  <li><strong>Top-level numbered heading.</strong></li>
+</ol>

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);
+});

package/tests/unit/html2md-ol-numbering.test.js

@@ -0,0 +1,20 @@
+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', 'ol-continuous-numbering.html'),
+  'utf8'
+);
+
+it('numbers consecutive top-level ordered lists continuously', () => {
+  const md = convertHtmlToMarkdown(HTML);
+  expect(md).toMatch(/^\s*1\.\s+\*\*First\*\*/m);
+  expect(md).toMatch(/^\s*2\.\s+\*\*Second\*\*/m);
+  expect(md).toMatch(/^\s*3\.\s+\*\*Third\*\*/m);
+  expect(md).toMatch(/^\s*4\.\s+\*\*Fourth\*\*/m);
+  expect(md).toMatch(/^\s*13\.\s+\*\*Top-level/m);
+});