Skip to content

Latest commit

 

History

History
173 lines (125 loc) · 5.47 KB

HTML.md

File metadata and controls

173 lines (125 loc) · 5.47 KB

HTML style guide

Most of the rules in this style guide are based on our own experiences with writing maintainable HTML. Some of the sources that inspired us in the past years, and while writing the style guide:

Table of Contents

Syntax and whitespace

The following rules apply:

Write lowercase tags

<!-- bad -->
<P>I am a paragraph!</P>

<!-- good -->
<p>I am a paragraph!</p>

Use tabs for indentation

<!-- bad -->
<div>
∙∙<p>I am a paragraph!</p>
</div>

<!-- good -->
<div>
	<p>I am a paragraph!</p>
</div>

Use single quotes on attributes

Even though most style guides advise to use double quotes, we are stubborn and use single quotes. The reason is simple: we use single quotes in other languages (PHP, Javascript) and want to be consistent. Mixing double and single quotes becomes confusing in contexts where different languages meet eachother (for example in a Twig environment).

<!-- bad -->
<img src="path/to/file.jpg" alt="A beautiful file" />

<!-- good -->
<img src='path/to/file.jpg' alt='A beautiful file' />
<img src='path/to/file.jpg' alt="It's a beautiful file" />

Properly close void elements

Yes, even though trailing slashes optional. We just prefer closure, I guess. :)

<!-- bad -->
<img src="path/to/file.jpg" alt="A beautiful file">

<!-- good -->
<img src='path/to/file.jpg' alt='A beautiful file' />

Don't omit optional closing tags

<!-- bad -->
<ul>
	<li>Item 1
	<li>Item 2
	<li>Item 3
</ul>

<!-- good -->
<ul>
	<li>Item 1</li>
	<li>Item 2</li>
	<li>Item 3</li>
</ul>

Don't omit optional tags

<!-- bad -->
<!doctype html>
<title>Saving money, saving bytes</title>
<p>Qed.

<!-- good -->
<!doctype html>
<html>
	<head>
		<title>Spending money, spending bytes</title>
	</head>
	<body>
		<p>Sic.</p>
	</body>
</html>

Naming convention

We use a BEM-like naming convention for the value of class attributes. Read more about our naming section here.

Doctype

Always include a proper doctype to trigger standards mode. Omitting the doctype triggers quirks mode and should always be avoided. The HTML5 doctype is simple and easy to remember:

<!doctype html>

Language

Always include the lang attribute on the html tag. From the HTML5 spec:

Authors are encouraged to specify a lang attribute on the root html element, giving the document's language. This aids speech synthesis tools to determine what pronunciations to use, translation tools to determine what rules to use, and so forth.

Read more about the lang attribute in the spec.

<html lang='en-us'>
	<!-- ... -->
</html>

IE Compatibility mode

Internet Explorer supports the use of a document compatibility meta tag to specify what version of IE the page should be rendered as. Unless circumstances require otherwise, it's most useful to instruct IE to use the latest supported mode with edge mode.

For more information, read this awesome Stack Overflow article.

Keep in mind that the tag for compatibility mode needs to be included before all other tags except for the title and the other meta tags.

<meta http-equiv='X-UA-Compatible' content='IE=Edge' />

Character encoding

Quickly and easily ensure proper rendering of your content by declaring an explicit character encoding. When doing so, you may avoid using character entities in your HTML, provided their encoding matches that of the document (generally UTF-8).

Please keep in mind that the charset declaration:

<head>
	<meta charset='UTF-8' />
</head>

Validation

Valid markup is a goal but not a mandate. However, be aware validation can be an excellent starting place while debugging a Web page — especially if the problems are unusual.