HTML

HTML Style Guide

Maintaining consistent, well-structured HTML helps teams read, debug, and scale code more efficiently. This tutorial walks you through the core best practices—from document setup to file naming—using real HTML examples.

Learning Outcomes

After completing this tutorial, you will be able to:

Create a valid HTML5 skeleton. Include <!DOCTYPE html>, <html lang="…">, <head>, and <body> correctly.
Define essential metadata. Set <meta charset="UTF-8">, viewport, and a clear <title>.
Apply consistent syntax. Use lowercase tags/attributes, quote all values, and close non-void elements.
Format for readability. Follow a uniform indentation, limit line length, and insert blank lines between sections.
Enhance accessibility and linking. Provide alt, width, and height on images, and attach CSS/JS with correct tags.

The Role of an HTML Style Guide

An HTML style guide documents rules and conventions for writing markup. It ensures consistency across a project, reduces errors, and makes collaboration smoother. By agreeing on a shared style, teams spend less time fixing typos and more time building features.

Best Practices for Clean HTML Markup

Below are the foundational rules every HTML author should follow. Each section includes a brief explanation, key notes, and a live example.

Begin with the HTML5 Doctype

Declaring <!DOCTYPE html> at the top of your file enables standards mode in all modern browsers.

Notes:

Case-insensitive, but always write uppercase for readability.
Must be the very first line (no comments or spaces before).

Example:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My Page</title>
</head>
<body>
    <!-- content -->
</body>
</html>

Declare Character Encoding Early

Defining <meta charset="UTF-8"> ensures your text renders correctly and supports all Unicode characters.

Notes:

Place immediately after <head> opens.
UTF-8 covers most languages and symbols.

Example:

<head>
    <meta charset="UTF-8">
    <title>My Page</title>
</head>

Set the Page Language with `lang`

Adding lang="en" (or your locale) to <html> helps screen readers and search engines interpret content correctly.

Notes:

Use BCP 47 codes (e.g., "en-US", "fr", "es-MX").
Affects hyphenation, spell-check, and translation tools.

Example:

<html lang="en">
  <!-- … -->
</html>

Use Lowercase for Element Tags

Writing <div>, <p>, <section> uniformly in lowercase creates a clean, predictable codebase.

Notes:

Avoid <DIV> or <Div>.
Consistent casing prevents server-sensitive file mismatches.

Example:

<body>
  <h1>Welcome</h1>
  <p>Example paragraph.</p>
</body>

Always Close Your HTML Tags

Explanation: Explicit closing of elements (e.g., <p></p>) avoids unexpected nesting and rendering issues, especially in older browsers and XML tools.

Notes:

Void elements (<img>, <br>, <hr>) may self-close in XHTML (<img />).
Closing reduces DOM ambiguity.

Example (Incorrect Usage):

Here the first <p> tag isn’t closed, causing the second <p> to nest unexpectedly and leading to unpredictable rendering:

<section>
  <p>First paragraph.
  <p>Second paragraph.</p>
</section>

Example (Correct Usage):

Each paragraph tag is explicitly closed, ensuring a clear, well-formed DOM:

<section>
  <p>First paragraph.</p>
  <p>Second paragraph.</p>
</section>

Use Lowercase for Attribute Names

Keeping attributes like href, src, and alt in lowercase aligns with HTML5 specs and boosts readability.

Notes:

Avoid mixing cases (e.g., HREF, Src).
Simplifies search and replace operations.

Example:

<a href="https://example.com">Visit Site</a>

Quote All Attribute Values

Quoting values—even single words—avoids parsing errors and clearly delineates attribute boundaries.

Notes:

Always use double quotes "…".
Required around values with spaces.

Example:

<img src="logo.png" alt="Company Logo">

Provide Alt Text and Dimensions for Images

Supplying alt, width, and height attributes improves accessibility and reserves layout space before images load.

Notes:

alt describes the image for screen readers.
width/height prevent content shifts.

Example:

<img
    src="banner.jpg"
    alt="Promotional Banner"
    width="1200"
    height="400">

Include a Meaningful `<title>` Tag

The <title> appears in browser tabs, bookmarks, and search results. A clear title helps both users and SEO.

Notes:

Keep it under 60 characters.
Place inside <head> as the only <title>.

Example:

<head>
  <title>Introduction to CSS Grid | SitePoint Tutorial</title>
</head>

Avoid Spaces Around the Equals Sign

Writing attr="value" without spaces around = tightens your code visually.

Notes:

rel="stylesheet" is preferred over rel = "stylesheet".
More compact and consistent.

Example:

<link rel="stylesheet" href="styles.css">

Keep Lines Within a Reasonable Length

Limiting lines to ~80–120 characters prevents horizontal scrolling and eases code reviews.

Notes:

Wrap long attribute lists across multiple lines.
Align attributes vertically for clarity.

Example:

<input
    type="text"
    id="username"
    name="username"
    placeholder="Enter your username">

Use Consistent Indentation and Blank Lines

Indenting by 2 spaces (or your team’s standard) and adding blank lines between logical blocks highlights structure.

Notes:

Never mix spaces and tabs.
Reserve blank lines for separate sections, not every tag.

Example:

<body>

  <header>
    <h1>SitePoint</h1>
  </header>

  <main>
    <p>Welcome to our tutorial.</p>
  </main>

</body>

Define Metadata in the Head

Metadata like <meta name="description">, viewport settings, and charset belong inside <head>.

Notes:

Order: charset → viewport → SEO tags → title → CSS links → scripts.
Early metadata avoids flash-of-unstyled-content.

Example:

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="description" content="Learn HTML style conventions">
  <title>HTML Style Tutorial</title>
</head>

Configure the Viewport for Responsive Design

The viewport meta tag ensures pages scale correctly on mobile devices.

Notes:

width=device-width matches screen width.
initial-scale=1.0 prevents automatic zoom.

Example:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Write Clear HTML Comments

Comments () document non-obvious code intentions and aid future maintainers.

Notes:

Keep single-line comments brief.
Indent multi-line comments to the same level as the code they describe.

Example:

<!-- Page header starts here -->
<header>
  <!-- Logo and navigation -->
</header>

Link to CSS Stylesheets Properly

Use <link> in the <head> to attach external style sheets without unnecessary attributes.

Notes:

Omit type="text/css"; HTML5 infers it.
Use media attribute only when needed.

Example:

<link rel="stylesheet" href="styles.css">

Include External JavaScript Files

Load scripts with <script src="…"></script>—preferably at the end of <body> or with defer in <head>.

Notes:

Omit type="text/javascript" in HTML5.
Use defer to maintain execution order without blocking rendering.

Example:

<script src="app.js" defer></script>

Ensure Valid Markup for JavaScript Interactions

JavaScript methods like document.getElementById() rely on exact id values—HTML must match.

Notes:

IDs are case-sensitive in CSS, but methods often convert to lowercase.
Avoid duplicate IDs.

Example:

<button id="submitBtn">Submit</button>
<script>
  document.getElementById("submitBtn").addEventListener("click", submitForm);
</script>

Use Lowercase for File Names

Lowercase file names (index.html, main.css) prevent issues on case-sensitive servers.

Notes:

Keep extensions consistent (.html, not mixed .HTM).
Simplifies linking and deployment.

Example:

/index.html
/css/styles.css
/js/app.js

Apply Correct File Extensions

Assign .html to HTML files, .css to stylesheets, and .js to scripts for proper MIME handling.

Notes:

Some legacy servers allow .htm, but prefer .html.
Misnamed files can lead to download prompts instead of rendering.

Example:

about.html
contact.html
styles.css
script.js

Leverage Default Filenames for Directory Indexing

Servers often serve index.html when a directory is requested (/blog/ → /blog/index.html).

Notes:

Name your homepage file index.html for auto-indexing.
You can configure additional defaults (default.html, home.html) on some servers.

Example:

/blog/index.html   ←-> https://example.com/blog/
/portfolio/index.html ←-> https://example.com/portfolio/

FAQs on HTML Style

Can I omit the `<html>` and `<body>` tags?

Browsers will automatically insert missing <html> and <body> tags during parsing, so your page might still render correctly. However, omitting them can break validation tools and lead to unexpected behavior in XML-based processors. Always include both for a complete, standards-compliant document:

<!-- Good: explicit html/body -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Page Title</title>
</head>
<body>
  <h1>Hello World</h1>
</body>
</html>

Is it valid to omit the `<head>` section?

While browsers will create an implicit <head> if you place <title>, <meta>, or <link> before <body>, leaving it out makes your structure unclear and can confuse build tools or linters. Always wrap metadata in an explicit <head>:

<!-- Avoid this -->
<!DOCTYPE html>
<title>My Page</title>
<p>Content</p>

<!-- Better -->
<!DOCTYPE html>
<html>
<head>
  <title>My Page</title>
</head>
<body>
  <p>Content</p>
</body>
</html>

Should I close empty (void) HTML elements?

In HTML5, void elements (e.g., <img>, <br>, <hr>) are self-closing by definition and do not require a trailing slash. Adding /> has no effect in pure HTML5 but can help with XHTML compatibility. Choose one style and apply it consistently:

<!-- HTML5 style -->
<img src="logo.png" alt="Logo">
<br>

<!-- XHTML-compatible -->
<img src="logo.png" alt="Logo" />
<br />

What is the difference between `.htm` and `.html` extensions?

Both .htm and .html are treated identically by browsers and servers configured to serve HTML content. Historically, .htm arose from systems that limited filename extensions to three characters. Today, use .html for clarity and consistency—just be sure all your links and deployment scripts reference the chosen extension.

Why use lowercase for elements and attributes?

Consistency. Everyone on the team writes “<section>” instead of mixing <SECTION> or <Section>.
Standards compliance. HTML5 spec defines tag and attribute names in lowercase.
Server safety. Some servers (e.g., Apache on Linux) are case-sensitive; mismatched casing can lead to 404 errors when linking CSS, images, or scripts.

Do I need to close every HTML element?

Although browsers often auto-close certain tags (like <li> or <p>), explicitly closing all non-void elements prevents accidental nesting and hides no surprises from your collaborators. A clear open/close pair makes your markup easier to scan:

<!-- Avoid this ambiguity -->
<ul>
  <li>Item 1
  <li>Item 2
</ul>

<!-- Clear and explicit -->
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

Why is the `alt` attribute essential for images?

Accessibility. Screen readers announce alt text to visually impaired users.
Error handling. If an image fails to load, browsers display the alt text.
SEO benefit. Search engines use alt content to understand image context.

<img src="diagram.png" alt="Flowchart showing user login process">

Previous Next

HTML Style Guide

Learning Outcomes

The Role of an HTML Style Guide

Best Practices for Clean HTML Markup

Begin with the HTML5 Doctype

Declare Character Encoding Early

Set the Page Language with lang

Use Lowercase for Element Tags

Always Close Your HTML Tags

Use Lowercase for Attribute Names

Quote All Attribute Values

Provide Alt Text and Dimensions for Images

Include a Meaningful <title> Tag

Avoid Spaces Around the Equals Sign

Keep Lines Within a Reasonable Length

Use Consistent Indentation and Blank Lines

Define Metadata in the Head

Configure the Viewport for Responsive Design

Write Clear HTML Comments

Link to CSS Stylesheets Properly

Include External JavaScript Files

Ensure Valid Markup for JavaScript Interactions

Use Lowercase for File Names

Apply Correct File Extensions

Leverage Default Filenames for Directory Indexing

FAQs on HTML Style

Can I omit the <html> and <body> tags?

Is it valid to omit the <head> section?

Should I close empty (void) HTML elements?

What is the difference between .htm and .html extensions?

Why use lowercase for elements and attributes?

Do I need to close every HTML element?

Why is the alt attribute essential for images?

Set the Page Language with `lang`

Include a Meaningful `<title>` Tag

Can I omit the `<html>` and `<body>` tags?

Is it valid to omit the `<head>` section?

What is the difference between `.htm` and `.html` extensions?

Why is the `alt` attribute essential for images?