Automatically Correcting Semantic Headings for CMS Content

# Why I Built a JavaScript Library to Fix Broken Heading Hierarchies (And Why You Need It)


So here's the thing - you spend hours building a beautiful Sitefinity site with proper accessibility in mind, semantic HTML, the works. Then you hand it off to content editors and... well, let's just say accessibility goes out the window faster than you can say "H4 followed by H6."


Sound familiar?


## The Problem: Content Editors vs. Semantic HTML


In any CMS environment (Sitefinity, WordPress, you name it), content editors think about headings one way: **styling**. They see a heading that looks big and bold, so they use H2. They want something a little smaller? H4 it is! Need something tiny for a caption? H6 all the way!


What they DON'T think about is semantic structure. And honestly, why would they? They're focused on making content look good, not whether screen readers can properly navigate the page.


The result? Heading hierarchies that look like this:


```html
<h1>Main Article Title</h1>
<h4>Introduction</h4>         <!-- Skips H2, H3 -->
<h6>Key Points</h6>           <!-- Jumps to H6 -->
<h2>Conclusion</h2>           <!-- Back to H2? Why not! -->

This breaks accessibility completely. Screen reader users rely on proper heading progression to understand and navigate content. Search engines use heading hierarchy to understand content structure. And accessibility audits? Yeah, they're going to flag this all day long.

Enter: Semantic Heading Hierarchy

After dealing with this problem on too many Sitefinity projects, I built a JavaScript library that automatically fixes broken heading hierarchies without destroying the visual design.

Here's what it does:

1. Corrects the semantic structure - Ensures proper H1 → H2 → H3 progression
2. Preserves visual appearance - Adds CSS classes so your H4 styling stays on the corrected H2
3. Maintains accessibility - Creates proper document outline for screen readers
4. Improves SEO - Gives search engines the content hierarchy they expect

The broken example above becomes:

<h1>Main Article Title</h1>
<h2 class="hs-4">Introduction</h2>     <!-- Semantically correct, visually styled as H4 -->
<h3 class="hs-6">Key Points</h3>       <!-- Semantically correct, visually styled as H6 -->
<h2>Conclusion</h2>                    <!-- Already correct -->

How It Works in the Real World

Here's the beauty of it - you just add one line of JavaScript to your Sitefinity master page:

SemanticHeadingHierarchy.fix('.main-content');

The library finds all the headings after your H1, figures out what the proper semantic progression should be, and fixes it automatically. It adds CSS classes like hs-4 and hs-6 so you can style them to match the original appearance.

No more telling content editors "don't use H4 there!" No more accessibility audit failures. No more broken screen reader navigation.

Why This Matters for Sitefinity Sites

Sitefinity gives content editors a lot of power through the rich text editor and widget designers. That's awesome for content creation, but it also means they can easily break semantic structure without realizing it.

With this library running on your site:

• Content editors can focus on content - They don't need to understand semantic HTML
• Developers get compliance - Accessibility audits pass without constant content policing
• Users get better experiences - Screen readers work properly, SEO improves
• Zero visual disruption - The library prevents layout flash by applying styling before changing tags

Installation & Setup

Get it from npm:

npm install semantic-heading-hierarchy

Or grab it from the CDN:

<script src="https://unpkg.com/semantic-heading-hierarchy@latest/dist/index.js"></script>

The key thing to remember: you need to add CSS for the styling classes. The library creates classes like hs-2, hs-3, etc., and you style them to match your original heading appearance:

h2, .hs-2 { 
    /* Your H2 styles here */
}


h4, .hs-4 { 
    /* Your H4 styles here */
}

Then just call it on your container:

// Fix headings in your main content area
SemanticHeadingHierarchy.fix('.sf_cols');


// Enable logging to see what gets fixed
SemanticHeadingHierarchy.fix('.content', { logResults: true });

The Bottom Line

Building accessible websites shouldn't require constantly policing content editors or fighting against the CMS. Sometimes you need a technical solution that just handles the problem automatically.

If you're dealing with broken heading hierarchies on your Sitefinity (or any other CMS) sites, give this library a shot. Your accessibility audits will thank you, your users will have a better experience, and your content editors can focus on what they do best - creating great content.

Links:

• GitHub Repository
• npm Package

---

Made with ❤️ for better web accessibility ```