Skip to content

Instantly share code, notes, and snippets.

@heiswayi

heiswayi/html-style-guide.md

Forked from ryansechrest/html-style-guide.md
Created September 23, 2015 05:39
Show Gist options
  • Save heiswayi/acb5b2922d937b6881cc to your computer and use it in GitHub Desktop.
Save heiswayi/acb5b2922d937b6881cc to your computer and use it in GitHub Desktop.
Download ZIP
HTML style guide with coding standards and best practices.
Raw
html-style-guide.md

HTML Style Guide

All rules and guidelines in this document apply to HTML files.

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Icon Legend:

· Space, ⇥ Tab, ↵ Enter/Return

Table of Contents

  1. Files
    1. File Format
    2. Filename
  2. Document
    1. Doctype
    2. Language
    3. Character Encoding
    4. Viewport
    5. Head And Body
  3. Comments
    1. Single-line Comments
    2. Multi-line Comments
    3. Closing Tag Comments
    4. Sensitive Information
  4. Formatting
    1. Line Indentation
    2. Direct Child Elements
    3. Block, List and Table Elements
    4. Trailing Whitespace
    5. Elements and Attributes
    6. Word Separator
  5. Elements and Attributes
    1. Self-closing Elements
    2. Optional Open/Close Tags
    3. Attribute Order
    4. Attribute Values
    5. Attribute Booleans
    6. Type and Language Attribute
    7. Type Attribute
    8. Protocol
  6. Best Practices
    1. Structures, Styles and Scripts
    2. Valid HTML
    3. Semantic HTML
    4. Form Fields
    5. Entity References

1. Files

This section describes the format and naming convention of HTML files.

File Format

  1. Character encoding MUST be set to UTF-8 without BOM
    • Sublime.app → File › Save with Encoding › UTF-8
  2. Line endings MUST be set to Unix (LF)
    • Sublime.app → View › Line Endings › Unix

Filename

  1. Letters MUST be all lowercase
    • e.g. sidebar.html, index.php
  2. Words MUST be separated with a hyphen
    • e.g. social-media.html, contact-widget.php

▲ Table of Contents

2. Document

This section showcases the main elements required in a full HTML file.

  1. Doctype MUST be specified and SHOULD be HTML5
    • e.g. <!DOCTYPE html>
  2. Language MUST be defined in the html element
    • e.g. <html lang="en">
  3. Character encoding MUST be defined as early as possible
    • e.g. <meta charset="utf-8">
  4. Viewport MUST be included
    • e.g. <meta name="viewport" content="width=device-width, user-scalable=no">
  5. Head and body elements MUST be included
    • e.g. <head></head><body></body>

▲ Table of Contents

Example

<!DOCTYPE html>
<html lang="en">
<head>
	<title>Welcome</title>
	<meta charset="utf-8">
</head>
<body>

<h1>Welcome</h1>

<p>This is a skeleton document.</p>

</body>
</html>

▲ Document

3. Comments

This section describes how comments should be formatted and used.

  1. Single-line comments MUST be on one line and the comment surrounded by spaces
    • e.g. <!-- This is a comment -->
  2. Multi-line comments MUST start and end on their own line
    • i.e. <!-- ↵ Line number one ↵ Line number two ↵ `-->
  3. Closing tag comments SHOULD be prefixed with a # or . followed by the name
    • e.g. </div><!-- #main-wrapper -->
  4. Sensitive information MUST NOT be placed in a comment

▲ Table of Contents

1. Single-line Comments

Single-line comments MUST be on one line and the comment surrounded by spaces.

✖ Incorrect

<!--
This is a comment
-->

↳ Incorrect because the one-line comment is not on one line.

<!--This is a comment-->

↳ Incorrect because the comment is not surrounded by spaces.

✔ Correct

<!-- This is a comment -->

▲ Comments

2. Multi-line Comments

Multi-line comments MUST start and end on their own line.

✖ Incorrect

<!-- This is a comment
that spans multiple lines
-->

↳ Incorrect because comment doesn't start and end on its own line.

✔ Correct

<!--
This is a comment
that spans multiple lines
-->

▲ Comments

3. Closing Tag Comments

Closing tag comments SHOULD be prefixed with either a # or . followed by the name.

✖ Incorrect

<div id="main-wrapper">
...
</div><!-- main-wrapper -->

↳ Incorrect because # prefix is missing.

<div id="main-wrapper">
...
</div><!-- .main-wrapper -->

↳ Incorrect because main-wrapper is prefixed with . instead of #.

✔ Correct

<div id="main-wrapper">
...
</div><!-- #main-wrapper -->

▲ Comments

4. Sensitive Information

Sensitive information MUST NOT be placed in a comment.

✖ Incorrect

<!-- Generated by some_php_function() -->

↳ Incorrect because comments reveals server-side processes.

▲ Comments

4. Formatting

This section outline various, general formatting rules related to whitespace and text.

  1. Line indentation MUST be accomplished using tabs
    • i.e. <ul> ↵ ⇥ <li>
  2. Direct child elements within html, body, script or style element MUST NOT be indented
    • i.e. <head> ↵ ⇥ ... </head>, <body><h1></h1></body>
  3. Block, list and table elements MUST start on a new line and their children MUST be indented
    • i.e. <div> ↵ ⇥ <h1>, <table> ↵ ⇥ <th>
  4. Trailing whitespace MUST NOT be present
    • i.e. no <p></p> · · ↵
  5. Elements and attributes MUST be all lowercase
    • e.g. <a href="" title="">, <link rel="stylesheet" href="">
  6. Word separator MUST be a hyphen for user-defined attributes
    • e.g. <div data-user-name="">

▲ Table of Contents

1. Line Indentation

Line indentation MUST be accomplished using tabs.

▲ Formatting

2. Direct Child Elements

Direct child elements within html, body, script or style element MUST NOT be indented.

▲ Formatting

3. Block, List and Table Elements

Block, list and table elements MUST start on a new line and their children MUST be indented.

▲ Formatting

4. Trailing Whitespace

Trailing whitespace MUST NOT be present.

▲ Formatting

5. Elements and Attributes

Elements and attributes MUST be all lowercase.

▲ Formatting

6. Word Separator

Word separator MUST be a hyphen for user-defined attributes.

▲ Formatting

5. Elements and Attributes

This section addresses how to utilize elements and attributes.

  1. Self-closing elements MUST NOT be closed
    • e.g. <br>, <link rel="stylesheet" href="">
  2. Optional open/close tags MUST be included
    • e.g. <ul><li></li></ul>
  3. Attribute order MUST be alphabetical and lead with required attributes
    • e.g. <input class="" id="" placeholder="" type="text" value="">
  4. Attribute values MUST be wrapped in double quotation marks
    • e.g. <a href="" title="">Link</a>
  5. Attribute booleans SHOULD NOT include a value
    • e.g. <input autofocus type="text">
  6. Type and language attribute MUST be omitted on script tags
    • e.g. <script src=""></script>
  7. Type attribute MUST be omitted on link and style tags
    • e.g. <style src=""></script>
  8. Protocol SHOULD be omitted
    • e.g. <link href="//style.css" rel="stylesheet">

▲ Table of Contents

1. Self-closing Elements

Self-closing elements MUST NOT be closed.

▲ Elements and Attributes

2. Optional Open/Close Tags

Optional open/close tags MUST be included.

▲ Elements and Attributes

3. Attribute Order

Attribute order MUST be alphabetical and lead with required attributes.

▲ Elements and Attributes

4. Attribute Values

Attribute values MUST be wrapped in double quotation marks .

▲ Elements and Attributes

5. Attribute Booleans

Attribute booleans SHOULD NOT include a value.

▲ Elements and Attributes

6. Type and Language Attribute

Type and language attribute MUST be omitted on script tags.

▲ Elements and Attributes

7. Type Attribute

Type attribute MUST be omitted on link and style tags.

▲ Elements and Attributes

8. Protocol

Protocol SHOULD be omitted.

▲ Elements and Attributes

6. Best Practices

  1. Structures, styles and scripts SHOULD be separated from each other
    • e.g. <a class="button" data-track="pageview">Read More</a>
  2. Valid HTML SHOULD be written
    • i.e. yes <ul><li></li></ul>, no <ul><p></p></ul>
  3. Semantic HTML SHOULD be written
    • i.e. yes <a href="">View Options</a>, no <div class="click">View Options</div>
  4. Form fields SHOULD have a corresponding label
    • e.g. <label for=""></label><input id="" type="text">
  5. Entity references SHOULD NOT be used
    • e.g. yes —, no &mdash;

▲ Table of Contents

<strong>Get out!</strong>, <b>That compromised his system.</b>

1. Structures, Styles and Scripts

Structures, styles and scripts SHOULD be separated from each other.

▲ Best Practices

2. Valid HTML

Valid HTML SHOULD be written.

▲ Best Practices

3. Semantic HTML

Semantic HTML SHOULD be written.

▲ Best Practices

4. Form Fields

Form fields SHOULD have a corresponding label.

▲ Best Practices

5. Entity References

Entity references SHOULD NOT be used.

▲ Best Practices

▲ Table of Contents

Inspired in part by style guides from: CKAN, Google, jQuery, and WordPress.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment