Skip to content
Tutorials Center
My learning

Topics

Lesson 108 of 122 ยท Accessibility and Best Practices

HTML Style Guide

Write HTML that is easy to read and maintain, with conventions for the doctype, lowercase names, quoting, indentation, optional tags, file names and comments.

HTML is forgiving. Browsers accept uppercase tags, missing quotes, missing closing tags and odd indentation, and the page usually still works. But code is read far more often than it is written: by you next month, by teammates and by tools. A consistent style makes markup faster to read, easier to review and less likely to hide bugs.

There is no single official HTML style guide. What follows is a set of widely used conventions, with the reasons behind them. The most important rule is the last one: whatever you choose, be consistent.

Start every page the same way

Every HTML document should begin with the same short skeleton:

HTML
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Opening Hours โ€“ Riverside Library</title>
</head>
<body>
  ...
</body>
</html>
  • <!doctype html> switches the browser into standards mode. It is case-insensitive; <!DOCTYPE html> is just as valid. Pick one form for your project.
  • lang on <html> tells browsers and screen readers the page language (see Accessibility Basics).
  • <meta charset="utf-8"> should be the first thing in <head>; it must appear within the first 1024 bytes of the file. The Character Encoding lesson explains why.
  • The viewport meta tag makes the page behave on phones (see Responsive Web Design).
  • A unique <title> for every page.

Use lowercase names

Element and attribute names in HTML are case-insensitive, so <DIV CLASS="card"> works. Write them in lowercase anyway. It is the overwhelming convention, it is easier to type and read, and it matches the XML syntax of HTML, where case matters (see HTML vs XHTML).

Attribute values are different: some are case-sensitive. A class named Card does not match the CSS selector .card, and id values must match exactly. Keep values lowercase too, unless they are human-readable text.

Quote attribute values

HTML lets you leave quotes off a value that has no spaces or special characters. Do not rely on it. A missing quote around a value with a space silently creates a second attribute:

HTML
<!-- The browser sees alt="Sunset" plus two stray attributes, over and hills -->
<img src="sunset.svg" alt=Sunset over hills>

<!-- Clear and correct -->
<img src="sunset.svg" alt="Sunset over hills">

Use double quotes for consistency. Use single quotes only when the value itself contains double quotes, such as JSON in a data- attribute.

For boolean attributes, write just the name: <input required>, not required="true". Remember from the Attributes lesson that disabled="false" still disables the element.

Indentation and whitespace

Indent child elements one level deeper than their parent. Two spaces per level is the most common choice in HTML and is used throughout this course, but four spaces or tabs are fine if the whole project agrees.

  • Put block-level children on their own lines.
  • Keep short inline content on one line: <li><a href="/">Home</a></li>.
  • Use blank lines to separate large sections, not every element.
  • Avoid very long lines; break long attribute lists across lines and align them.
HTML
<ul class="tag-list">
  <li><a href="/tags/html">HTML</a></li>
  <li><a href="/tags/css">CSS</a></li>
</ul>

<img
  src="/images/harbor-at-dusk.jpg"
  alt="Fishing boats moored in a harbor at dusk"
  width="1200"
  height="800"
  loading="lazy">

Remember that HTML collapses whitespace but does not ignore it completely: a line break between two inline elements renders as a space. Occasionally that matters for things like inline buttons placed side by side.

The two versions below produce exactly the same page. Only one of them is pleasant to edit.

Same page, different style

Optional closing tags, and the self-closing trap

The HTML standard lets you omit some tags. For example, </li>, </p>, </td>, </tr> and </option> can be left out in many situations, and even <html>, <head> and <body> are optional. The browser fills them in.

That is legal, but the rules for exactly when each tag may be omitted are subtle. Most teams close every non-void element explicitly. It makes the structure obvious and prevents surprises when someone adds content later.

Void elements such as <br>, <img>, <input>, <meta> and <link> never have a closing tag. You may write them as <br> or <br />; in HTML the trailing slash has no effect at all. Choose one style. This course uses <br>.

The real danger is writing a slash on a non-void element. HTML ignores the slash, so <div /> is just an opening tag, and everything after it ends up inside the div:

The self-closing div trap

Both paragraphs land inside the dashed box. Always write <div></div>, <span></span> and <script></script> with real closing tags.

A consistent attribute order

Browsers do not care about attribute order, but readers do. A predictable order makes it quicker to find what you are looking for. One popular convention:

  1. class
  2. id, name
  3. data-*
  4. src, href, for, type, value
  5. title, alt
  6. role, aria-*
  7. boolean attributes such as required or disabled
HTML
<input class="field" id="email" name="email" type="email" autocomplete="email" required>

Other teams put id first or group aria-* attributes next to what they describe. Any order is fine as long as it is applied everywhere, ideally by a formatter.

Characters and entities

Save files as UTF-8 and type characters directly: cafรฉ, โ‚ฌ, โ€”. You only need character references for characters that have special meaning in HTML: write &lt; for a literal < and &amp; for a literal & in text. Inside attribute values, use &quot; if you must include a double quote.

File and folder names

Names become part of URLs, and URLs are often case-sensitive on servers. Follow a few simple rules:

  • Use lowercase letters, digits and hyphens: contact-us.html, team-photo-2026.jpg.
  • No spaces; they turn into %20 in URLs (see URL Encoding).
  • Avoid underscores and special characters; hyphens are the common word separator.
  • Name the default page of a folder index.html so /about/ loads /about/index.html.
  • Use the .html extension for HTML files.

Comments

Comments start with <!-- and end with -->. Use them to explain why something is unusual, or to mark the end of a long block:

HTML
<!-- The newsletter form posts to a third-party service; keep the field names. -->
<form class="newsletter" action="/subscribe" method="post">
  ...
</form>

Some guidelines:

  • Comment the intent, not the obvious. <!-- Navigation --> above a <nav> adds nothing.
  • Comments cannot be nested, and you should not put -- inside one.
  • Comments are public. Anyone can read them with View Source, so never leave passwords, internal notes or old code with secrets in them.
  • Delete commented-out code instead of keeping it "just in case"; version control remembers it.

Let tools enforce the style

Arguing about indentation in code reviews wastes time. Let tools do it:

  • An .editorconfig file sets indentation, line endings and final newlines for every editor on the team.
  • A formatter such as Prettier rewrites files into a consistent style when you save.
  • A linter points out problems the formatter cannot fix. The next lesson, on validation, covers these checks.

Consistency beats preference. When you join an existing project, follow its style even if you would choose differently. Mixed styles in one codebase are worse than any single style.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens when you write <div class="box" /> in an HTML document?

    Only void elements have no closing tag. On a normal element the slash is ignored, so the div stays open until a closing tag is found.
  2. 2. Why should you always quote attribute values?

    HTML allows some unquoted values, but a space ends the value. Quoting every value avoids that whole class of bugs.
  3. 3. Which file name follows common conventions?

    Lowercase letters and hyphens are safe in URLs, avoid case-sensitivity issues and are easy to read.
  4. 4. Which statement about HTML comments is true?

    Comments travel with the HTML and are visible to anyone, so never put secrets or sensitive notes in them.

Summary

  • Start every page with <!doctype html>, lang, <meta charset="utf-8"> first in the head, the viewport tag and a unique title.
  • Write element and attribute names in lowercase, and quote every value with double quotes.
  • Indent consistently (two spaces is common) and keep the structure visible.
  • Close every non-void element; never "self-close" a div or span.
  • Pick a consistent attribute order, use lowercase hyphenated file names and keep comments meaningful and free of secrets.
  • Let an .editorconfig, a formatter and a linter enforce the rules.

Next up: Validating Your HTML.