Heading outline repair

Headings form a document outline that both assistive technology and search engines rely on. Levels chosen for visual size rather than hierarchy produce an outline that says something different from the page. This skill repairs the structure without changing the design.

The skill file

---
name: heading-outline-repair
description: Use when a page reads well to a person but its heading structure is illegible to a crawler or a screen reader.
---

# Heading outline repair

Headings form a document outline that both assistive technology and search engines rely on. Levels chosen for visual size rather than hierarchy produce an outline that says something different from the page. This skill repairs the structure without changing the design.

## What you need first

- The rendered page
- Its visual hierarchy as designed

## Method

1. Extract every heading in document order with its level, ignoring styling entirely.
2. Check for the three structural faults: no H1, more than one H1, and skipped levels such as an H2 followed directly by an H4.
3. Read the extracted outline on its own. If it does not describe the page, the levels are wrong regardless of how the page looks.
4. Check what is inside the H1. Hidden text intended for screen readers, or a rotating headline element, can inflate the heading to hundreds of characters - a human sees a short headline while a crawler reads a paragraph.
5. Fix by changing levels to match meaning, then restore appearance with CSS. Size and level are independent.
6. Move any screen-reader-only sentence out of the heading to a sibling element, so assistive technology keeps it while the heading stays short.

## What this produces

A corrected outline, plus any hidden content removed from headings and relocated without loss.

## Where this goes wrong

- Choosing heading level by font size
- Leaving visually-hidden text inside an H1, which inflates it for crawlers
- Using multiple H1s because a framework template emits them

---

From the QuQi skill library - https://www.quqi.io/skills/heading-outline-repair

What you need first

• The rendered page
• Its visual hierarchy as designed

Method

1. 01 Extract every heading in document order with its level, ignoring styling entirely.
2. 02 Check for the three structural faults: no H1, more than one H1, and skipped levels such as an H2 followed directly by an H4.
3. 03 Read the extracted outline on its own. If it does not describe the page, the levels are wrong regardless of how the page looks.
4. 04 Check what is inside the H1. Hidden text intended for screen readers, or a rotating headline element, can inflate the heading to hundreds of characters - a human sees a short headline while a crawler reads a paragraph.
5. 05 Fix by changing levels to match meaning, then restore appearance with CSS. Size and level are independent.
6. 06 Move any screen-reader-only sentence out of the heading to a sibling element, so assistive technology keeps it while the heading stays short.

What this produces

A corrected outline, plus any hidden content removed from headings and relocated without loss.

Where this goes wrong

• Choosing heading level by font size
• Leaving visually-hidden text inside an H1, which inflates it for crawlers
• Using multiple H1s because a framework template emits them

More in On-page SEO