---
group: Coding Style
order: 1
---
# HTML Coding Specification
## Boilerplate
```html
My Site - There are a lot of fun!
```
## DOCTYPE
### Must have doctype at the beginning
Level: **Mandatory**
```html
```
### Must use HTML5 lowercase doctype
Level: **Mandatory**
```html
```
## `` element
### Must have and only have one `` element at root
Level: **Mandatory**
```html
...
...
...
...
```
### `` element must have `lang` attribute
Level: **Mandatory**
`lang` attribute is important for search engines, screen readers and translation tools. The value is usually in `language-REGION` format, e.g. `en-US`, `zh-CN`.
```html
```
If a part of the document is written in another language, add `lang` attribute to the root element.
```html
...
......
```
### `` must have and only have one `` and one `` as children
Level: **Mandatory**
```html
...
...
...
...
...
```
## `` elements
### `` element must be contained in `` element
Level: **Mandatory**
```html
...
...
```
### Must use UTF-8 charset
Level: **Mandatory**
```html
```
### Responsive web page should have viewport meta
Level: **Recommended**
The following settings match the actual device size. Users can scale the content with touch gestures.
```html
```
The following settings disable downscale, which is not useful and even troublesome.
```html
```
In case you have implemented scaleable UI in the web page, you may want to totally disable browser scale support.
```html
```
To fit iPhone's notch screen, you may need some extra configuration. [Learn more](https://webkit.org/blog/7929/designing-websites-for-iphone-x/) .
### 1.4 资源加载
- 1.4.1 `recommended` 引入 CSS 和 JavaScript 时无需指定 type。
根据 HTML5 规范，引入 CSS 和 JavaScript 时通常不需要指明 type，因为 [text/css](https://html.spec.whatwg.org/multipage/obsolete.html#attr-style-type) 和 [text/javascript](https://html.spec.whatwg.org/multipage/scripting.html#attr-script-type) 分别是他们的默认值。
```html
```
- 1.4.2 `recommended` 在 head 标签内引入 CSS，在 body 结束标签前引入 JS。
在 `` 中指定外部样式表和嵌入式样式块可能会导致页面的重排和重绘，对页面的渲染造成影响。因此，一般情况下，CSS 应在 `` 标签里引入，[了解更多](https://developer.yahoo.com/performance/rules.html#css_top)。
> 在 HTTP2（Chrome 浏览器 69 版本之后，Firefox 和 Edge）中可以在 body 中使用 link 标签引入样式文件，但不推荐在 body 中使用 `
...
```
- 1.4.3 `recommended` 外部资源的引用地址跟随页面协议，省略协议部分。
```html
```
- 1.4.4 `recommended` 使用 preload 预加载关键资源，[了解更多](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Preloading_content)。
```html
```
- 1.4.5 `recommended` 使用 dns-prefetch 和 preconnect 处理 DNS 解析延迟问题，提高网页加载性能，[了解更多](https://developer.mozilla.org/zh-CN/docs/Web/Performance/dns-prefetch)。
```html
```
### 1.5 页面标题
- 1.5.1 `mandatory` 页面需要指定 title 标签，有且仅有 1 个。
```html
淘宝网 - 淘！我喜欢
```
## 2 编码
### 2.1 缩进
- 2.1.1 `recommended` 统一使用 2 个空格缩进，不要使用 4 个空格或 tab 缩进。
```html
Page title
```
### 2.6 可访问性
- 2.6.1 `referenced` 注意 HTML 的可访问性（Accessibility）。
网页可访问性使网页内容落实“无障碍”，让不同程度或需求的用户可以顺畅的获取网站上的信息。传统上我们认为这只与残疾人士有关，但提升网站的可访问性也可以让其他用户群体受益，比如使用移动设备的人群或低速网络的人群。
例如，为 img 标签设置 alt 属性：
```html
```
了解更多 HTML 可访问性的知识，可以阅读[这篇 MDN 的文章](https://developer.mozilla.org/zh-CN/docs/learn/Accessibility)。
## Template languages
There are many template languages to generate HTML files, e.g. [Nunjucks], [EJS]. Writting template language syntax should also follow some common specification.
This part uses [Nunjucks] as an example. But it should fit other template languages, too.
### Variables, filters and keywords MUST have spaces around
Level: **Mandatory**
```jinja
{# ❌ bad, no spaces #}
{{username}} {{tags|join(',')}}
{# ✅ good #}
{{ username }} {{ tags | join(',') }}
```
### Unfiltered user input MUST be HTML escaped
Level: **Mandatory**
```jinja
{# ❌ bad #}
{{ description }}
{# ✅ good #}
{{ description | escaped }}
```
## Credits
> If you have contributed to this document but your name isn't listed, please [create an issue](https://github.com/alibaba/f2e-spec/issues/new) to let us know!
- TODO
## References
- [Code Guide by @mdo](http://codeguide.co)
- [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)
[EJS]: https://ejs.co/
[Nunjucks]: https://mozilla.github.io/nunjucks/
