docs(html): html boilerplate

alibaba · Jan 4, 2025 · 9be6e8d · 9be6e8d
1 parent ec56c95
commit 9be6e8d
Show file tree

Hide file tree

Showing 2 changed files with 76 additions and 52 deletions.
diff --git a/docs/coding/html.md b/docs/coding/html.md
@@ -5,6 +5,26 @@ order: 1
 
 # HTML Coding Specification
 
+## 0. Boilerplate
+
+```html
+<!doctype html>
+<html lang="en-US">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, minimum-scale=1.0, viewport-fit=cover" />
+    <title>My Site - There are a lot of fun!</title>
+    <meta name="description" content="web front-end coding and engineering specification" />
+    <meta name="keyword" content="code,html,css,javascript,typescript,react,node" />
+    <link rel="stylesheet" href="index.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script src="./index.js"></script>
+  </body>
+</html>
+```
+
 ## 1. DOCTYPE
 
 ### 1.1. `mandatory` Must have doctype at the beginning
@@ -149,19 +169,47 @@ If a part of the document is written in another language, add `lang` attribute t
 </html>
 ```
 
-- 1.3.1 `recommended` 使用 UTF-8 字符编码。
-
-  声明一个明确的字符编码，可以让浏览器更快速高效地确定适合网页内容的渲染方式。
+## 3. `<meta>` elements
 
-  由于历史原因，不同浏览器采用了不同的字符编码。但对于新业务，如无特殊要求，统一使用 UTF-8 字符编码，以便统一。
+### 3.1. `mandatory` `<meta>` element must be contained in `<head>` element
 
-  在 HTML 中使用 `<meta charset="utf-8" />` 声明文档的编码方式：
+```html
+<!-- ❌ meta in body -->
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    ...
+  </head>
+  <body>
+    <meta charset="utf-8" />
+  </body>
+</html>
 
-  ```html
+<!-- ✅ good -->
+<!doctype html>
+<html lang="zh-CN">
   <head>
     <meta charset="utf-8" />
   </head>
-  ```
+  <body>
+    ...
+  </body>
+</html>
+```
+
+### 3.2. `mandatory` 使用 UTF-8 字符编码
+
+声明一个明确的字符编码，可以让浏览器更快速高效地确定适合网页内容的渲染方式。
+
+由于历史原因，不同浏览器采用了不同的字符编码。但对于新业务，如无特殊要求，统一使用 UTF-8 字符编码，以便统一。
+
+在 HTML 中使用 `<meta charset="utf-8" />` 声明文档的编码方式：
+
+```html
+<head>
+  <meta charset="utf-8" />
+</head>
+```
 
 - 1.3.2 `recommended` 页面提供给移动设备使用时，需要设置 [viewport](https://drafts.csswg.org/css-device-adapt/#viewport-meta)。
 
@@ -432,28 +480,6 @@ If a part of the document is written in another language, add `lang` attribute t
 
   了解更多 HTML 可访问性的知识，可以阅读[这篇 MDN 的文章](https://developer.mozilla.org/zh-CN/docs/learn/Accessibility)。
 
-## 3. 脚手架模板
-
-根据以上规约，建议的 HTML 脚手架模板如下：
-
-```html
-<!doctype html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="description" content="淘宝网 - 亚洲较大的网上交易平台" />
-    <meta name="keyword" content="淘宝,掏宝,网上购物,C2C" />
-    <meta name="viewport" content="width=device-width, minimum-scale=1.0, viewport-fit=cover" />
-    <title>淘宝网</title>
-    <link rel="stylesheet" href="example.css" />
-  </head>
-  <body>
-    <div id="container"></div>
-    <script src="example.js"></script>
-  </body>
-</html>
-```
-
 ## Credits
 
 - [Guo Yunhe](https://github.com/guoyunhe)

diff --git a/docs/coding/html.zh.md b/docs/coding/html.zh.md
@@ -5,6 +5,26 @@ order: 1
 
 # HTML 编码规约
 
+## 0. 文件样板
+
+```html
+<!doctype html>
+<html lang="en-US">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, minimum-scale=1.0, viewport-fit=cover" />
+    <title>My Site - There are a lot of fun!</title>
+    <meta name="description" content="web front-end coding and engineering specification" />
+    <meta name="keyword" content="code,html,css,javascript,typescript,react,node" />
+    <link rel="stylesheet" href="index.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script src="./index.js"></script>
+  </body>
+</html>
+```
+
 ## 1. DOCTYPE
 
 ### 1.1. `强制` 文档开头必须有 doctype
@@ -149,7 +169,7 @@ order: 1
 </html>
 ```
 
-## 3.
+## 3. `<meta>` 元素
 
 - 1.3.1 `推荐` 使用 UTF-8 字符编码。
 
@@ -434,28 +454,6 @@ order: 1
 
   了解更多 HTML 可访问性的知识，可以阅读[这篇 MDN 的文章](https://developer.mozilla.org/zh-CN/docs/learn/Accessibility)。
 
-## 3. 脚手架模板
-
-根据以上规约，建议的 HTML 脚手架模板如下：
-
-```html
-<!doctype html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="description" content="淘宝网 - 亚洲较大的网上交易平台" />
-    <meta name="keyword" content="淘宝,掏宝,网上购物,C2C" />
-    <meta name="viewport" content="width=device-width, minimum-scale=1.0, viewport-fit=cover" />
-    <title>淘宝网</title>
-    <link rel="stylesheet" href="example.css" />
-  </head>
-  <body>
-    <div id="container"></div>
-    <script src="example.js"></script>
-  </body>
-</html>
-```
-
 ## 作者署名
 
 - [郭云鹤（鹤仙）](https://github.com/guoyunhe)