Semantic HTML for Agents

If you received a low Semantic Density score in our Agent Scanner, it means your website relies too heavily on generic <div> tags.

Why Agents Hate “Div Soup”

When an AI agent (like ChatGPT or a web scraper) reads your code, it doesn’t see the visual layout. It sees the raw HTML tree.

If your site looks like this:

<div class="header">...</div>
<div class="content">
  <div class="article">...</div>
</div>
<div class="sidebar">...</div>

The agent has to guess which part is the actual content. This burns “tokens” and increases the chance it will hallucinate or miss your main documentation.

The Fix: Use Explicit Tags

By swapping generic tags for semantic ones, you tell the agent exactly what each section is.

Generic Tag	Semantic Replacement	What it tells the Agent
<div class="nav">	<nav>	”This is navigation, not content.”
<div class="post">	<article>	”This is the main content. Read this first.”
<div class="sidebar">	<aside>	”This is related info, but optional.”
<b> / <i>	<strong> / <em>	”This word is important.”
<div onclick="...">	<button>	”This is an interactive element.”

Example: Before vs. After

❌ Bad (Low Scanner Score)

<div id="main">
  <div class="blog-post">
    <div class="title">How to Fix Legacy Code</div>
    <div class="body">
       ... content ...
    </div>
  </div>
</div>

✅ Good (High Scanner Score)

<main id="main">
  <article>
    <h1>How to Fix Legacy Code</h1>
    <section>
       ... content ...
    </section>
  </article>
</main>

Quick Wins for Astro Users

If you are using Astro or Starlight, you are likely already doing well, but check your custom components.

1. Wrap your main layouts in <main>.
2. Use <nav> for any table of contents or sidebar links.
3. Use <code> and <pre> for code blocks (agents look for these specifically to extract snippets).

Validate Your Fix

1. Deploy your changes.
2. Run the Agent Scanner again.
3. Your Semantic Density percentage will increase, boosting your overall score.