Skip to content
This repository was archived by the owner on Aug 8, 2023. It is now read-only.

Commit c87ddf3

Browse files
kpeattkpeatt
committed
Merge pull request #19 from mobify/add-HTML-style
Add Mobify (CST) HTML Styleguide
2 parents ffb4e58 + 7f21e94 commit c87ddf3

1 file changed

Lines changed: 232 additions & 0 deletions

File tree

‎html/Readme.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
This document outlines the way Customer Success team is expected to write their HTML markup. Following this document ensures that everyone is writing markup is doing so with good practices and accessibility in mind.
2+
3+
This document borrows ideas and rules from Google's HTML Style Guide and Github's Markup & Template Styleguide.
4+
5+
## HTML Formatting
6+
7+
### Doctype
8+
9+
All our HTML documents should be using the HTML5 doctype
10+
11+
```html
12+
<!DOCTYPE html>
13+
```
14+
15+
Do we have a preference for uppercase vs, e.g. `<!doctype html>`?
16+
17+
### General Formatting
18+
19+
Use a new line for every block, list or table element and indent every such child element.
20+
21+
```html
22+
<blockquote>
23+
<p><em>Space</em>, the final frontier.</p>
24+
</blockquote>
25+
26+
<ul>
27+
<li>Moe</li>
28+
<li>Larry</li>
29+
<li>Curly</li>
30+
</ul>
31+
```
32+
33+
### Indentation Spaces
34+
35+
Indent your markup with 4 spaces, not tabs.
36+
37+
```html
38+
<!-- Preferred Method is 4 spaces -->
39+
<div>
40+
<p>This is indented with four spaces</p>
41+
</div>
42+
43+
<!-- NOT Recommended -->
44+
<div>
45+
<p>This is indented with two spaces</p>
46+
</div>
47+
48+
<!-- NOT Recommended -->
49+
<div>
50+
<p>This is indented with an tab</p>
51+
</div>
52+
```
53+
54+
### Table Format
55+
56+
If the content being marked up is tabular data (key-value or multidimensional data), use a table. Make use of the caption, `<thead>`, `<tfoot>`, `<tbody>` and `<th>` tags when necessary. In general, all `<th>` elements should always have a scope attribute associating them with a row or column, for accessibility reasons.
57+
58+
```html
59+
<table>
60+
<caption>Income and Taxes for 2014</caption>
61+
<thead>
62+
<tr>
63+
<th scope="col">Income</th>
64+
<th scope="col">Taxes</th>
65+
</tr>
66+
</thead>
67+
<tbody>
68+
<tr>
69+
<td>$ 5.00</td>
70+
<td>$ 4.50</td>
71+
</tr>
72+
</tbody>
73+
<tfoot>
74+
<tr>
75+
<td>Table Data 1</td>
76+
<td>Table Data 2</td>
77+
</tr>
78+
</tfoot>
79+
</table>
80+
```
81+
82+
If data is grouped, tables may have more than one `<tbody>`. Columns may also have more than one `<th>`, representing a hierarchy of column labels, with the topmost `<th>` elements able to span several secondary headers using the `colspan` attribute. The same is true of table rows, using multiple `<th>` and the `rowspan` attribute.
83+
84+
```html
85+
<table>
86+
<caption>Results for growth variables of mountain birches subjected to fertilization-shade (FS) treatment (two year) and previous-season manual defoliation, D (50% of leaf area).</caption>
87+
88+
<thead>
89+
<tr>
90+
<th scope="col" colspan="2">Growth variables</th>
91+
<th scope="col">MS</th>
92+
<th scope="col">F</th>
93+
<th scope="col">df</th>
94+
<th scope="col">P</th>
95+
</tr>
96+
</thead>
97+
<tbody>
98+
<tr>
99+
<th scope="row" rowspan="3">Long-shoot length</th>
100+
<th scope="row">FS</th>
101+
<td>1.242</td>
102+
<td>6.45</td>
103+
<td>3,12</td>
104+
<td>0.075</td>
105+
</tr>
106+
<tr>
107+
<th scope="row">D</th>
108+
<td>1.2342</td>
109+
<td>14.8</td>
110+
<td>6, 8</td>
111+
<td>0.005</td>
112+
</tr>
113+
<tr>
114+
<th scope="row">FS × D</th>
115+
<td>1.3445</td>
116+
<td>18.6</td>
117+
<td>2, 3</td>
118+
<td>0.455</td>
119+
</tr>
120+
</tbody>
121+
<tbody>
122+
<tr>
123+
<th scope="row" rowspan="3">Leaf Area</th>
124+
<th scope="row">FS</th>
125+
<td>0.745</td>
126+
<td>5.45</td>
127+
<td>2,12</td>
128+
<td>0.435</td>
129+
</tr>
130+
<tr>
131+
<th scope="row">D</th>
132+
<td>2.76</td>
133+
<td>12.1</td>
134+
<td>7,77</td>
135+
<td>0.234</td>
136+
</tr>
137+
<tr>
138+
<th scope="row">FS × D</th>
139+
<td>23.335</td>
140+
<td>13.0</td>
141+
<td>1,10</td>
142+
<td>1.865</td>
143+
</tr>
144+
</tbody>
145+
</table>
146+
```
147+
148+
### Close All HTML Tags
149+
150+
Even though HTML5 can automatically close tags, we prefer to close them ourselves.
151+
152+
```html
153+
<!-- BAD -->
154+
<p>Lorem ipsum dolor sit amet.
155+
<ul>
156+
<li>Foo
157+
<li>Bar
158+
<li>Baz
159+
</ul>
160+
161+
<!-- Good -->
162+
<p>Lorem ipsum dolor sit amet.</p>
163+
<ul>
164+
<li>Foo</li>
165+
<li>Bar</li>
166+
<li>Baz</li>
167+
</ul>
168+
```
169+
170+
Self-contained elements (e.g. `<meta charset="utf-8">`) should not have a trailing slash at the end.
171+
172+
### Attribute Values
173+
174+
When writing attribute values, always quote their value, even when writing HTML5. Use double quotation marks `"` rather than single quotation marks `'`.
175+
176+
```html
177+
<!-- NOT Recommended -->
178+
<input type=text>
179+
<a href='/' class='button'></a>
180+
181+
<!-- Recommended -->
182+
<input type="text">
183+
<a href="/" class="button"></a>
184+
```
185+
186+
### Attribute Order
187+
188+
> _Do we want to do something like this? See https://github.com/necolas/idiomatic-html_
189+
190+
> HTML attributes should be listed in an order that puts the most commonly-used attributes first:
191+
>
192+
> 1. class
193+
> 2. id
194+
> 3. data-*
195+
> 4. Mandatory attributes (e.g. `type` on <input>)
196+
> 5. Everything else
197+
198+
### Entity Reference
199+
200+
There is no need to use entity references like `&mdash;`, `&rdquo;`, `&#x263a;`, assuming the same encoding is used for all files and editors.
201+
202+
The exception to this is for characters with special meaning in HTML (like `<` and `&`) as well as control or "invisible" characters (like no-break spaces).
203+
204+
```html
205+
<!-- NOT recommended -->
206+
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
207+
208+
<!-- Recommended -->
209+
The currency symbol for the Euro is “€”.
210+
```
211+
212+
### Omit `[type]` on `<link>` and `<script>`
213+
214+
Do not use type attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript).
215+
216+
Specifying type attributes in these contexts is not necessary as HTML5 implies text/css and text/javascript as defaults. This can be safely done even for older browsers.
217+
218+
```html
219+
<!-- NOT recommended -->
220+
<link rel="stylesheet" href="//www.google.com/css/maia.css"
221+
type="text/css">
222+
223+
<!-- Recommended -->
224+
<link rel="stylesheet" href="//www.google.com/css/maia.css">
225+
226+
<!-- NOT recommended -->
227+
<script src="//www.google.com/js/gweb/analytics/autotrack.js"
228+
type="text/javascript"></script>
229+
230+
<!-- Recommended -->
231+
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
232+
```

0 commit comments

Comments
 (0)