The HTML Report

The HTML Report checks your markup for structure, semantic element use, and common best practices. Good HTML is the foundation of accessible, maintainable, and search-friendly sites. Use these findings to practice refining your markup as you build.

How it works

When you submit a solution, we use html-validate to run an automated check on your HTML. The report flags common issues such as incorrect element nesting, missing semantic elements, and improper heading structure.

Going deeper with the AI code review

These automated checks catch concrete, rule-based issues. For feedback that looks at your semantic structure in the context of your whole solution, the AI code review scores your code across several dimensions, including Best Practices and Accessibility. Pro members get it on every submission, and free members get one a month. See The AI Code Review to learn more.

Common issues detected

Not using semantic elements

The report flags when <div> elements are used where semantic elements would be more appropriate.

Instead of:

<div class="header">...</div>
<div class="navigation">...</div>
<div class="main-content">...</div>
<div class="footer">...</div>

Use:

<header>...</header>
<nav>...</nav>
<main>...</main>
<footer>...</footer>

Incorrect element nesting

Certain HTML elements have rules about what they can contain. The report catches violations like block elements improperly nested inside inline elements.

Missing headings in sections

Section elements should typically contain headings to provide document structure. The report flags <section> elements that lack heading elements.

Improper heading hierarchy

Headings should follow a logical order without skipping levels.

Instead of:

<h1>Page Title</h1>
<h3>Section</h3>  <!-- Skipped h2 -->

Use:

<h1>Page Title</h1>
<h2>Section</h2>

Framework false positives

Some JavaScript frameworks (like React, Vue, or Angular) automatically add attributes to HTML elements that aren't technically valid HTML but are crucial for how the frameworks work.

If you're using a framework and see many HTML validation errors related to attributes, these are often benign and a necessary part of how the framework works. Focus on the semantic and structural issues rather than framework-specific attribute warnings.

Why semantic HTML matters

Accessibility: screen readers use semantic elements to help users navigate. People can jump straight to <main> content or skip past navigation.

SEO: search engines use semantic structure to understand your content and how it's organized.

Maintainability: semantic HTML is self-documenting. The purpose of each section is clear without reading class names.

Quick reference

| Element | Use for | | --- | --- | | <header> | Introductory content, navigation | | <nav> | Major navigation blocks | | <main> | Primary page content (one per page) | | <article> | Self-contained, reusable content | | <section> | Thematic grouping with a heading | | <aside> | Tangentially related content | | <footer> | Footer content, copyright, links |

Acting on your report

Review your HTML Report findings and prioritize:

1. Errors first: these indicate invalid HTML that could cause problems.
2. Warnings second: issues worth addressing for better quality.
3. Info items: best-practice suggestions to consider.

As you build more solutions, semantic HTML becomes second nature, and your code gets more accessible and maintainable along the way.