Semantic HTML5 markup patterns for meaningful, accessible, and SEO-optimized content structure
Converts presentation-focused HTML into semantic, accessible, and SEO-friendly markup. It automatically analyzes and transforms div-soup into proper HTML5 landmarks, sectioning elements, and structured data.
/plugin marketplace add pluginagentmarketplace/custom-plugin-html/plugin install custom-plugin-html@pluginagentmarketplace-htmlThis skill inherits all available tools. When active, it can use any tool Claude has access to.
assets/config.yamlreferences/GUIDE.mdscripts/helper.pyTransform markup from presentation-focused to meaning-focused, enabling accessibility, SEO, and AI/voice interface compatibility.
Provide atomic, single-responsibility operations for:
<article>, <section>, <nav>)interface SemanticHtmlInput {
operation: 'analyze' | 'convert' | 'validate' | 'suggest';
content_type: ContentType;
markup?: string; // Existing HTML to analyze/convert
context?: {
page_type: 'homepage' | 'article' | 'product' | 'contact' | 'search';
has_sidebar: boolean;
has_comments: boolean;
};
options?: {
semantic_level: 'strict' | 'moderate' | 'minimal';
include_landmarks: boolean;
preserve_classes: boolean;
};
}
type ContentType =
| 'article' // Blog post, news article
| 'navigation' // Nav menus, breadcrumbs
| 'sidebar' // Aside content
| 'header' // Page/section headers
| 'footer' // Page/section footers
| 'section' // Generic thematic sections
| 'figure' // Images, diagrams, code blocks
| 'list' // Lists of items
| 'table'; // Tabular data
interface SemanticHtmlOutput {
success: boolean;
markup: string;
semantic_score: number; // 0-100
improvements: Improvement[];
landmark_map: LandmarkMap;
outline: DocumentOutline;
}
interface Improvement {
original: string;
suggested: string;
reason: string;
impact: 'critical' | 'high' | 'medium' | 'low';
}
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Semantic Element Decision Tree ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā¤
ā ā
ā Is it the main content? ā
ā āāā Yes ā <main> ā
ā āāā No ā ā
ā ā
ā Is it independently distributable? ā
ā āāā Yes ā <article> ā
ā āāā No ā ā
ā ā
ā Is it a thematic grouping with a heading? ā
ā āāā Yes ā <section> ā
ā āāā No ā ā
ā ā
ā Is it navigation links? ā
ā āāā Yes ā <nav> ā
ā āāā No ā ā
ā ā
ā Is it tangentially related content? ā
ā āāā Yes ā <aside> ā
ā āāā No ā ā
ā ā
ā Is it introductory or navigational content? ā
ā āāā Yes ā <header> ā
ā āāā No ā ā
ā ā
ā Is it footer/meta information? ā
ā āāā Yes ā <footer> ā
ā āāā No ā <div> ā
ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
| HTML5 Element | ARIA Landmark Role | Implicit Role |
|---|---|---|
<header> (page) | banner | Yes |
<nav> | navigation | Yes |
<main> | main | Yes |
<aside> | complementary | Yes |
<footer> (page) | contentinfo | Yes |
<section> | region | If has accessible name |
<article> | article | Yes |
<form> | form | If has accessible name |
<body>
<header>
<nav aria-label="Main">...</nav>
</header>
<main>
<article>
<header>
<h1>Article Title</h1>
<p>By <a rel="author" href="/author">Author</a></p>
<time datetime="2025-01-15">January 15, 2025</time>
</header>
<section aria-labelledby="intro">
<h2 id="intro">Introduction</h2>
<p>Content...</p>
</section>
<section aria-labelledby="main-content">
<h2 id="main-content">Main Content</h2>
<p>Content...</p>
</section>
<footer>
<p>Tags: <a href="/tag/html" rel="tag">HTML</a></p>
</footer>
</article>
<aside aria-label="Related articles">
<h2>Related Articles</h2>
<ul>...</ul>
</aside>
</main>
<footer>
<nav aria-label="Footer">...</nav>
<p>© 2025</p>
</footer>
</body>
<body>
<header>
<nav aria-label="Main">...</nav>
<nav aria-label="Breadcrumb">
<ol>
<li><a href="/">Home</a></li>
<li><a href="/products">Products</a></li>
<li><a href="/products/widgets" aria-current="page">Widget</a></li>
</ol>
</nav>
</header>
<main>
<article itemscope itemtype="https://schema.org/Product">
<h1 itemprop="name">Product Name</h1>
<figure>
<img itemprop="image" src="product.jpg" alt="Product description">
</figure>
<section aria-labelledby="description">
<h2 id="description">Description</h2>
<p itemprop="description">Product details...</p>
</section>
<section aria-labelledby="pricing">
<h2 id="pricing">Pricing</h2>
<p itemprop="offers" itemscope itemtype="https://schema.org/Offer">
<span itemprop="price" content="29.99">$29.99</span>
</p>
</section>
</article>
<aside aria-label="Related products">
<h2>You May Also Like</h2>
<ul>...</ul>
</aside>
</main>
<footer>...</footer>
</body>
| Code | Description | Recovery |
|---|---|---|
SH001 | Missing document outline | Add proper heading hierarchy |
SH002 | No main landmark | Wrap primary content in <main> |
SH003 | Multiple main elements | Keep only one <main> |
SH004 | Section without heading | Add heading or use <div> |
SH005 | Article without heading | Add <h1>-<h6> |
SH006 | Nav without label | Add aria-label |
SH007 | Div soup detected | Suggest semantic alternatives |
Analyze Input ā Identify Anti-Patterns ā Suggest Fixes ā Validate ā Report
ā
[If conversion requested]
ā
Apply automatic fixes ā Re-validate ā Return improved markup
Debug Checklist:
ā” Is <main> present and unique?
ā” Are headings in logical order (h1āh2āh3)?
ā” Do sections have accessible names?
ā” Are nav elements labeled uniquely?
ā” Is banner/contentinfo outside main?
Debug Checklist:
ā” Is <article> used for main content?
ā” Is author/date marked with rel/datetime?
ā” Are headings used (not just styled divs)?
ā” Is structured data (schema.org) present?
ā” Are images in <figure> with <figcaption>?
Conversion Guide:
<div class="header"> ā <header>
<div class="nav"> ā <nav>
<div class="main"> ā <main>
<div class="article"> ā <article>
<div class="sidebar"> ā <aside>
<div class="footer"> ā <footer>
<div class="section"> ā <section>
<div class="figure"> ā <figure>
| Factor | Weight | Measurement |
|---|---|---|
| Landmark coverage | 25% | banner, main, contentinfo present |
| Heading hierarchy | 25% | Correct h1āh6 nesting |
| Semantic ratio | 20% | semantic / (semantic + div + span) |
| Accessible names | 15% | Labeled sections and navs |
| Article structure | 15% | Proper article markup |
Score Interpretation:
# Analyze existing markup
skill: semantic-html
operation: analyze
markup: "<div class='main'><div class='post'>...</div></div>"
# Convert to semantic HTML
skill: semantic-html
operation: convert
content_type: article
markup: "<div class='blog-post'>...</div>"
options:
semantic_level: strict
include_landmarks: true
# Suggest improvements
skill: semantic-html
operation: suggest
content_type: navigation
context:
page_type: homepage
has_sidebar: true