docs: group

alibaba · Feb 10, 2024 · e5a9301 · e5a9301
1 parent ecb8cbc
commit e5a9301
Show file tree

Hide file tree

Showing 10 changed files with 243 additions and 141 deletions.
diff --git a/docs/coding/1.html-style-guide.md b/docs/coding/1.html-style-guide.md
@@ -1,4 +1,9 @@
+---
+group: 代码规约
+---
+
 # HTML 编码规约
+
 > 注：本篇规约无配套的 Lint 工具包
 
 ## 1 文档
@@ -42,7 +47,7 @@
 - 1.3.1【推荐】使用 UTF-8 字符编码。
 
  声明一个明确的字符编码，可以让浏览器更快速高效地确定适合网页内容的渲染方式。
- 
+
  由于历史原因，不同浏览器采用了不同的字符编码。但对于新业务，如无特殊要求，统一使用 UTF-8 字符编码，以便统一。
 
  在 HTML 中使用 `<meta charset="utf-8" />` 声明文档的编码方式：
@@ -54,9 +59,9 @@
  ```
 
 - 1.3.2【推荐】页面提供给移动设备使用时，需要设置 [viewport](https://drafts.csswg.org/css-device-adapt/#viewport-meta)。
- 
+
  设置 viewport-fit 设置为“cover”来兼容 iPhone X 的刘海屏，[了解更多](https://webkit.org/blog/7929/designing-websites-for-iphone-x/) 。
- 
+
 
  ```html
  <meta name="viewport" content="width=device-width, minimum-scale=1.0, viewport-fit=cover" />
@@ -88,7 +93,7 @@
  在 `<body></body>` 中指定外部样式表和嵌入式样式块可能会导致页面的重排和重绘，对页面的渲染造成影响。因此，一般情况下，CSS 应在 `<head></head>` 标签里引入，[了解更多](https://developer.yahoo.com/performance/rules.html#css_top)。
 
  > 在 HTTP2（Chrome 浏览器 69 版本之后，Firefox 和 Edge）中可以在 body 中使用 link 标签引入样式文件，但不推荐在 body 中使用 `<style>` 标签的内联样式。**`<link rel="stylesheet">` 将会阻止后续内容的渲染，而不是整个页面**。
- 
+
  除了基础库等必须要在 DOM 加载之前运行的 JavaScript 脚本，其他都在靠近 `body` 结束标签前引入，以防止出现页面渲染的阻塞，[了解更多](https://developer.yahoo.com/performance/rules.html#js_bottom)。
 
 
@@ -162,7 +167,7 @@
 ### 2.1 缩进
 
 - 2.1.1【推荐】统一使用 2 个空格缩进，不要使用 4 个空格或 tab 缩进。
- 
+
  ```html
  <!DOCTYPE html>
  <html>
@@ -181,7 +186,7 @@
 - 2.2.1【强制】在 HTML 注释代码中，不允许出现任何敏感信息。
 
  常见的敏感信息包括：
- 
+
  - 业务相关敏感信息，例如业务规则
  - 员工个人隐私信息，例如邮箱、手机、身份证号码
  - AK（accessKey id, accesskey secret）

diff --git a/docs/coding/2.css-style-guide.md b/docs/coding/2.css-style-guide.md
@@ -1,3 +1,7 @@
+---
+group: 代码规约
+---
+
 # CSS 编码规约
 
 本规约涉及 CSS 及其预编译语言（Sass、Less）的编码风格和最佳实践，部分规则可通过 [stylelint](https://stylelint.io/) 工具落地。
@@ -11,7 +15,7 @@
 上图是一张符合规约要求编码风格的速览图，详细规则如下：
 
 - 1.1.1【强制】所有声明都应该以分号结尾，不能省略。stylelint: [declaration-block-trailing-semicolon](https://stylelint.io/user-guide/rules/declaration-block-trailing-semicolon)
- 
+
  虽然 CSS 语法中最后一条声明的分号是可选的，但是使用分号可以增加代码的一致性和易用性。
 
  ```css
@@ -42,7 +46,7 @@
  }
  ```
 
-- 1.1.3【推荐】选择器和 `{` 之间保留一个空格。stylelint: [block-opening-brace-space-before](https://stylelint.io/user-guide/rules/block-opening-brace-space-before) 
+- 1.1.3【推荐】选择器和 `{` 之间保留一个空格。stylelint: [block-opening-brace-space-before](https://stylelint.io/user-guide/rules/block-opening-brace-space-before)
 
  ```css
  /* bad */
@@ -56,7 +60,7 @@
  }
  ```
 
-- 1.1.4【推荐】属性名和 `:` 之前无空格，`:` 和属性值之间保留一个空格。stylelint: [declaration-colon-space-after](https://stylelint.io/user-guide/rules/declaration-colon-space-after) [declaration-colon-space-before](https://stylelint.io/user-guide/rules/declaration-colon-space-before) 
+- 1.1.4【推荐】属性名和 `:` 之前无空格，`:` 和属性值之间保留一个空格。stylelint: [declaration-colon-space-after](https://stylelint.io/user-guide/rules/declaration-colon-space-after) [declaration-colon-space-before](https://stylelint.io/user-guide/rules/declaration-colon-space-before)
 
  ```css
  /* bad */
@@ -180,7 +184,7 @@
  ```
 
 - 1.1.11【参考】使用多个选择器时，每个选择器应该单独成行。stylelint: [selector-list-comma-newline-after](https://stylelint.io/user-guide/rules/selector-list-comma-newline-after)
- 
+
  ```css
  /* bad */
  .selector, .selector-secondary, .selector-third {
@@ -234,7 +238,7 @@
 ### 1.2 选择器
 
 - 1.2.1【参考】不要使用 id 选择器。stylelint: [selector-max-id](https://stylelint.io/user-guide/rules/selector-max-id)
- 
+
  id 会带来过高的[选择器优先级](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity)，使得后续很难进行样式覆盖（继而引发使用 `!important` 覆盖样式的恶性循环）。
 
  ```css
@@ -290,7 +294,7 @@
  > - 伪类（伪元素）选择器，比如 `a:hover`、`a::before`
 
 ### 1.3 属性和属性值
- 
+
 - 1.3.1【推荐】使用尽可能短的十六进制值。stylelint: [color-hex-length](https://stylelint.io/user-guide/rules/color-hex-length)
 
  ```css
@@ -412,7 +416,7 @@
  ```
 
  更多 CSS 属性顺序参考如下列表：
- 
+
  |第一组|第二组|第三组|第四组|第五组|第六组|第七组|
  |----|----|----|----|----|----|----|
  |content |box-sizing|background* |font*|opacity |unicode-bidi|transition*|
@@ -449,7 +453,7 @@
  - `border-radius`
 
  使用简写属性时，需要显式地设置所有值。我们应该在真正需要设置所有值或大多数值时才使用简写属性。
- 
+
  如果只是想设置某一个属性，则不应该使用简写属性：
 
  ```css
@@ -483,7 +487,7 @@
 ## 2 Sass 和 Less
 
 > 对于 CSS 而言，可以在新项目中尝试放弃使用 Sass、Less 这样的处理器语言，因为：
-> 
+>
 >* 这些处理器语言是在一定历史条件下的产物，虽然这些产物在一定程度上提高开发者的开发效率，但不同的处理器语言也同时增加了项目的维护成本（特别是多人协作，多团队协作的时候）。
 >* 更建议使用 PostCSS 处理器，它类似于 CSS 中的 Babel，不但具备 Sass 和 Less 的功能，而且社区繁荣，同时还可以根据自己的需求扩展相关的插件。
 >* 随着 CSS 的一些新特性出现，Sass 和 Less 以往的优势也会慢慢消失。

diff --git a/docs/coding/3.javascript-style-guide.md b/docs/coding/3.javascript-style-guide.md
@@ -1,3 +1,6 @@
+---
+group: 代码规约
+---
 
 # JavaScript 编码规约
 
@@ -6,7 +9,7 @@
 JavaScript 编码规约主要包含编码风格、语言特性、注释、命名、配套工具等几个部分。本规约面向的 ECMAScript 语言版本是 ES6+，并提供了「关于 ES5」章节供仍在使用 ES5 的开发者查阅。
 
 ## 1 编码风格
- 
+
 ![示例代码标注图](https://img.alicdn.com/tfs/TB1IaB4hIVl614jSZKPXXaGjpXa-772-484.svg)
 
 上图是一张符合规约要求编码风格的速览图，详细规则如下：
@@ -2397,7 +2400,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名
  - **Null** 被计算为 **false**
  - **布尔值** 被计算为 **布尔的值**
  - **数字** 如果是 **+0、-0 或 NaN** 被计算为 **false**，否则为 **true**
- - **字符串** 如果是空字符串 `''` 被计算为 **false**，否则为 **true** 
+ - **字符串** 如果是空字符串 `''` 被计算为 **false**，否则为 **true**
 
  ```javascript
  if ({}) { // => true
@@ -2492,7 +2495,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名
 
 ## 3 注释
 
-> 注释的目的：提高代码的可读性，从而提高代码的可维护性 
+> 注释的目的：提高代码的可读性，从而提高代码的可维护性
 > 注释的原则：如无必要，勿增注释；如有必要，尽量详尽
 
 - 3.1【推荐】单行注释使用 //。

diff --git a/docs/coding/4.react-style-guide.md b/docs/coding/4.react-style-guide.md
@@ -1,3 +1,7 @@
+---
+group: 代码规约
+---
+
 # React 编码规约
 
 ## 1 编码风格

diff --git a/docs/coding/5.node-style-guide.md b/docs/coding/5.node-style-guide.md
@@ -1,3 +1,7 @@
+---
+group: 代码规约
+---
+
 # Node.js 编码规约
 
 ## 前言