Skip to main content

Blog Post

Why Good Markup Matters

I recently had the opportunity to work on a project for one of our clients that consisted of building two landing pages using only HTML, CSS and JavaScript. This is not a typical project for us, almost all of the projects we work on are Drupal projects. However, it was a reminder of how great things can be when we have full control of markup authoring.

After working with Drupal for a while, not having to deal with 10 nested divs just to get to the element I want to theme, was refreshing.

The problem with poor markup is not simply how difficult it can be to theme a site - it’s deeper than that. I have been working with Drupal for a while and I think is the best CMS, but when people ask what, if anything, I would change about Drupal my answer is always “markup”. For those using Drupal, of course, this is not a secret. One of Drupal’s shortcomings is not being able to output good markup out of the box.

There are modules out there that allow you to clean things up a bit and a lot can be done during development to ensure cleaner and more semantic markup is produced. In addition, when working with views, we can have a lot of control of the markup we generate by configuring fields settings or choosing to remove Drupal’s specific classes or markup.

The joke around the Drupal community is how many levels deep will div wrappers go on any given field that is output by Drupal. Here’s is an example of how Drupal outputs a simple anchor field:

Example of nested markup

Image 1: The image above shows how an anchor/link is rendered. I should mention that the link outlined above is the first item displayed on this particular page and yet the levels of wrappers around that link is quite long.

Granted, the screenshot above reflects markup of a drupal site that is using the Panels module which usually adds more markup to the content.

Here’s how that markup would look if I could hand-craft it:

Example of good markup

Image 2: The markup above is how it would look in a perfect world.

I realize we won’t be able to get perfect markup from Drupal, or any other CMS for that matter, but we should always make an effort to ensure we are producing the best markup possible on our sites.

In addition to markup, another issue I usually deal with when working with a Drupal site is the default CSS classes Drupal adds to the markup it generates. Often times these classes are generic and do not properly describe the content at hand. Furthermore, these classes are shared among many of the page elements, whether they are related or not (Image 1 above shows several instances of ".field-item(s)" class). This increases the complexity of theming because, if not properly handled, we could end up with a mess in our hands when theming the site.
So, in addition to providing good markup, it is also important to assign appropriate CSS classes to the main elements we’re working with.

So what’s the big deal?  The website renders and works well despite the river of divs. Well, here are some reasons why cleaner and semantic markup as well as proper class names matter:


There is no question from the two markup examples above that cleaner markup is easier to read and make sense of. From development point of view cleaner markup is also easier to debug and saves time.


When I think about maintainability I’m not necessarily thinking of the HTML because the CMS does that for us. I am referring to maintainability of the styles associated with the markup. As I briefly touched on above, not assigning the right CSS classes to our key page elements can result in bloated and disorganized CSS that has no logic because the classes associated with the elements have absolutely no meaning.

You may be able to get the site themed, but the challenge will be six months or a year later when you need to tweak things and you can’t find your way around the styles.
Personally, I think good and semantic markup goes hand and hand with good use of CSS classes. With HTML5 we can even associate roles to our elements allowing us to use those roles when styling. HTML5 improves the way markup is written using semantic names for many elements but without a proper CSS class or role assigned we could end up in the same place as before. After all, with HTML5 we could have 10 <header> elements in a page.


When optimizing our sites for performance we can’t disregard markup. When the browsers renders a page it needs to go through every HTML element from top to bottom. If we are providing a large number of unnecessary divs the rendering process will not only take longer but it also means that the page’s weight will be heavier translating into more data consumption.

This article has great information on how bloated markup can not only affect performance but also how search engines rank your site.

Time savings

Sometimes we need to choose between spending more time upfront during development to produce better markup or wait until we get to theming and find the way to work with the provided markup. The extra time will be spent no matter what, so why not do it during the process when we decide how our markup will look as we develop our code? (I think I just made a bunch of enemies).

Here is my argument: if you don’t spend enough time on improving the markup during development, the themer will need to find workarounds for ensuring the site is properly themed regardless of what the markup looks like. So, as a company, you have not saved time. The problem is that even though your site looks and works great, under the hood, things are a mess and that could potentially create problems in the future when someone updates the styles and accidentally alters something that was not supposed to be changed because of the generic classes provided by Drupal.
If we take more time during development to produce better markup, assign the right CSS classes, the theming process will be smoother and although the end product, from the site’s visitor point of view, is the same, we have a product that is more polished and is easier to work with in the future.

Keep in mind that the goal is not to make things easier for themers or to save time, the goal is to ensure we are producing the best markup with the right classes possible.

Good Semantics

I mentioned earlier that HTML5 offers new elements that improve semantics in markup. What used to be a meaningless div can now be a <nav>, <header>, <footer>, etc. Now we know just by looking at the code the kind of content that is expected on a particular area of the site.

Page ranking

One of the things search engines love is well-structured and semantic markup. Google will give higher priority to a block of text that is within a <p> tag than say, a <div> with no class. 

Search engines look at whether your content is properly structured and have certain expectations of what your markup should look like. For example, search engines expect to find a <h1> as the title of an article and as you move down the page, depending on the importance of content, expect to find <h2> - <h6> accordingly. Read more about this.

Another factor for ranking websites is how well the website performs and as we discussed earlier, bloated markup can affect performance. Performance issues may not be as evident on your laptop or desktop computer while in a high speed wifi connection but what if the site is being accessed in a low 3G connection on a mobile device?  This could significantly affect your website ranking especially after google recently announced they are taking mobile-friendly websites as a ranking factor.


Lately we at Mediacurrent have been discussing accessibility a lot in an effort to make our website accessible to as many people as possible. Audio interfaces present content linearly to users, one item at a time. This contrasts with the way in which most people use visual interfaces. Sighted users can scan an entire screen almost instantaneously, comprehending the overall layout, the artistic style, and other macro-level aspects of the content. Screen reader users cannot comprehend these macro-level aspects as quickly. Users must progress through such systems in a step-wise manner. The insight that audio interfaces are linearized versions of web content is an important one that should guide web developers during engineering and design process.

If we look at the example of not so good markup above, we realize that it would be pretty painful for a person with disability to go through all the divs just to get to a piece of valid content. Well-formatted markup is not only good for looks but in a way it’s the moral thing to do.

Responsive Design

One of the recommendations when building a responsive website is to provide a natural content flow at all breakpoints. Forcing content placement with position properties could result in unexpected side effects if the markup is not where it needs to be. In addition, styles become hard to maintain and fragile because we are forcely keeping content in place even if it’s not the natural thing to do.

I have experienced this first hand and it’s not only a nightmare to theme but the user experience as you move from breakpoint to breakpoint is poor and it feels forced and made up versus feeling natural.

So whose job is it to ensure markup is done right?  Many times the project type or deadline may determines where this issue will be addressed. Some may argue themers should handle markup since they will be the ones affected the most, however the issue is that by the time work makes it to the themer’s desk markup is already in place and cleaning it up may require additional development work. I strongly feel the best place to address and plan well-structured markup is during development where decisions are made about how things will be laid out. This is not to say it is the back-end developers responsibility, this is something that should be planned and worked out by front and back-end developers.

As themers, it is our responsibility to make sure back-end developers know and understand what our expectation for markup is.  We can’t let developer think that whatever markup Drupal provides will just work. We (themers) know badly structured markup makes theming more complicated and is to our benefit that we work with better markup.

The truth is that there are more benefits than the ones outlined above when using good markup, these include:

  • Natural content flow
  • Better transition of content placement in responsive design
  • Less use of CSS hacks to achieve desired content placement and layouts
  • Not forcing content through position properties

One of the things I’ve done with developers in the past is provide them with snippets or code of what I expect for a specific item such as a slider or a page layout. Even if they can’t give me 100% of what I’m asking, I’m still getting better markup than if I just leave it up to Drupal.

Here’s an example of the markup I asked for while trying to theme a site’s carousel:

<div class="carousel-container">
  <div class="carousel-image">
    <img src="" alt="Image alt text">
  <div class="carousel-overlay">
    <div class="carousel-fields">
      <div class="slide-title">
          <a href="#">Slide title here</a>
        <div class="slide-description">
          <p>Slide teaser goes here</p>

Here is what the end result was:

Although the markup above is not perfect, it provides exactly the source order I needed and most importantly, the css classes I asked for.  This not only made theming easier but it also provides a better user experience as content in the carousel floats naturally when we move through various breakpoints.

In closing, I realize that it’s hard to get perfect markup when working with a CMS, any CMS, however, we should always make an effort to get the best markup possible and we can only do this if front-end and back-end developers are on the same page as to what the expectation is.  Providing back-end developers with detailed markup snippets has proven successful for me.

SEO Keyword Strategy eBook

Additional Resources

Using Sass Breakpoints Effectively | Mediacurrent Blog Post
Web Accessibility Terminology | Mediacurrent Blog Post

Mario Hernandez

Meet team member, Mario Hernandez

Mario is a Senior Front End Developer with over 10 years of Drupal experience. He is a regular speaker and trainer at tech conferences including Drupal Camps in Los Angeles, San...

Learn more about Mario >
Access icon Up arrow icon Drupal 8 icon Facebook icon - white Facebook icon - blue outline Facebook icon - yellow Hollow right arrow icon Hollow right arrow icon - white LinkedIn icon - white LinkedIn icon - hollow LinkedIn icon - blue outline LinkedIn icon - yellow Mediacurrent wordmark Quote icon Twitter icon - white Twitter icon - hollow Twitter icon - blue outline Twitter icon - yellow Youtube icon - white Youtube icon - yellow