Check heading structure hierarchy

A heading hierarchy can look correct on screen while its underlying tags tell a different story. This checker accepts heading tags in document order, such as h1, h2, h3, and h2, then applies two focused rules: the list must contain exactly one h1, and no heading may descend by more than one level at a time. It returns a clear validity result, the h1 count, and the exact position of each skipped level so editors and automated publishing systems can act on the findings.

Prepare the heading sequence in document order

Start with the heading tags exactly as they occur in the rendered document, not as they appear in a design file or content outline. A typical input might be h1, h2, h3, h2, h3. The order matters because hierarchy is expressed by the transition from one heading to the next.

The checker accepts tags from h1 through h6, ignores surrounding whitespace, and treats uppercase forms such as H2 the same as lowercase forms. It does not accept arbitrary HTML, heading text, CSS classes, or numbers standing alone. An empty list is rejected as invalid input because there is no document structure to assess.

A malformed entry is also rejected with its array index, which makes a faulty extraction step easier to diagnose. This separation is useful in pipelines: extraction determines which tags exist, while this capability evaluates only their order and levels. Keeping the stages distinct produces stable results and prevents visual styling from being mistaken for semantic structure.

Understand the two hierarchy rules

The first rule requires exactly one h1 in the complete list. A result with no h1 fails because the document has no single top-level heading, while two or more h1 tags fail because the top level is repeated. The second rule looks at each adjacent pair and reports a skip whenever the next number is more than one greater than the previous number.

Moving from h2 to h4 therefore reports a missing h3. Moving from h1 to h5 reports h2, h3, and h4 as missing in that transition. Moving upward, such as h4 to h2, is allowed because it closes nested material and returns to a broader section.

Repeating a level is also allowed, so consecutive h2 tags can introduce sibling sections. The checker reports every skip rather than stopping after the first one. Each record includes the zero-based index of the destination tag, the transition, and all missing intermediate tags.

The result is valid only when the h1 count equals one and the skipped-level collection is empty.

Use the result in reviews and publishing gates

Use the valid field for a simple pass or fail decision, then retain the detailed fields for a useful correction message. The issues array provides concise English summaries for logs, pull-request comments, or a content management interface. This capability intentionally does not judge heading wording, keyword use, visual size, empty heading text, or whether a page should contain more sections.

Those are separate content and markup concerns. It also does not fetch a URL or parse HTML; callers that begin with a page should extract the ordered tags first. Because the algorithm has no network access, randomness, clock dependency, or hidden state, the same list always produces the same response.