HTML Coding Convention

Consistent and Minimal

Most important rules:
Be consistent.
Be minimal.
Use tools.
Read these sections carefully.

Standard template

<!doctype html> <html> <head> ... </head> <body> .. </body> </html>

Indentation is 2 spaces (not 4 as in programming languages).
Column width is 79 chars, unless it breaks a single attribute value.

<li>Click the button and go to Spark's main website page link <a href=http://holaspark.com>holaspark.com</a> and click about</li> <li>Click the button and go to Spark's main website page link <a href=http://holaspark.com>holaspark.com</a> and click about</li> <li>Click the button and go to Spark's main website page link <a href=http://holaspark.com>holaspark.com</a> and click about</li> <li>Click the button and go to Spark's main website page link <a href=http://holaspark.com> holaspark.com</a> and click about</li> <li> Click the button and go to Spark's main website page link <a href=http://holaspark.com>holaspark.com</a> and click about </li> <li> Click the button and go to Spark's main website page link <a href=http://holaspark.com>holaspark.com</a> and click about </li> <li>Click the button and go to Spark's main website page link <a href=http://holaspark.com>holaspark.com</a> and click about</li> <p> Click the button and go to a website page link <a href=http://very.long/url/that/exeeds/79/charachters>Very very long page name</a> and click about </p> <p> Click the button and go to a website page link <a href=http://very.long/url/that/exeeds/79/charachters> Very very long page name</a> and click about </p> <p> Click the button and go to a website page link <a href=http://very.long/url/that/exeeds/79/charachters>Very very long page name</a> and click about </p>

Items which contain less than two rows will end on the same line, while items which have more than two rows will end in a new line.

<li>Short line</li> <li>This is a sentence that goes above 79 characters per line and therefore should be split into two rows</li> <li> This is a sentence that goes above 79 characters and also above three lines and therefore it should be split into three rows and start/end the tags in new lines </li> <li>This is a bad example of sentance that goes above 79 characters and also above three lines but ends on the same last line as it not suppose to be</li>

Don't break the line before the closing tag of an empty element. If the line is too long, break it before an attribute.

<br> are like new line in text. Break the line after it.

Time flies when you are having fun!<br>You finished your first week. Time flies when you are having fun!<br> You finished your first week. Time flies when you are having fun!<br><br><br> You finished your first week. Time flies when you are having fun!<br> <br> <br> You finished your first week.

Element names and tags always in lower case.

Hyperlinks

Always use absolute links and paths.

<a href=file>Click here</a> <a href=dir/file>Click here</a> <a href=../dir/file>Click here</a> <a href=/root/path/file>Click here</a> <a href=//site.com/path/file>Click here</a> <a href=http://site.com/path/file>Click here</a>

Using relative links and paths are allowed only if they point to the same document.

<a href=#id>Click here</a> <a href=file#id>Click here</a> <a href=./file#id>Click here</a> <a href=/path/to/file#id>Click here</a>

Special characters

Use & < > only in html, not inside tags.

<div>The answer is: a > b</div> <div title="The answer is: a > b">Answer</div> <div title="The answer is: a > b">Answer</div>

Avoid using &. Use plain & wherever possible.

Hello & Goodbye! Hello & Goodbye! <a href=/get?type=user&name=bat></a> <a href=/get?type=user&name=bat></a>

Use & only where escaping needed - when followed by a-z0-9 and ;

<div>expression: x = a&b;</div> <div>expression: x = a&b;</div>

© ' ‘ ’ — • etc.:
use plain unicode UTF8 chars for it (validate your VI is :set encoding=utf-8).

<div>This ‘download’ is the right one.</div> <div>This ‘download’ is the right one.</div>

Quote only if needed

Due to minimalism
quote attribute values only if they need quoting (contain spaces, < > " '...). No need to quote & ? = #.

<a href="http://site.com/download?option=1&set=1">Download</a> <a href=http://site.com/download?option=1&set=1>Download</a> <div id="download_btn">Download now</div> <div id=download_btn>Download now</div> <div class="download">Download now</div> <div class=download>Download now</div> <div class="download button">Download now</div>

Leave quotes on attributes that typically require quoting, such as JS fragments, and angular 'JS like' directives.

No need to quote empty attributes.

<option selected="">Customer</option> <option selected>Customer</option>

Tag's id should be the first element

<h3 text="Bring value" id=bring_value>Bring value</h3> <h3 id=bring_value text="Bring value">Bring value</h3>

Tag's class should be after id element

<h3 text="Bring value" class=bring_value>Bring value</h3> <h3 class=more_value id=bring_value text="Bring value">Bring value</h3> <h3 id=bring_value class=more_value text="Bring value">Bring value</h3> <h3 class=more_value text="Bring value">Bring value</h3>

Avoid redundant `type=text/javascript`

Due to minimalism

Don't use `<noscript>` `alt=` `title=`

We are in the age of HTML5. We don't do web pages for browsers without JavaScript, or text based browsers. Therefore we avoid obsolete features such as <noscript> and alt=

<img src=/login.png alt="Click to login"> <img src=/login.png> <script>... login form in JS...</script> <noscript>...pure html login from without JS...<noscript> <script>... login form in JS...</script>

Tooltips are great - they are the modern alternative to F1 help. But browsers tooltips (title=) don't display nice clear large fonts, cannot include HTML, just plain text.
Since tooltips are important, we avoid using the built-in browser tooltips, and we use our own jquery/angularjs tooltips, such as data-tooltip.

<div title="KB/s: kilobytes per second">4385</div> <div data-tooltip title="<b>4385 KB/s</b>: kilobytes per second">4385</div>

SVG usage

SVGs should be placed in svg files, not embedded into the html.
Loading an SVG resource should be done with <use>.

And the svg file:

Include svg4everybody (polyfill for IE) library and call it after your html will be ready.

Multiple related SVGs may be put in the same svg file and loaded separately using <symbol> tag.

Apply styles (like fill) to each fragment of svg.

.my_svg use { fill: #ccc; }

New window

Links should not open new windows/tabs - user can right-click himself to open new tab, or click BACK to return to current window

<a href=http://different.site.com target=_blank>click here</a> <a href=http://different.site.com>click here</a>

Filenames

The path is part of the name. Don't include the path name in the filename.

pkg/svc/dashboard/pub/dashboard_table.html pkg/svc/dashboard/pub/table.html

Main module page is called index.html.

pkg/svc/dashboard/pub/dashboard.html pkg/svc/dashboard/pub/index.html

External JS/CSS

External JS/CSS code used on our site as-is should be via CDN, in the following order of preference:

AngularJS

Avoid data- prefix by default.

ExpressJS

TODO (missing description of our angular tree layout)