The Document Outline Algorithm

Technical Deep Dive & Specifications

The Historical Dream of the HTML5 Outline Algorithm

When HTML5 was drafted between 2004 and 2011, Section 4.3.11 of the specification defined an automatic algorithm:

• Every sectioning element (<article>, <section>, <nav>, <aside>) created a new nested outline scope.
• Inside any sectioning element, developers could start fresh with an <h1>.
• The browser was supposed to dynamically compute the outline depth:
  • Root <h1> = Rank 1
  • <section><h1> = Rank 2 (equivalent to <h2>)
  • <section><section><h1> = Rank 3 (equivalent to <h3>)

Why It Failed and Was Abandoned

1. Browser Engines Refused to Implement: Chrome (Blink), Firefox (Gecko), and Safari (WebKit) never built native user-agent styling or DOM tree APIs to calculate outline levels dynamically due to performance and backwards-compatibility concerns.
2. Screen Readers Never Supported It: Screen readers (JAWS, NVDA, VoiceOver) read heading levels directly from the HTML element's tag name (tagName === 'H1'). They never recalculated heading levels based on nested <section> depth.
3. Severe Accessibility Harm: Web developers who adopted the "all <h1>" pattern inadvertently created catastrophic accessibility failures where screen reader users lost all sense of document hierarchy.
4. Official Spec Clarification: WHATWG and W3C updated the specification with explicit warnings advising authors to use explicit heading levels (<h1> through <h6>) and to avoid relying on the outline algorithm.

+-------------------------------------------------------------------------------+
|                    SPECIFICATION STATUS COMPARISON                            |
+-------------------------------------------------------------------------------+
| Feature                          | Spec Intent (2011) | Current Reality (2026)|
+----------------------------------+--------------------+-----------------------+
| Auto-demoting <section><h1>      | Intended Feature   | Abandoned / Anti-pattern
| Monotonic <h1>–<h6> hierarchy    | Legacy Fallback    | Strict Gold Standard  |
| Single <h1> per page             | Discouraged        | Recommended Standard  |
| Accessible Tree Heading Level    | Calculated Rank    | Hardcoded Tag Name    |
+----------------------------------+--------------------+-----------------------+

The Explicit Monotonic Heading Rule

To guarantee 100% compliance with WCAG 2.1 Success Criterion 1.3.1 (Info and Relationships) and SC 2.4.6 (Headings and Labels), follow these strict rules:

  <h1> Top-Level Page Entity (Only 1 per page)
   |
   +---> <h2> Major Section Heading A
   |      |
   |      +---> <h3> Sub-topic A.1
   |      |      |
   |      |      +---> <h4> Detail A.1.a
   |      |
   |      +---> <h3> Sub-topic A.2
   |
   +---> <h2> Major Section Heading B
          |
          +---> <h3> Sub-topic B.1

Rule 1: Exactly One <h1> Per Document

The <h1> represents the title of the entire document (e.g., the title of the article, the name of the tool, or the dashboard title). Having multiple <h1> elements fragments the primary topic identity.

Rule 2: Never Skip Heading Levels Downward

Do not jump from <h1> directly to <h3> or <h4> just because you want smaller visual text. Skipping levels creates a "broken branch" in the screen reader's heading navigation rotor:

• ✅ Valid: <h1> → <h2> → <h3> → <h2>
• ❌ Invalid: <h1> → <h3> (Skipped <h2>!)
• ❌ Invalid: <h2> → <h5> (Skipped <h3> and <h4>!)

(Note: Ascending jumps upward are perfectly legal—e.g., going from <h4> back up to <h2> when closing a subsection).

Heading Strategies in Component Architectures

In component-driven architectures (React, Vue, Angular, Svelte), a shared <Card> or <Widget> component might appear at different depths in different views.

// SENIOR ARCHITECTURAL PATTERN: Dynamic Heading Level in React
function Widget({ level = 2, title, children }) {
  const HeadingTag = `h${Math.min(Math.max(level, 1), 6)}`;
  return (
    <section className="widget-card">
      <HeadingTag className="widget-title">{title}</HeadingTag>
      <div className="widget-content">{children}</div>
    </section>
  );
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Line 19 (<h1>): The singular, top-level root heading defining the core topic of the document.
• Line 26 (<h2>1. Maritime Freight Corridors</h2>): The first primary section heading beneath <h1>.
• Line 31 (<h3>1.1 Port Congestion Modeling</h3>): A valid monotonic step from level 2 to level 3.
• Line 35 (<h4>Berth Allocation Invariants</h4>): A valid monotonic step from level 3 to level 4.
• Line 42 (<h2>2. Intermodal Rail Connectivity</h2>): A valid structural ascension from level 4 back up to level 2 to begin the next major section.
• Line 46 (<h3>2.1 Rolling Stock Telematics</h3>): A valid monotonic descent from level 2 to level 3.

Expected Browser Render Output

Global Logistics & Supply Chain Architecture
Real-time optimization models for multi-modal freight networks.
--------------------------------------------------------------------------------

1. Maritime Freight Corridors
Maritime transport accounts for roughly 80% of international trade by volume.

  | 1.1 Port Congestion Modeling
  | Queueing algorithms estimate container dwell times using AIS tracking...
  | 
  | BERTH ALLOCATION INVARIANTS
  | Vessels must be serviced within strict dynamic tidal windows.

2. Intermodal Rail Connectivity
Transitioning dry cargo from maritime container yards to inland freight networks.

  | 2.1 Rolling Stock Telematics
  | IoT vibration sensors transmit axle temperature and wheel stress metrics...