From a68632fbaf118ebbd5b4e8b7a51f8a1205336df3 Mon Sep 17 00:00:00 2001 From: chopupu <1123478123@qq.com> Date: Wed, 21 May 2025 15:04:49 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=E6=9B=B4=E6=96=B0markdownlint=E8=A7=84?= =?UTF-8?q?=E5=88=99=E4=B8=8E=E6=B5=81=E6=B0=B4=E7=BA=BF=E9=97=A8=E7=A6=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/zh/contribute/_toc.yaml | 2 +- docs/zh/contribute/markdownlint_rules.md | 116 +++++++++++++++++------ docs/zh/contribute/markdownlint_tools.md | 38 +++++++- 3 files changed, 123 insertions(+), 33 deletions(-) diff --git a/docs/zh/contribute/_toc.yaml b/docs/zh/contribute/_toc.yaml index 9fef2ce26..4a6a8fdaa 100644 --- a/docs/zh/contribute/_toc.yaml +++ b/docs/zh/contribute/_toc.yaml @@ -5,7 +5,7 @@ sections: href: ./directory_structure_introductory.md - label: 快速入门 href: ./contribution_process.md - - label: 教程 + - label: 规范与门禁 sections: - label: 文档写作规范 href: ./documentation_writing_specifications.md diff --git a/docs/zh/contribute/markdownlint_rules.md b/docs/zh/contribute/markdownlint_rules.md index 2dc12ff94..6b572e771 100644 --- a/docs/zh/contribute/markdownlint_rules.md +++ b/docs/zh/contribute/markdownlint_rules.md @@ -6,6 +6,47 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置的规则对 Markdown 文件进行全面的检查。文档写作时可以借助 VSCode 等工具的 markdownlint 插件修复格式问题。 +## openEuler docs 仓规则设置 + +- openEuler 规则采用如下方案： + + - MD003 (标题样式) 规则将参数 `style`设置为`atx`。 + - MD029（有序列表的前缀序号）规则将参数`style`设置为`ordered`。 + - 屏蔽 MD004（无序列表）这条规则。 + - 屏蔽 MD007（无序列表缩进）这条规则。 + - 屏蔽 MD009（行尾空格）这条规则。 + - 屏蔽 MD013（行的长度）这条规则。 + - 屏蔽 MD014（命令前使用\$而不显示输出）这条规则。 + - 屏蔽 MD020（closed atx样式的标题内没有空格）这条规则。 + - 屏蔽 MD021（closed atx样式的标题内有多个空格）这条规则。 + - 屏蔽 MD024（不能有重复内容的标题）这条规则。 + - 屏蔽 MD025 （文档中有多个顶级标题）这条规则。 + - 屏蔽 MD027（块引用符号后的多个空格）这条规则。 + - 屏蔽 MD033（内联HTML）这条规则。 + - 屏蔽 MD036（使用强调标记代替标题）这条规则。 + - 屏蔽 MD046（代码块样式）这条规则。 + +- ruby 文件的书写方式如下： + + ```bash + all + rule 'MD003', :style => :atx + rule 'MD029', :style => :ordered + exclude_rule 'MD004' + exclude_rule 'MD007' + exclude_rule 'MD009' + exclude_rule 'MD013' + exclude_rule 'MD014' + exclude_rule 'MD020' + exclude_rule 'MD021' + exclude_rule 'MD024' + exclude_rule 'MD025' + exclude_rule 'MD027' + exclude_rule 'MD033' + exclude_rule 'MD036' + exclude_rule 'MD046' + ``` + ## 规则介绍 ### MD001 - 标题级别一次只能增加一个级别 @@ -55,7 +96,8 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 - **参数** - - `style`：指定文档标题的样式，有 `consistent`、`atx`、`atx_closed`、`setext`、`setext_with_atx`五种。本仓已设置为 `atx`。 + - `style`：指定文档标题的样式，有 `consistent`、`atx`、`atx_closed`、`setext`、`setext_with_atx`五种。**本仓已设置为 `atx`**。 + - **错误示例** ```text @@ -77,6 +119,8 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD004 - 无序列表样式 +**本仓已屏蔽这条规则。** + - **参数** - `style`：指定无序列表的样式，有 `consistent(定义时符号前后保持一致)`、`astrisk(用星号定义)`、`plus(用加号定义)`、`dash(用减号定义)`、`sublist(定义多重列表的时候用不同的符号定义)`五种，默认为 `consistent`。 @@ -136,9 +180,11 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD007 - 无序列表缩进 +**本仓已屏蔽这条规则。** + - **参数** - - `ident`：指定无序列表嵌套时缩进的空格数，默认值是2。本仓将其设置为4，即需要缩进4个空格。 + - `ident`：指定无序列表嵌套时缩进的空格数，默认值是2。 - **错误示例** ```text @@ -155,7 +201,7 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD009 - 行尾空格 -本仓已忽略这条规则。 +**本仓已屏蔽这条规则。** - **参数** - `br_spaces`：指定在行尾可以添加的空格的数目，默认值为0，空格数目建议大于等于2，如果小于2，会默认为0。 @@ -217,11 +263,12 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 Some more text here ``` -> 注意：如果代码块内有多个连续的空行，将不会触发此规则。 +> [!NOTE]说明 +> 如果代码块内有多个连续的空行，将不会触发此规则。 ### MD013 - 行的长度 -本仓已忽略这条规则。 +**本仓已屏蔽这条规则。** - **参数** @@ -233,7 +280,7 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD014 - 命令前使用$而不显示输出 -本仓已忽略这条规则。 +**本仓已屏蔽这条规则。** - **错误示例** @@ -300,7 +347,7 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD020 - closed atx样式的标题内没有空格 -本仓已忽略这条规则。 +**本仓已屏蔽这条规则。** - **错误示例** @@ -320,7 +367,7 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD021 - closed atx样式的标题内有多个空格 -本仓已忽略这条规则。 +**本仓已屏蔽这条规则。** - **错误示例** @@ -385,7 +432,7 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD024 - 不能有重复内容的标题 -本仓已忽略这条规则。 +**本仓已屏蔽这条规则。** - **错误示例** @@ -405,7 +452,7 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD025 - 文档中有多个顶级标题 -本仓已忽略这条规则。 +**本仓已屏蔽这条规则。** - **参数** @@ -447,6 +494,8 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD027 - 块引用符号后的多个空格 +**本仓已屏蔽这条规则。** + - **错误示例** ```text @@ -485,7 +534,7 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 - **参数** - - `style`：指定前缀序号的格式，有 `one`(只用1做前缀)，`ordered`(从1开始的加1递增数字做前缀)两种，默认值是 `one`。本仓设置为`ordered`。 + - `style`：指定前缀序号的格式，有 `one`(只用1做前缀)，`ordered`(从1开始的加1递增数字做前缀)两种，默认值是 `one`。**本仓设置为`ordered`**。 - **错误示例** ```text @@ -596,7 +645,7 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD033 - 内联HTML -本仓已忽略这条规则。 +**本仓已屏蔽这条规则。** - **错误示例** @@ -632,7 +681,7 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD036 - 使用强调标记代替标题 -本仓已忽略这条规则。 +**本仓已屏蔽这条规则。** - **参数** @@ -776,6 +825,8 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 ### MD046 - 代码块样式 +**本仓已屏蔽这条规则。** + - **参数** - `style`：指定代码块定义格式，有 `fenced（使用三个反引号）`，`indented（使用缩进）`，`consistent（上下文一致）`三种，默认值是 `fenced`。 @@ -825,25 +876,29 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 - openEuler 规则采用如下方案： - MD003 (标题样式) 规则将参数 `style`设置为`atx`。 - - MD007（无序列表缩进）规则将参数 `indent`设置为4。 - MD029（有序列表的前缀序号）规则将参数`style`设置为`ordered`。 - - 忽略 MD009（行尾空格）这条规则。 - - 忽略 MD013（行的长度）这条规则。 - - 忽略 MD014（命令前使用\$而不显示输出）这条规则。 - - 忽略 MD020（closed atx样式的标题内没有空格）这条规则。 - - 忽略 MD021（closed atx样式的标题内有多个空格）这条规则。 - - 忽略 MD024（不能有重复内容的标题）这条规则。 - - 忽略 MD025 （文档中有多个顶级标题）这条规则。 - - 忽略 MD033（内联HTML）这条规则。 - - 忽略 MD036（使用强调标记代替标题）这条规则。 + - 屏蔽 MD004（无序列表）这条规则。 + - 屏蔽 MD007（无序列表缩进）这条规则。 + - 屏蔽 MD009（行尾空格）这条规则。 + - 屏蔽 MD013（行的长度）这条规则。 + - 屏蔽 MD014（命令前使用\$而不显示输出）这条规则。 + - 屏蔽 MD020（closed atx样式的标题内没有空格）这条规则。 + - 屏蔽 MD021（closed atx样式的标题内有多个空格）这条规则。 + - 屏蔽 MD024（不能有重复内容的标题）这条规则。 + - 屏蔽 MD025 （文档中有多个顶级标题）这条规则。 + - 屏蔽 MD027（块引用符号后的多个空格）这条规则。 + - 屏蔽 MD033（内联HTML）这条规则。 + - 屏蔽 MD036（使用强调标记代替标题）这条规则。 + - 屏蔽 MD046（代码块样式）这条规则。 - ruby 文件的书写方式如下： ```bash all rule 'MD003', :style => :atx - rule 'MD007', :indent => 4 rule 'MD029', :style => :ordered + exclude_rule 'MD004' + exclude_rule 'MD007' exclude_rule 'MD009' exclude_rule 'MD013' exclude_rule 'MD014' @@ -851,8 +906,10 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 exclude_rule 'MD021' exclude_rule 'MD024' exclude_rule 'MD025' + exclude_rule 'MD027' exclude_rule 'MD033' exclude_rule 'MD036' + exclude_rule 'MD046' ``` ## VSCode 中 Markdown 插件 @@ -869,7 +926,7 @@ markdownlint 扩展库包含 markdown 文件规则库，以保证 Markdown 文 #### 配置 -注意：VSCode 中 markdownlint 参照的版本是 David Anson 拟定的，与 openEuler 仓使用的 markdownlint 官方 v0.12.0 版本有差异。为了与 openEuler 仓配置的规则保持一致，请参考下方配置项。 +注意：VSCode 中 markdownlint 参照的版本是 David Anson 拟定的，与 openEuler 仓使用的 markdownlint 官方 v0.12.0 版本有差异。为了与 openEuler 仓配置的规则保持一致，可参考下方配置项。 - 在命令面板（`Ctrl+Shift+P`）中输入`Open Settings (JSON)`命令。 - 在 Json 对象中添加如下配置： @@ -878,8 +935,9 @@ markdownlint 扩展库包含 markdown 文件规则库，以保证 Markdown 文 "markdownlint.config":{ "default":true, "MD003":{"style":"atx"}, - "MD007":{"indent":4}, "MD029":{"style":"ordered"}, + "MD004":false, + "MD007":false, "MD009":false, "MD013":false, "MD014":false, @@ -893,11 +951,15 @@ markdownlint 扩展库包含 markdown 文件规则库，以保证 Markdown 文 "MD043":false, "MD044":false, "MD045":false, + "MD046":false, "MD048":false, "MD049":false, "MD050":false, "MD051":false, "MD052":false, - "MD053":false + "MD053":false, + "MD055":false, + "MD056":false, + "MD057":false } ``` diff --git a/docs/zh/contribute/markdownlint_tools.md b/docs/zh/contribute/markdownlint_tools.md index 73ab1dd39..7759dddea 100644 --- a/docs/zh/contribute/markdownlint_tools.md +++ b/docs/zh/contribute/markdownlint_tools.md @@ -2,7 +2,9 @@ markdownlint-cli2 适用于批量修改 markdownlint 低错问题，如空行、缩进等，大大提高文档开发效率，但是复杂问题仍需要手动修复。 -## 安装 Node.js + npm +## 安装与配置 + +### 安装 Node.js + npm 进入 [Node.js](https://nodejs.org/zh-cn)官网下载 Node.js，并按照提示完成安装。 @@ -13,7 +15,7 @@ node -v npm -v ``` -## 安装 markdownlint-cli2 +### 安装 markdownlint-cli2 执行如下命令，安装 markdownlint-cli2。 @@ -32,7 +34,7 @@ npm error errno -13 以管理员身份解决该问题：如果是 Mac 或 Linux 系统，可以在命令前加 `sudo`；如果是 `Windows` 系统，在命令提示符或者Powershell中以管理员身份运行命令。 -## 配置 markdownlint-cli2 +### 配置 markdownlint-cli2 markdownlint-cli2支持指定检查项，配置文件默认名为.markdownlint.json。将配置文件与待检查的 markdown 文件放在同一文件夹（如果要检查多个文件，则放在其共同的最上级文件夹），markdownlint-cli2就会自动读取并执行。 @@ -41,8 +43,9 @@ markdownlint-cli2支持指定检查项，配置文件默认名为.markdownlint.j ```bash { "MD003":{"style":"atx"}, - "MD007":{"indent":4}, "MD029":{"style":"ordered"}, + "MD004":false, + "MD007":false, "MD009":false, "MD013":false, "MD014":false, @@ -50,17 +53,42 @@ markdownlint-cli2支持指定检查项，配置文件默认名为.markdownlint.j "MD021":false, "MD024":false, "MD025":false, + "MD027":false, "MD033":false, "MD036":false, "MD042":false, "MD043":false, "MD044":false, "MD045":false, + "MD046":false, "MD048":false, "MD049":false, "MD050":false, "MD051":false, "MD052":false, - "MD053":false + "MD053":false, + "MD055":false, + "MD056":false, + "MD057":false } ``` + +## 检查与修复 + +### 检查 + +执行如下命令，检查指定的 markdown 文件或文件夹。 + +```bash +markdownlint-cli2 "**/*.md" +``` + +其中，文件路径可以是一个或多个文件名，也可以是通配符，或是文件夹。注意当被检测的文件夹中包含非.md格式的文件时，可能出现错误，导致检测失败。 + +### 修正 + +修正markdownlint的错误，可以使用`--fix`参数。将在源文件上直接修正错误语法，不创建备份。执行如下命令： + +```bash +markdownlint-cli2 --fix "**/*.md" +``` -- Gitee From aaf8b4247ca6308c4b7b6dd2830bfb7c80b392fa Mon Sep 17 00:00:00 2001 From: chopupu <1123478123@qq.com> Date: Wed, 21 May 2025 15:08:11 +0800 Subject: [PATCH 2/2] update --- docs/zh/contribute/markdownlint_rules.md | 49 ++---------------------- 1 file changed, 3 insertions(+), 46 deletions(-) diff --git a/docs/zh/contribute/markdownlint_rules.md b/docs/zh/contribute/markdownlint_rules.md index 6b572e771..df88ad980 100644 --- a/docs/zh/contribute/markdownlint_rules.md +++ b/docs/zh/contribute/markdownlint_rules.md @@ -871,60 +871,17 @@ markdownlint 是一款检查 Markdown 文件格式的工具，可以根据设置 [EOF] ```` -## openEuler 规则设置 - -- openEuler 规则采用如下方案： - - - MD003 (标题样式) 规则将参数 `style`设置为`atx`。 - - MD029（有序列表的前缀序号）规则将参数`style`设置为`ordered`。 - - 屏蔽 MD004（无序列表）这条规则。 - - 屏蔽 MD007（无序列表缩进）这条规则。 - - 屏蔽 MD009（行尾空格）这条规则。 - - 屏蔽 MD013（行的长度）这条规则。 - - 屏蔽 MD014（命令前使用\$而不显示输出）这条规则。 - - 屏蔽 MD020（closed atx样式的标题内没有空格）这条规则。 - - 屏蔽 MD021（closed atx样式的标题内有多个空格）这条规则。 - - 屏蔽 MD024（不能有重复内容的标题）这条规则。 - - 屏蔽 MD025 （文档中有多个顶级标题）这条规则。 - - 屏蔽 MD027（块引用符号后的多个空格）这条规则。 - - 屏蔽 MD033（内联HTML）这条规则。 - - 屏蔽 MD036（使用强调标记代替标题）这条规则。 - - 屏蔽 MD046（代码块样式）这条规则。 - -- ruby 文件的书写方式如下： - - ```bash - all - rule 'MD003', :style => :atx - rule 'MD029', :style => :ordered - exclude_rule 'MD004' - exclude_rule 'MD007' - exclude_rule 'MD009' - exclude_rule 'MD013' - exclude_rule 'MD014' - exclude_rule 'MD020' - exclude_rule 'MD021' - exclude_rule 'MD024' - exclude_rule 'MD025' - exclude_rule 'MD027' - exclude_rule 'MD033' - exclude_rule 'MD036' - exclude_rule 'MD046' - ``` - ## VSCode 中 Markdown 插件 -### markdownlint - -markdownlint 扩展库包含 markdown 文件规则库，以保证 Markdown 文件与其标准保持一致。添加配置后，markdownlint 可以自动检查文档错误。 +markdownlint 扩展库包含 markdown 文件规则库，以保证 markdown 文件与其标准保持一致。添加配置后，markdownlint 可以自动检查文档错误。 -#### 安装 +### 安装 - 按下 `Ctrl_Shift+X`以打开扩展选项卡。 - 输入 `markdownlint` 以找到扩展。 - 点击 `Install` 按钮，然后再点击`Enable`按钮。 -#### 配置 +### 配置 注意：VSCode 中 markdownlint 参照的版本是 David Anson 拟定的，与 openEuler 仓使用的 markdownlint 官方 v0.12.0 版本有差异。为了与 openEuler 仓配置的规则保持一致，可参考下方配置项。 -- Gitee