heading-outline

Heading Outline — H1–H6 Heading Structure and Hierarchy

Screaming Frog exports only H1/H2 and flags only "missing H1" / "multiple H1" (see ../sf-analyzer/reference/checks.md: H1_MISSING, H1_MULTIPLE, H2_MISSING). It does not provide a complete H1–H6 outline in document order or check level jumps; the agent does this itself by parsing live HTML.

When to Use It

• "Check the headings / heading structure on the page";
• "Is the H1→H2→H3 hierarchy correct, with no level jumps?";
• "Build the page outline" or "inspect the Hx structure."

Workflow

1. Get the URL list. Use the sf-analyzer audit (audit.json → pages[].url or Internal:All). If no URL was provided, ask for one page or a set of pages. Process each URL separately.
2. Download and parse the HTML in DOM order (requires pip install lxml):

   curl -sL -A 'Mozilla/5.0 (audit heading-outline)' "$URL" -o /tmp/page.html
   python - "$URL" <<'PY'
   import sys, re
   from lxml import html
   url = sys.argv[1]
   doc = html.parse('/tmp/page.html').getroot()
   # All h1..h6 elements in document order
   nodes = doc.xpath('//h1|//h2|//h3|//h4|//h5|//h6')
   out = []
   for n in nodes:
       lvl = int(n.tag[1])
       txt = re.sub(r'\s+', ' ', n.text_content()).strip()
       out.append((lvl, txt))
   # Print the indented outline
   for lvl, txt in out:
       print('  ' * (lvl - 1) + f'H{lvl}: ' + (txt or '∅ (empty)'))
   PY
   

   For a JS-heavy SPA, curl returns an empty shell; in that case, use rendered HTML from sf-analyzer mode A (Store Rendered HTML), or warn that rendering is required.
3. Check the hierarchy using the collected (level, text) list:
   • Exactly one H1. 0 → H1_MISSING; ≥2 → H1_MULTIPLE (output every text).
   • No skipped levels. The level must not increase by more than 1 in a single step: H3 may follow H2, but H2→H4 is an error (HEADING_SKIP). A heading may drop to any level (H4→H2 is valid).
   • H1 comes first. If an H2+ occurs before the first H1 → H1_NOT_FIRST.
   • H1 is not empty and does not match <title> verbatim (H1_EQUALS_TITLE).
   • Text is meaningful: not empty, longer than ~2 characters, and not just numbers, icons, "Read more," or "Read"; these are "decorative" headings (HEADING_DECORATIVE).
   • No duplicate text among headings on the same page (HEADING_DUP_TEXT).
4. Summarize the result. For each page, provide the indented outline (from step 2) plus a list of detected issues, including the level and text of the offending heading. For a set of pages, provide a summary such as "N pages with hierarchy issues" and the most common issue types.