Choosing HTML elements is hard

February 2, 2024

When I first started building websites back in the late ’90s, we were using nested tables to achieve our layout. The semantics of HTML elements were not a thing. When I moved away from using <table> tags and started using <div> and other HTML elements, the semantics of HTML were not something I was thinking about.

I didn’t start thinking about the semantics of my code until I read Andy Clarke’s book, Transcending CSS. He spent a fair amount of time at the beginning of the book laying a solid foundation of HTML structure that we could then build our creative layouts and styling with CSS.

“In markup, semantics is concerned with the meaning of an element and how that element describes the content it contains.”
Molly E. Holzschlag

To help us understand how the semantics described the content, Andy went through several exercises to visualize the content of a design. He would walk through how to write out HTML to describe several images.

Here is a sample description:

It’s a picture of several jockeys on horses, each wearing different colored jerseys. The picture has a title, Par for the Horse.

Andy encourages his readers to approach meaningful markup by describing the content, not thinking about the presentation. We ask, “What is this?” and “What does this mean?” It is about describing the markup much like trying to describe the picture above. Ask the question, “What does the content tell you?”

He went on to show that “all the world is a list; every item must play its part.” Article listings on a homepage or archive page are lists. So Andy approached it by writing the content as lists. So the markup would look something like this:

<ul>
  <li>
     <img ... />
     <h3><a href="#">Title of the card</a></h3>
     <p>A description or teaser text</p>
  </li>
  ...
</ul>

I started seeing lists everywhere. Navigation items were an ordered list because there was usually thought behind the order of the listing. Article listings were unordered lists. Galleries could be unordered or ordered lists.

Andy also introduced an HTML tag to me, the description list item <dl>. They were originally invented to markup definition terms and their descriptions. But many had started to stretch their semantics to join “name” and “value” pairs.

I took to heart what I had read and began to be much more intentional and thoughtful in how I wrote my markup so that it described the content.

What I have found in practice is that it is much easier to mark up a blog post or article than a page with a lot of layout. I believe this is because a lot of thought was given to HTML markup at the beginning by Tim Berners-Lee and others who pioneered the markup language. That is because they were marking up documents that did not have a presentation other than the semantic description.

Things got more complicated later when layouts and styling were introduced. At first, we had very few options to use other than the humble <div>. At least at first for me in 2007 when I started taking semantics seriously. It was not until three years later that we got some new tags to help us out.

In 2010, HTML5 was introduced. And with it came tags like <header>, <footer>, <aside>, <section>, <article>, and <main>. We also got <video> and <audio> but those are not so much about the presentational semantics that I am talking about. While it was nice to get these new tags, it was often confusing as to what was the correct way to use them or what they meant.

For example, a <section> tag is supposed to also have a heading within the section to be used properly. I have had sections of a page that did not have a heading but I chose to use a <section> tag because it was another page section. The semantics meant something to me even if I was not quite following the “rules.”

I have never fully understood the <article> tag. Here is the definition from MDN:

“The <article> HTML element represents a self-contained composition in a document, page, application, or site, which is intended to be independently distributable or reusable (e.g., in syndication). Examples include: a forum post, a magazine or newspaper article, or a blog entry, a product card, a user-submitted comment, an interactive widget or gadget, or any other independent item of content.”
Mozilla Developer Network

I think the reusable part is what throws me. It makes sense to use the tag around the content of a blog post but does that also mean I can use it in a listing of blog posts where you only have the title, a short description, and a link to the post?

Going back to my earlier examples of using lists. A listing of blog posts seems like the appropriate use of a list. But somewhere along the way, I believe I read something that told me that it is wrong to have a heading and a paragraph inside a list item. So I started feeling self-conscious about using lists in this situation. At times, I think I have used an <article> tag instead but many times I went back to just using a <div>.

I am not even sure if that “advice” about not using a heading or paragraph tag inside a list item was correct. I had trouble finding anything to support it when I did a Google search as I was trying to research it for this article. But the main point of this is that I got confused and it still is something I think about when I am trying to write semantically sound HTML in a project.

Many people have said that the hardest thing in development is naming things. I wholeheartedly agree with that. But a close second or maybe even tied for the hardest thing is determining which HTML element to use to best describe the content.

And I am not the only one who feels this way. After I had conceived the idea of this post several weeks ago, I read two articles that express similar sentiments. Vadim Makeev wrote The road to HTMHell is paved with semantics and Stephanie Eckels wrote A Call for Consensus on HTML Semantics. Stephanie talked about the fact that it is not always clear-cut about which option is best. Vadim asks “Does it really make a difference?” when there is a gap between the specs and what browsers and screen readers are willing to implement. Dan Cederholm has an entire chapter in Twenty Bits I Learned about Making Websites entitled “I Never Really Understood HTML5.”

At the end of the day, you try to do your very best and know that you might choose differently down the road. You need to be careful about what advice you take. And you don’t need to get caught up in a heated online discussion about what is right or better. I think in the end you have to trust yourself as a developer and you need to get the job done today. You might think differently a year from now but what matters right now is shipping this project for the client.

“HTML markup is a skill that is honed in the fires of experience that may be learned but never mastered, but it is an honorable and worthy battle.”
Stephanie Eckels, A Call for Consensus on HTML Semantics

I would like to see some consensus or some more thought into HTML semantics going forward. Maybe we need to follow some cow paths and reimagine or stretch the semantics of elements much like Andy described with the definition list element in the past. Maybe that will lead to better solutions and more consensus (and less time having to think about what is the best element to use).

For further reading

This is a list of articles I have read in the last three years about HTML semantics.

Jeff Bridgforth

Front-end Developer

Choosing HTML elements is hard

For further reading

Comment on this post