Writing Standards-Compliant HTML

January 17, 20197 min read

The importance of quality Hypertext Markup Language (HTML) in any codebase cannot be over-emphasized. HTML is the backbone of any website, the skeleton fleshed out with CSS and brought to life with JavaScript.

Though markups render when standards are not adhered to, we need to strive towards writing standards-compliant code. Accessibility cannot be achieved without quality and semantically valid HTML.

Let's go through the basic elements that makes up a HTML page, coding practices which are usually neglected and ways we can write standards-compliant HTML.

Doctype

This is often neglected. Doctype explains the document type being rendered on websites. You should always include it when writing your markup.

<!DOCTYPE html>

Lang attribute

The lang attribute is essential in any website. lang attribute within html element plays an important role especially when considering internationalization (i18n).

<html lang="en"></html>

In a french version of your site, it should be written as

<html lang="fr"></html>

Character encoding

The first content of the head section should be the character encoding declaration. The browser needs to know the encoding to use when rendering the content of a site. Therefore, this should be written before any other element within the head section.

<head>
  <meta charset="utf-8" />
</head>

Entity reference

Entity reference should be used for characters with special meaning in HTML

Character	Reference	Description
&	`&`	Ampersand
"	`"`	Quotation mark
'	`'`	Apostrophe
<	`lt;`	Less than
>	`gt;`	Greater than

Content of Title element

The title element should not be left without a content. The title of the page should be written first, followed by a separator before the title of the site.

<title>Writing Standards-Compliant HTML | Chiamaka Ikeanyi</title>

Indentation

Of what use is a code if it is not readable? We need to ensure that the lines of code we write are properly indented showing hierarchy.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Coding Style</title>
  </head>
  <body>
    <main>
      <section><p>content</p></section>
    </main>
  </body>
</html>

The above code is messed up. To avoid this, for every new element, always indent using the tab key or by leaving 2 spaces. Closing elements should correspond to the opening elements.

If you find this really tasking, Prettier extension can help with that. Go through the "Get Started" guide to set it up.

Separation of concerns

Despite being in this era of CSS in JS, i'm still of the opinion that HTML, CSS and JS files are meant to be kept in different files. Structure, presentation and behaviour should not be muddled up in one file. Not only do this improve readability of the code, it makes it reusable also.

You can always import your CSS and JS files using

<link rel="stylesheet" href="path_to_file.css" />

and

<script src="path_to_file.js"></script>

respectively

Use elements appropriately

Elements are often misused. We need to use the right elements for the right reasons. It is not appropriate to use an a element where button should be used (vice versa) or a div instead of a button and assign a button value to its role attribute. Avoid divitis (the act of writing many div elements in place of meaningful semantic HTML elements), there is no need to use a div element where we are meant to use a p or semantic element.

<!-- bad code -->
<div class="wrapper">
  <input type="text" placeholder="Search..." />

  <p class="header">Main Title</p>
  <div class="description">
    <p>Short description</p>
    <br /><br />
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    <button class="link" onclick="navigateSomewhere()">Learn more</button>
  </div>
</div>

<!-- good code -->
<div class="wrapper">
  <input type="search" placeholder="Search..." />

  <article>
    <header>
      <h1>Main Title</h1>
    </header>
    <p>Short description</p>
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
    <a href="https://domainname.topleveldomain" target="_blank">Learn more about the main title </a>
  </article>
</div>

 and  may yield the same result but has a different meaning for screen readers. Likewise <bold> and . Having an understanding of the appropriate usage of these elements will help you write better HTML code.

Semantic elements - main, nav, section, article, aside, footer should always be used to describe contents of a website instead of using a div.

Use <time> to represent a specific period instead of wrapping it within  or  tag.

<!-- bad code -->
Published on <span>January 17, 2019</span> at <span>07:00</span>

<!-- good code -->
Published on
<time datetime="January 17, 2019">
  January 17, 2019
</time>
at <time datetime="07:00">07:00 am</time>

Quotation marks

Attributes values should be enclosed in double quotation marks (" ") rather than single quotation marks (' ').

<!-- bad code -->
<a href="/explore">Explore</a>

<!-- good code -->
<a href="/explore">Explore</a>

Use alternate text on images

Provide a descriptive alternate text for images. alt attribute helps assistive technologies like screen readers to get a better understanding of the content of the element. For images used for decorative purposes (e.g. a button containing a search icon close to a Search text), it should be left empty alt="" because adding alternate text would introduce redundancy.

<!-- bad code -->
<img src="path_to_file.png" />

<!-- good code -->
<img src="path_to_file.png" alt="Descriptive text" />
<img src="path_to_file.png" alt="" />

Form Labelling

Forms elements should be associated with labels either implicitly or explicitly.

<!-- implicit label -->
<label>
  <input id="email" name="email" type="email" />
</label>

<!-- explicit label -->
<label for="email">Email Address</label>
<input id="email" name="email" type="email" />

Avoid Shouting

Writing a content in all capital letters signifies shouting. Lowercase letters should be used for your content likewise elements, attributes and values. Handle all typography and styling using CSS.

<!-- bad code -->
<h1>CODING STYLE</h1>
<p class="nav">CONTENT</p>

<!-- good code -->
<h1>Coding Style</h1>
<p class="nav">Content</p>

If you need the content to be in all capital letters, you can then use

.nav {
  text-transform: uppercase;
}

Naming Convention

Naming things can be daunting but pays off in the long run when we get it right. Id and class names should be descriptive. It needs to relate to the content, not the presentation.

<!-- bad code -->
<p class="green-notification">Order successful</p>

<!-- good code -->
<p class="order-notification">Order successful</p>

Peradventure we decide to change the color of notification in the future, it would only affect the CSS file leaving the markup untouched. However, if the first approach was used, we would need to update the class name within the markup to reflect the change.

Logical Sequence

Markups should be written in a logical sequence. This can be very useful to screen readers. Using CSS to position sections within a page which can be achieved using HTML is an overkill.

Link to external documents

The rel attribute with value of noopener noreferrer should always be added to a elements when linking to external documents.

<a href="path_to_file" rel="noopener noreferrer" target="_blank">Link text</a>

noopener: To prevent the browsing context from having an opener browsing context if a user clicks on the hyperlink.
noreferrer: To prevent the browser from sending an HTTP referrer header if a user clicks on the hyperlink.

Code Validation

Validators such as W3C validator can help pin point areas that we might have missed.

<!-- good code -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Writing Standards-Compliant HTML | Chiamaka Ikeanyi</title>
    <link rel="shortcut icon" href="path_to_image.png" type="image/png" />
    <link rel="stylesheet" href="path_to_file.css" />
  </head>

  <body class="site-body">
    <header>
      <a href="/">Site Title</a>
      <span class="sr-only">Navigation</span>
      <nav>
        <ul>
          <li>
            <a href="/about">About</a>
          </li>
          <li>
            <a href="/projects">Projects</a>
          </li>
        </ul>
      </nav>
    </header>

    <main>
      <section class="site-content">
        <article>
          <h1>Writing Standards-Compliant HTML</h1>
          <img src="path_to_file.png" alt="Descriptive alternate text" />
          <p>The article</p>
        </article>
      </section>

      <footer>
        &copy; {dynamic date} Site Title
      </footer>
    </main>

    <script src="path_to_file.js"></script>
  </body>
</html>

You must have learnt a few things here. Consider educating someone also. Let's write semantic, accessible and search engine optimized HTML and leave codebases better than we meet them.