HTML5 Style Guide

HTML Style Guide and Coding Conventions

Why Coding Conventions Matter

Consistent coding style makes HTML easier to read, understand, and maintain, especially when working in teams. While HTML5 is flexible, establishing conventions improves code quality and reduces errors.

Following best practices also helps ensure compatibility with various tools (like linters, formatters, and accessibility checkers) and future-proofs your code.

Use the Correct Document Type (DOCTYPE)

Always start your HTML document with the DOCTYPE declaration. For HTML5, it’s simple and ensures the browser renders the page in standards mode:

<!DOCTYPE html>

This should be the very first line in your HTML file.

Use Lowercase Element and Attribute Names

While HTML5 allows mixed case, the widely accepted convention is to use lowercase for all element and attribute names.

• Consistency: Avoids confusion.
• Readability: Lowercase is generally considered cleaner.
• Compatibility: Aligns with related languages like CSS and JavaScript, and stricter formats like XML.
• Tooling: Many development tools expect lowercase.

Good:

<section class="main-content">
  <p>This is a paragraph.</p>
</section>

Avoid:

<SECTION CLASS="main-content">
  <P>This is a paragraph.</P>
</SECTION>

Close All Non-Void HTML Elements

Although HTML5 allows omitting closing tags for some elements (like <p>, <li>), it’s strongly recommended to close all non-void elements explicitly.

• Clarity: Makes the document structure unambiguous.
• Maintainability: Reduces the risk of nesting errors.
• Tooling: Easier for code editors and validators to parse correctly.

Good:

<ul>
  <li>First item</li>
  <li>Second item</li>
</ul>
<p>A paragraph.</p>

Avoid (even if technically valid):

<ul>
  <li>First item
  <li>Second item
</ul>
<p>A paragraph.

Handle Empty (Void) HTML Elements Consistently

Void elements cannot have content and don’t need a closing tag (e.g., <meta>, <img>, <br>, <hr>, <input>).

HTML5 syntax allows omitting the trailing slash:

<meta charset="utf-8">
<img src="logo.png" alt="Logo">

XHTML required a trailing slash:

<meta charset="utf-8" />
<img src="logo.png" alt="Logo" />

Best Practice: Choose one style (with or without the trailing slash for void elements) and use it consistently throughout your project. Many teams omit the slash in modern HTML5.

Always Quote Attribute Values

HTML5 allows omitting quotes around attribute values under certain conditions (e.g., no spaces or special characters). However, it’s best practice to always enclose attribute values in quotes.

• Safety: Prevents errors when values contain spaces or special characters.
• Readability: Clearly distinguishes attribute values.
• Consistency: Avoids mixing styles.

Good (Use double quotes preferably):

<a href="/about-us" class="nav-link active">About</a>

Acceptable (If value contains double quotes):

<p title='The "Best" Section'>Content</p>

Avoid (Error-prone):

<a href=/about-us class=nav-link active>About</a> <!-- Avoid this -->

Double quotes (") are the most common convention, but single quotes (') are also valid.

Image Attributes (src, alt, width, height)

Always provide the src (source URL) and alt (alternative text) attributes for <img> elements.

• alt: Crucial for accessibility (screen readers) and SEO. Describes the image content or function.
• src: Specifies the path to the image file.

Including width and height attributes helps the browser reserve space, preventing layout shifts as images load.

<img src="images/product.jpg" alt="A red t-shirt with a logo" width="300" height="400">

Note: While width and height attributes set the intrinsic size, use CSS for responsive image styling (e.g., max-width: 100%; height: auto;).

Code Formatting (Indentation and Line Breaks)

Consistent indentation and logical line breaks significantly improve readability.

• Indentation: Use spaces (typically 2 or 4) to indicate nesting levels. Avoid using tabs or mixing tabs and spaces.
• Line Length: Keep lines reasonably short (e.g., under 80-100 characters) to avoid horizontal scrolling.
• Blank Lines: Use blank lines sparingly to separate logical blocks of code.

Readable Example:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Formatted Example</title>
</head>
<body>

  <header>
    <h1>Page Title</h1>
  </header>

  <main>
    <article>
      <h2>Article Heading</h2>
      <p>
        This is a paragraph with well-formatted text,
        making it easy to read and understand the structure.
      </p>
    </article>
  </main>

</body>
</html>

Tools like Prettier or editor integrations can automatically format your code.

Omitting Optional Tags (<html>, <head>, <body>)

While the HTML5 specification technically allows omitting the <html>, <head>, and <body> tags, it is strongly recommended to include them.

• Clarity: Explicitly defines the document structure.
• Accessibility: The <html> tag is the standard place to declare the page language using the lang attribute (e.g., <html lang="en">).
• Compatibility: Some older browsers or tools might have issues if these tags are missing.
• Consistency: It’s the standard structure taught and expected by developers.

Recommended Structure:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Page Title</title>
  <!-- Other meta tags, links, scripts -->
</head>
<body>
  <!-- Page content -->
</body>
</html>

Essential Meta Data

Include essential meta information within the <head> section:

• Character Encoding: Declare UTF-8 as early as possible to ensure correct character display. <meta charset="UTF-8">
• Title: The <title> element is required and crucial for browser tabs, bookmarks, and SEO. Make it descriptive. <title>Meaningful Page Title</title>
• Viewport (for Responsive Design): Essential for controlling layout on mobile devices. <meta name="viewport" content="width=device-width, initial-scale=1.0">

Example <head>:

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>HTML Style Guide</title>
  <link rel="stylesheet" href="styles.css">
</head>

HTML Comments

Use comments (<!-- comment -->) to explain code sections, document complex logic, or temporarily disable code. Keep comments concise and relevant.

<!-- Main navigation menu -->
<nav>
  <!-- ... -->
</nav>

<!-- TODO: Refactor this section later -->
<!-- <div class="old-component">...</div> -->

Linking CSS and JavaScript

Use the <link> tag within the <head> to link external CSS files. The type="text/css" attribute is no longer necessary.

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

Link external JavaScript files using the <script> tag. Place scripts just before the closing </body> tag generally improves perceived load time. The type="text/javascript" attribute is also unnecessary.

<script src="js/app.js"></script>
<!-- Use async or defer for optimized loading -->
<script src="js/analytics.js" async></script>

Use the async or defer attributes to control how scripts are loaded and executed without blocking page rendering.

File Naming Conventions

Use lowercase file and directory names. Separate words with hyphens (-), not underscores (_) or spaces.

• Consistency: Easier to manage files.
• Server Compatibility: Avoids issues with case-sensitive file systems (like Linux/Unix).
• URL Readability: Hyphenated names are generally preferred for URLs.

Good: about-us.html, contact-form.css, image-gallery.js

Avoid: AboutUs.html, contact_form.css, Image Gallery.js

Use standard file extensions: .html for HTML files, .css for CSS, .js for JavaScript.