Merge pull request #35 from agent-ecosystem/fix-content-start-position

dacharyc · web-flow · commit c003a9923ee5 · 2026-04-14T21:09:19.000-04:00
fix: html-to-markdown flattening markdown tables
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -80,6 +80,7 @@
     "commander": "^13.1.0",
     "node-html-parser": "^7.1.0",
     "turndown": "^7.2.2",
+    "turndown-plugin-gfm": "^1.0.2",
     "yaml": "^2.7.0"
   },
   "devDependencies": {
diff --git a/src/checks/page-size/content-start-position.ts b/src/checks/page-size/content-start-position.ts
@@ -74,6 +74,12 @@ function headingFollowedByContent(lines: string[], headingIdx: number): boolean
     const nextLine = i + 1 < lines.length ? lines[i + 1].trim() : '';
     if (/^[=-]+$/.test(nextLine) && nextLine.length >= 2) return false;
 
+    // Markdown table row (e.g. "| Col A | Col B |")
+    if (/^\|.+\|/.test(t)) return true;
+
+    // HTML table tags inside .md files (not converted by htmlToMarkdown)
+    if (/^<table[\s>]/i.test(t) || /^<tr[\s>]/i.test(t)) return true;
+
     // A line > NAV_MAX_LENGTH that isn't a link is likely real prose
     if (t.length > NAV_MAX_LENGTH && linkDensity(t) < 0.5) return true;
 
diff --git a/src/helpers/html-to-markdown.ts b/src/helpers/html-to-markdown.ts
@@ -1,11 +1,15 @@
 import TurndownService from 'turndown';
+import { tables } from 'turndown-plugin-gfm';
 
 /**
  * Convert HTML to markdown using Turndown with default configuration.
  * Matches real agent behavior per the Agent-Friendly Documentation Spec:
  * no explicit <style>/<script> stripping, default options only.
+ * The GFM tables plugin is enabled so HTML tables are preserved as markdown
+ * tables rather than being flattened to plain text.
  */
 export function htmlToMarkdown(html: string): string {
   const turndown = new TurndownService();
+  turndown.use(tables);
   return turndown.turndown(html);
 }
diff --git a/src/types/turndown-plugin-gfm.d.ts b/src/types/turndown-plugin-gfm.d.ts
@@ -0,0 +1,11 @@
+declare module 'turndown-plugin-gfm' {
+  import type TurndownService from 'turndown';
+
+  type TurndownPlugin = (service: TurndownService) => void;
+
+  export const gfm: TurndownPlugin;
+  export const tables: TurndownPlugin;
+  export const strikethrough: TurndownPlugin;
+  export const taskListItems: TurndownPlugin;
+  export const highlightedCodeBlock: TurndownPlugin;
+}
diff --git a/test/unit/checks/content-start-position.test.ts b/test/unit/checks/content-start-position.test.ts
@@ -507,6 +507,54 @@ describe('content-start-position', () => {
     expect(result.status).toBe('pass');
   });
 
+  // ── Table content after headings (issue #20) ──
+
+  it('detects markdown table as content after heading', async () => {
+    const html = `<html><body>
+      <h1>Limits for Scheduled Triggers</h1>
+      <table><tr><th>Trigger interval</th><th>Max executions</th></tr>
+      <tr><td>Every 5 minutes</td><td>50 per hour</td></tr></table>
+    </body></html>`;
+
+    server.use(
+      http.get(
+        'http://test.local/docs/table-after-heading',
+        () => new HttpResponse(html, { status: 200, headers: { 'Content-Type': 'text/html' } }),
+      ),
+    );
+
+    const result = await check.run(singlePageCtx('/docs/table-after-heading'));
+    expect(result.status).toBe('pass');
+  });
+
+  it('detects markdown table in .md content as content after heading', async () => {
+    const md = `# Limits\n\n| Trigger interval | Max executions |\n|-----------------|----------------|\n| Every 5 minutes | 50 per hour    |\n`;
+
+    server.use(
+      http.get(
+        'http://test.local/docs/table-md',
+        () => new HttpResponse(md, { status: 200, headers: { 'Content-Type': 'text/markdown' } }),
+      ),
+    );
+
+    const result = await check.run(singlePageCtx('/docs/table-md'));
+    expect(result.status).toBe('pass');
+  });
+
+  it('detects HTML table in .md content as content after heading', async () => {
+    const md = `# Limits\n\n<table>\n  <tr><th>Col A</th><th>Col B</th></tr>\n  <tr><td>val</td><td>val</td></tr>\n</table>\n`;
+
+    server.use(
+      http.get(
+        'http://test.local/docs/table-html-in-md',
+        () => new HttpResponse(md, { status: 200, headers: { 'Content-Type': 'text/markdown' } }),
+      ),
+    );
+
+    const result = await check.run(singlePageCtx('/docs/table-html-in-md'));
+    expect(result.status).toBe('pass');
+  });
+
   // ── Lines that don't match any skip pattern and aren't prose ──
 
   it('skips short multi-word non-prose lines (breadcrumbs)', async () => {
