Skip to content
Browse all guides

Issue #141 · important

This issue checks whether your web pages use HTML5 semantic landmark elements correctly.

What is this issue?

This issue checks whether your web pages use HTML5 semantic landmark elements correctly. Semantic landmarks are special HTML tags that clearly define different sections of a page, making it easier for browsers, search engines, and assistive technologies to understand the page structure.

The audit verifies the presence and proper use of these core semantic elements:

  • <main> — Identifies the primary content of a page
  • <nav> — Marks navigation menus
  • <header> — Defines page or section headers
  • <footer> — Defines page or section footers
  • <article> — Identifies self-contained content
  • <section> — Groups related content
  • <aside> — Marks complementary content (sidebars, related links)

A passing implementation should have:

  • Exactly one <main> element per page (or an ARIA role="main" as a fallback)
  • Appropriate landmark elements where semantically meaningful
  • Landmark elements that contain actual content (not empty)
  • No block-level elements nested inside inline elements

Example of good implementation:

<body>
  <header>
    <h1>Website Title</h1>
    <nav>Navigation menu</nav>
  </header>

  <main>
    <article>
      <h2>Article Title</h2>
      <p>Article content...</p>
    </article>
  </main>

  <aside>
    <p>Related links</p>
  </aside>

  <footer>
    <p>Copyright information</p>
  </footer>
</body>

Why does it matter?

Using semantic HTML5 landmarks is crucial for several reasons:

  • Accessibility: Screen readers and assistive technologies rely on landmarks to help users navigate page content efficiently. Missing or incorrect landmarks make your site inaccessible to visually impaired users.

  • SEO and Rankings: Search engines use semantic structure to better understand page content and context. Clear landmarks help search engines identify primary content versus navigation, sidebars, or footers, which can improve how your pages are indexed and ranked.

  • User Experience: Semantic landmarks improve keyboard navigation and make your site more usable for people relying on assistive technologies.

  • AI Search / AEO (Answer Engine Optimization): As AI-powered search engines and voice assistants become more prevalent, they use semantic HTML to extract and understand content structure. Proper landmarks help AI systems identify the most relevant content to answer user queries.

Resolving this issue improves your overall SEO health score by ensuring your site is accessible, well-structured, and easily understood by both search engines and assistive technologies.

How to fix it

  1. Add a <main> element: Ensure every page has exactly one <main> element that wraps the primary content. If you cannot use the <main> tag (e.g., legacy systems), add role="main" to the appropriate container div.

  2. Use semantic tags appropriately: Replace non-semantic <div> elements with appropriate semantic landmarks:

    • Use <nav> for navigation menus
    • Use <header> for page or section headers
    • Use <footer> for page or section footers
    • Use <article> for self-contained content pieces
    • Use <section> for grouping related content
    • Use <aside> for sidebars or complementary content

  3. Ensure landmarks contain content: Make sure semantic elements are not empty. They should contain meaningful content, headings, or links.

  4. Fix multiple <main> elements: If your page has multiple <main> elements, consolidate them into a single <main> element.

  5. Add ARIA roles as fallbacks: When semantic tags cannot be used, add appropriate ARIA roles (role="navigation", role="banner", role="contentinfo", etc.) to non-semantic elements.

  6. Fix nesting errors: Ensure block-level elements are not placed inside inline elements (e.g., don't put a <div> inside an <a> tag).

  7. Handle client-side rendered content: If your site uses JavaScript to render content client-side, ensure the initial HTML shell includes proper semantic landmarks, or use server-side rendering to deliver semantic HTML to crawlers.

Examples

Example 1: Proper semantic HTML structure

Scenario: A typical webpage with clear content sections.

Problematic state (what fails):

<body>
  <div id="header">
    <h1>Website Title</h1>
    <div id="nav">Navigation menu</div>
  </div>

  <div id="content">
    <div class="post">
      <h2>Article Title</h2>
      <p>Article content...</p>
    </div>
  </div>

  <div id="sidebar">
    <p>Related links</p>
  </div>

  <div id="footer">
    <p>Copyright information</p>
  </div>
</body>

Corrected state (what passes):

<body>
  <header>
    <h1>Website Title</h1>
    <nav>Navigation menu</nav>
  </header>

  <main>
    <article>
      <h2>Article Title</h2>
      <p>Article content...</p>
    </article>
  </main>

  <aside>
    <p>Related links</p>
  </aside>

  <footer>
    <p>Copyright information</p>
  </footer>
</body>

Example 2: Multiple main elements (incorrect)

Scenario: Page incorrectly has multiple main elements.

Problematic state (what fails):

<body>
  <main>First main content</main>
  <main>Second main content</main>
</body>

Corrected state (what passes):

<body>
  <main>
    <section>First content section</section>
    <section>Second content section</section>
  </main>
</body>

Example 3: Empty semantic elements

Scenario: Semantic elements without content.

Problematic state (what fails):

<body>
  <header></header>
  <main></main>
  <footer></footer>
</body>

Corrected state (what passes):

<body>
  <header>
    <h1>Site Title</h1>
  </header>
  <main>
    <p>Page content here</p>
  </main>
  <footer>
    <p>&copy; 2024 Company Name</p>
  </footer>
</body>

How PixyScan detects this

PixyScan uses a straightforward process to identify semantic HTML issues:

  1. Fetches the page: PixyScan downloads the HTML content of the page (respecting robots.txt rules) with a reasonable timeout.

  2. Parses the HTML: The crawler analyzes the static HTML structure without executing JavaScript (though it can detect if client-side rendering may require additional checks).

  3. Checks for required landmarks: PixyScan looks for the presence of key semantic elements:

    • Checks if there's exactly one <main> element (or role="main" attribute)
    • Checks for presence of <nav>, <header>, and <footer> elements
    • Identifies <article>, <section>, and <aside> elements

  4. Validates landmark usage: For each semantic element found, PixyScan checks:

    • Whether the element contains actual content (not just empty or whitespace)
    • Whether there are multiple <main> elements (which is incorrect)
    • Whether non-semantic <div> elements are being used as landmarks without ARIA roles

  5. Checks for nesting errors: PixyScan identifies incorrect HTML structure where block-level elements (like <div>, <p>, headings) are placed inside inline elements (like <a>, <span>, <strong>).

  6. Generates issues: Based on these checks, PixyScan flags problems with appropriate severity:

    • CRITICAL: Missing <main> landmark
    • WARNING: Multiple <main> elements, missing navigational landmarks, or empty semantic elements
    • SUGGESTION: Non-semantic wrappers that should use semantic elements

The detection focuses on the static HTML delivered by the server. For pages that heavily rely on client-side JavaScript to generate content, PixyScan may recommend additional rendering-capable validation.

References