How To Encourage Proper Headings In Webpages

By Cory LaViska on June 28, 2019

Using headings properly in a webpage will improve its structure and make it easier for humans and automated tools to consume content. Here's how you can encourage the use of proper headings in Surreal CMS.

A young boy holding a book.

Every now and then, someone asks if there's a way to disable certain heading levels in the editor. I understand why they're asking for this. For example, a client has decided to make some content bigger using <h1>, ignoring its semantic meaning and borking the page structure.

I experimented with this in previous versions of Surreal CMS by letting admins disable various toolbar options. However, disabling an option meant it was disabled for all pages. This turned out to be a bad solution, and I've since backpedaled on it.

Disabling things like headings doesn't teach clients how to use them properly, it just stops them from using them altogether. There are often times when it makes sense to use an <h1> or <h2> on one page, but not so much on another page.

So how do we encourage the proper use of headings everywhere?

Taking Inspiration From Word Processors

I've thought about this a lot, and the solution I came up with aligns closely with how spell checkers work. When you spell a word incorrectly, a word processor will usually underline it in red to tell you that something might not be right. It doesn't force you to fix it — it just says "hey, double check this!"

We can use that same idea with headings to let clients know that they might be using them wrong. For example, in my blog the post title is an <h2>, so there shouldn't be any <h1> or <h2>  elements inside the post's content. To discourage myself from using the wrong heading level, I've added the following styles.

/* Discourage high-level headings in blog posts */
.is-cms .post-content h1,
.is-cms .post-content h2 {
  text-decoration: underline wavy;
  text-decoration-color: tomato;
}

If I accidentally use an <h1> or <h2>, I'll see something like the image below. (Thanks to the .is-cms selector, the wavy underline will only show up in the editor, not on the live webpage.)

A heading with a red wavy underline
Yes, tomato is a valid CSS color name and it's awesome

This prompts me to reconsider using this heading level, but it doesn't stop me from using it if I really need to. And because I've specifically targeted the post content, I can safely use <h1> or <h2> on other pages where they may be more appropriate. The same technique can be used to discourage other elements depending on where they appear on the page.


Most clients aren't trying to destroy their content. Sometimes they just get lost thinking about how a page looks rather than what it says. Using this technique, you can encourage the proper use of headings and other elements without having to disable them altogether.