content-start-position: false positive on pages where content is a table (markdown, HTML, or HTML-in-md)

[Chris-ganta]

Bug Description

The content-start-position check incorrectly reports a fail on pages
where real content immediately follows a heading but is in table format
rather than prose paragraphs.

Affected check

• ID: content-start-position
• Category: page-size
• afdocs version: 0.9.1

Example page

https://developer.atlassian.com/platform/forge/limits-scheduled-trigger.md

Reported contentStartPercent: 95% (fail) — but the page has legitimate
content immediately after the first heading. The content is a limits table,
not navigation or boilerplate.

Root cause

In headingFollowedByContent(), a heading is only considered to have real
content following it if the next lines match prose patterns:

// Current prose detection:
t.length > NAV_MAX_LENGTH && linkDensity(t) < 0.5  // long non-link line
/[.!?]$/.test(t) && t.length >= 10                 // sentence with punctuation
This correctly filters nav/sidebar headings but incorrectly skips headings followed by tables — because:

•  Markdown table rows end with | not .!?
•  HTML <table> tags don't match any prose pattern
•  Short table cells may be under NAV_MAX_LENGTH
So for a page like:

# Limits for Scheduled Triggers

| Trigger interval | Max executions |
|-----------------|----------------|
| Every 5 minutes | 50 per hour    |
The heading is skipped as if it were a nav heading, the algorithm keeps scanning, and reports a falsely high contentStartPercent.
Three affected scenarios
1. Raw .md files with markdown tables

# Page Title
| Col A | Col B |
|-------|-------|
| val   | val   |
Table rows end with | — not matched by prose detection. ❌
2. HTML pages with HTML tables

<h1>Page Title</h1>
<table><tr><th>Col A</th><th>Col B</th></tr></table>
After htmlToMarkdown() conversion → becomes markdown table → same issue. ❌
3. .md files containing raw HTML tables

# Page Title

<table>
  <tr><th>Col A</th><th>Col B</th></tr>
  <tr><td>val</td><td>val</td></tr>
</table>
Since .md files skip htmlToMarkdown() conversion (raw body used directly), the <table> HTML tags are passed to findContentStart() as-is — not matched by any existing pattern. ❌
This third case is common in documentation sites that use HTML tables inside markdown files for complex layouts (e.g. developer.atlassian.com).
Suggested fix
Add table detection to headingFollowedByContent() alongside the existing prose checks:

// Markdown table row
if (/^\|.+\|/.test(t)) return true;

// HTML table tag inside .md files (not converted by htmlToMarkdown)
if (/^<table[\s>]/i.test(t)) return true;

// HTML table row inside .md files
if (/^<tr[\s>]/i.test(t)) return true;
Since findContentStart() always operates on the same text regardless of source format, this single fix covers all three scenarios.
Impact

•  False fail results on legitimate reference/API documentation pages
•  Affects any docs site that uses tables for reference content (API limits, config options, CLI flags, pricing tables, etc.)
•  Particularly severe for .md files containing HTML tables — a common pattern in documentation platforms
•  Misleads developers into thinking their content structure is wrong when it is perfectly valid

[dacharyc]

Thanks for this report — you're right that table content after headings should be recognized as real content, and the suggested fix is spot-on.

We've implemented the table detection fix on the fix-content-start-position branch:

• headingFollowedByContent() now recognizes markdown table rows (|...|), and raw HTML <table>/<tr> tags inside .md files, as content signals — alongside the existing prose checks.
• htmlToMarkdown() now uses the turndown-plugin-gfm tables plugin, so HTML <table> elements convert to proper markdown table syntax instead of being flattened to bare cell text by default Turndown.
• Tests cover all three scenarios from your report: markdown tables, HTML tables via Turndown, and raw HTML tables in .md files.

We'll ship this in the next release.

A note on the example URL

We investigated the specific page you referenced (developer.atlassian.com/platform/forge/limits-scheduled-trigger) and wanted to share what we found, since the content-start-position result for that page won't change with this fix.

On that page, the table detection wasn't actually the bottleneck. One of the table rows (| Total number of scheduled trigger modules in an app | 5 | at 59 characters) already exceeded the existing NAV_MAX_LENGTH threshold of 40 characters, so the heading was already being recognized as having content. The 96% result comes from the page's HTML structure:

• The <h1 id="scheduled-trigger-limits"> element is at position 94.3% of the raw HTML
• Before it: 157KB of server-rendered <nav> (the full Forge docs sidebar with ~269 links), 57KB of inline <style> tags, and 117KB of <script> content (including a window.__DATA__ JSON blob)
• After Turndown conversion, the heading lands at line 1399 of 1430 — with ~266KB of converted boilerplate before it

This is the class of problem content-start-position is designed to surface: the documentation content is real and well-structured, but agents processing the HTML response encounter it only after wading through a large volume of navigation, CSS, and JavaScript. The table detection fix helps pages where the heading is near the top but followed by short table rows; for this page, the DOM structure itself places the content late.

Separately, we're tracking an update to strip <script> and <style> elements before Turndown conversion (#34), which would reduce the converted output from 268KB to 27KB for this page. Even with that change the heading remains at ~97% because the <nav> content dominates, but it will significantly improve accuracy for pages where inline CSS/JS is the primary source of boilerplate.

[dacharyc]

Ok, @Chris-ganta, v0.10.2 is live with the table fix.