跳转到内容
OpenHarmonyDocumentation Technical Writing

markdown样式检查

有序列表格式

Section titled “有序列表格式”

标准格式

Section titled “标准格式”
  1. 有序列表下的所有内容，缩进都必须是三个空格，包含代码块。
  2. 有序列表需按顺序编写。
1. xxx
   列表1中的内容
2. xxx
   列表中存在代码块

这是代码块中内容

3. xxx

报错信息

Section titled “报错信息”

序列号格式异常

问题原因

Section titled “问题原因”
  1. 无缩进、仅缩进两个空格
  2. 代码块缩进格式导致的，请看看代码块缩进规则优化文档结构

问题现象

Section titled “问题现象”
1. xxx
列表1中的内容
2. xxx
  列表中存在代码块 //标准的是缩进三个，但是这里只缩进了两个

这是代码块中美容

3. xxx

优化建议

Section titled “优化建议”

按照标准格式，缩进三个空格

代码块格式

Section titled “代码块格式”

标准格式

Section titled “标准格式”

通过三个反引号包裹代码段，并指定对应语言类型

这是标准格式


代码块中内容

报错信息

Section titled “报错信息”

代码块格式错误

问题原因

Section titled “问题原因”
  1. 使用缩进式代码块格式（段落前有4 个空格或者一个制表符（Tab 键））
  2. 缩进使用了四个空格或者制表符，被识别成代码格式

问题现象-使用四个空格

Section titled “问题现象-使用四个空格”

正常文本段落

这是缩进式代码块
每行前面有四个空格
保持代码的原始格式

继续正常文本

优化建议

Section titled “优化建议”

参考标准格式使用三个反引号表示代码块格式

问题现象-缩进使用了四个空格

Section titled “问题现象-缩进使用了四个空格”

  1. 判断当前系统是否支持向量数据库，若不支持，则表示当前系统不具备向量数据库能力。示例代码如下：

    ``` C
    int numType = 0;
    // 如果numType为2则支持向量数据库，为1则不支持向量数据库
    OH_Rdb_GetSupportedDbType(&numType);
    ```

  2. 当前系统支持向量数据库时，获取OH_Rdb_Store实例。示例代码如下：

优化建议

Section titled “优化建议”

正常格式中内容按照要求各个样式的要求添加缩进，不要使用四个空格的方式，需要进行删除。

代码块缩进格式

Section titled “代码块缩进格式”

标准格式

Section titled “标准格式”

正文下代码块无需缩进

xxx

有序列表中缩进3个空格

  1. 这是第一段内容

    第一行代码
    第二行代码
    第三行代码

  2. 第二段内容

    xxx

  3. 第三段内容。

    xxx

  • 无序列表中的缩进2个空格

    xxx

报错信息

Section titled “报错信息”

代码块缩进异常

问题原因

Section titled “问题原因”

代码块中的某一行，缩进量小于代码块第一行的缩进量

问题现象

Section titled “问题现象”

  1. 这是第一段内容

    第一行代码

第二行代码 // 这个地方只缩进了1个空格 第三行代码

2. 第二段内容


```ts
xxx
// 最后一行代码块缩进量小于第一行

  1. 第三段内容。

    xxx

  • 无序列表1

    xxx

xxx xxx

- 无序列表2


```ts
xxx

优化建议

Section titled “优化建议”

按照标准格式编写

问题原因

Section titled “问题原因”

代码块写在说明格式中

问题现象

Section titled “问题现象”

说明： 该接口在CAPI场景使用时默认关闭。可以在工程的module.json5中配置metadata字段控制是否启用预上屏，配置如下：

"metadata": [
 {
    "name": "can_preview_text",
    "value": "true",
 }
]

优化建议

Section titled “优化建议”

说明格式中不可存在代码块，需要放入正文中

代码块未指定语言提示

Section titled “代码块未指定语言提示”

标准格式

Section titled “标准格式”

代码块指定语言语言格式： ```(指定语言)代码块```

其中日志内容可设定成text语言格式。

报错信息

Section titled “报错信息”

代码块未指定语言

问题原因

Section titled “问题原因”

示例代码未添加对应语言时，可能会导致在官网时关键字未高亮等显示问题。

问题现象

Section titled “问题现象”
可查看源码
当前代码块未指定语言类型

优化建议

Section titled “优化建议”

按照标准的格式书写

表格格式

Section titled “表格格式”

标准格式

Section titled “标准格式”
  1. 表格至少需要三行（标题行、分隔符行、数据行）
  2. 分隔符使用 -，且-之间不允许存在空格
  3. 每一行需要以“|”开头结尾
  4. 标题行、分隔符行、数据行的列数一致
  5. 不出现空白的单元格，无内容单元区分“无”和“不涉及”。如果大量的“不涉及”导致表格中重要信息不突出，则采用“－”表示“不涉及”。
标题一 标题二 标题三
内容 内容 内容
内容 内容 内容
内容 内容 内容

报错信息

Section titled “报错信息”
第xxx行表格错误
  1. 存在制表符
  2. 表格至少需要三行（标题行、分隔符行和数据行）
  3. 标题行格式不正确，存在空列
  4. 标题行格式不正确
  5. 缺少标题行
  6. 缺少分隔符行、或分隔符行格式不正确
  7. 标题行和分隔符行的列数不一致
  8. 数据行格式不正确，存在空列
  9. 数据行格式不正确
  10. 数据行的列数与标题行不一致

问题原因

Section titled “问题原因”
  1. 标题行、分隔符行、数据行的列数不一致
  2. 缺少列
  3. 列表中间多了制表符

问题现象-标题行格式不正确

Section titled “问题现象-标题行格式不正确”

测试第一行少 | 名称 | 说明 | | ––––––– | ––––––––––––––––|多余列| | uint8_t | 8-bit无符号整数。 |多余列| | uint16_t | 16-bit无符号整数，采用小端字节序。 |多余列|

测试第二行少 | 名称 | 说明 |多余列| | ––––––– | ––––––––––––––––| | uint8_t | 8-bit无符号整数。 |多余列| | uint16_t | 16-bit无符号整数，采用小端字节序。 |多余列|

测试多余列

名称 说明
uint8_t 8-bit无符号整数。
uint16_t 16-bit无符号整数，采用小端字节序。
uint32_t 32-bit无符号整数，采用小端字节序。

测试某几行少一列

名称 说明 多余列
uint8_t 8-bit无符号整数。 多余列
uint16_t 16-bit无符号整数，采用小端字节序。
uint32_t 32-bit无符号整数，采用小端字节序。 多余列
sleb128 leb128编码的有符号整数。

优化建议

Section titled “优化建议”

标题行、分隔符行、数据行的列数保持一致

问题现象-分隔符错误或分隔符之间存在空格

Section titled “问题现象-分隔符错误或分隔符之间存在空格”

分隔符存在空格

| 名称 | 说明 | | ––––––– | –––– ————————| | uint8_t | 8-bit无符号整数。 | | uint16_t | 16-bit无符号整数，采用小端字节序。 |

分隔符存在其他符号 |名称 | 说明 | |–=-|—| | uint8_t | 8-bit无符号整数。 | | uint16_t | 16-bit无符号整数，采用小端字节序。 |

缺少分隔符行 | 名称 | 说明 | | uint8_t | 8-bit无符号整数。 | | uint16_t | 16-bit无符号整数，采用小端字节序。 | | uint32_t | 32-bit无符号整数，采用小端字节序。 | | uleb128 | leb128编码的无符号整数。 | | sleb128 | leb128编码的有符号整数。 |

优化建议

Section titled “优化建议”

按照标准的格式书写

问题现象-管道符未闭环

Section titled “问题现象-管道符未闭环”

标题行前/后无管道符

名称 说明
uint8_t 8-bit无符号整数。
uint16_t 16-bit无符号整数，采用小端字节序。
名称 说明
uint8_t 8-bit无符号整数。
uint16_t 16-bit无符号整数，采用小端字节序。

分隔符行前/后无管道符

名称 说明
uint8_t 8-bit无符号整数。
uint16_t 16-bit无符号整数，采用小端字节序。
名称 说明
uint8_t 8-bit无符号整数。
uint16_t 16-bit无符号整数，采用小端字节序。

数据行行前/后无管道符

名称 说明
uint8_t 8-bit无符号整数。
uint16_t 16-bit无符号整数，采用小端字节序。
名称 说明
uint8_t 8-bit无符号整数。
uint16_t 16-bit无符号整数，采用小端字节序。

优化建议

Section titled “优化建议”

按照标准的格式书写

问题现象-标题行问题

Section titled “问题现象-标题行问题”

缺少标题行，标题行存在空值

| ––––––– | ––––––––––––––––| | uint8_t | 8-bit无符号整数。 | | uint16_t | 16-bit无符号整数，采用小端字节序。 | | uint32_t | 32-bit无符号整数，采用小端字节序。 | | uleb128 | leb128编码的无符号整数。 | | sleb128 | leb128编码的有符号整数。 |

名称
uint8_t 8-bit无符号整数。
uint16_t 16-bit无符号整数，采用小端字节序。
uint32_t 32-bit无符号整数，采用小端字节序。
uleb128 leb128编码的无符号整数。
sleb128 leb128编码的有符号整数。

优化建议

Section titled “优化建议”

按照标准的格式书写

问题现象-数据行问题

Section titled “问题现象-数据行问题”

数据行存在空值

名称 说明
uint8_t
uint16_t
uint32_t 32-bit无符号整数，采用小端字节序。
uleb128 leb128编码的无符号整数。
sleb128 leb128编码的有符号整数。

优化建议

Section titled “优化建议”

问题现象-表格存在制表符

Section titled “问题现象-表格存在制表符”
场景 示例
系统库模块 加载@ohos.或@system.
应用内Native模块 加载libNativeLibrary.so

优化建议

Section titled “优化建议”

删除标题中tab键（\t 制表符）

“说明”、“注意”格式规范

Section titled ““说明”、“注意”格式规范”

标准格式

Section titled “标准格式”
  1. 文字内容正常格式：“说明(Note/note)”、“注意(Caution/caution)”、“告警(Warning/warning)“为独立的行，在不为独立行时，结尾必须有‘<br>’或‘<br/>’换行标签
  2. 表格内容正常格式：“说明(Note/note)”、“注意(Caution/caution)”、“告警(Warning/warning)”，前须要有‘<br>’或‘<br/>’换行标签

文字内容正常格式

说明：

  • 由于支持转换PyTorch模型的编译选项默认关闭，因此下载的安装包不支持转换PyTorch模型，只能通过源码编译方式获取。

说明：
本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

说明：
<USERID>代表当前的用户ID <PACKAGENAME>代表当前的应用包名

注意：

  • 从API version 9之后的应用开发新增支持Stage模型，作为目前主推并长期演进的模型。
  • NFC标签读写示例代码的提供，全部按照Stage模型来说明。

表格内容正常格式

名称 说明
text 文本信息。
说明：当文本长度大于列宽时，文本被截断。
text 文本信息。
注意：当文本长度大于列宽时，文本被截断。
text 文本信息。
说明：当文本长度大于列宽时，文本被截断。
text 文本信息。
注意：当文本长度大于列宽时，文本被截断。

报错信息

Section titled “报错信息”
  1. 表格中错误：第xxx行表格总说明或注意格式不符合写作规范
  2. 正文中：第xxx行提示语错误；错误信息：

问题原因

Section titled “问题原因”
  1. “说明”或“注意”不是独立的行，且无
    ’或‘
    ’换行标签
  2. “说明”或“注意”，前面缺少‘
    ’或‘
    ’换行标签

问题现象-正文中没有按照要求

Section titled “问题现象-正文中没有按照要求”

异常显示： 方式一：

说明： 请注意不要在生命周期函数中执行复杂耗时操作，以避免影响页面切换性能

方式二：

说明：根据测试类型的不同，在具体编写过程中可选择不同的测试类型：

方式三： 根据测试类型的不同，在具体编写过程中可选择不同的测试类型（说明：）

优化建议

Section titled “优化建议”

按照标准的格式书写

问题现象-表格中未按标准书写

Section titled “问题现象-表格中未按标准书写”

异常

名称 说明
text 文本信息。说明：
当文本长度大于列宽时，文本被截断。
text 文本信息。注意：
当文本长度大于列宽时，文本被截断。

优化建议

Section titled “优化建议”

按照标准的格式书写

HTML标签规范

Section titled “HTML标签规范”

标准格式

Section titled “标准格式”
  1. <br/>或<br>标签结尾需要闭合
  2. <sup>标签要闭合

报错信息

Section titled “报错信息”
  1. 第xxx行br错误
  2. 第xxx行sup错误

问题原因

Section titled “问题原因”
  1. <br/>或<sup>标签结尾没有闭合

问题现象

Section titled “问题现象”

<br

<sup

标签结尾没有闭合

优化建议

Section titled “优化建议”

按照标准的格式书写

“@link”异常检测

Section titled ““@link”异常检测”

标准格式

Section titled “标准格式”

链接的正确的书写格式：[xxxxx](xxxxx)

报错信息

Section titled “报错信息”

第xxx行链接错误；错误信息

问题原因

Section titled “问题原因”

开发在md里面误用了代码注释的链接写法，没有被识别为链接。

优化建议

Section titled “优化建议”

按照标准的格式书写

链接（图片链接）格式错误

Section titled “链接（图片链接）格式错误”

标准格式

Section titled “标准格式”

内容元素-链接

内容元素-图片总体要求

链接基础格式

[xxx](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/markdown-check.md#xxxx)

[xxx](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/markdown-check/xxxx.md#xxxx)

[xxx](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/xxx/xxxx.md#xxxx)

图片基础格式

![xxx](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/markdown-check.md#xxxx)

![xxx](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/markdown-check/xxxx.md#xxxx)

![xxx](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/xxx/xxxx.md#xxxx)

报错信息

Section titled “报错信息”

链接格式错误

问题原因

Section titled “问题原因”
  1. 链接格式错误，右括号未闭环
  2. 图片类型超出，当前仅支持（png、 jpg、 gif、 jpeg、 svg）
  3. 链接中存在br标签

问题现象

Section titled “问题现象”
右括号未闭环
[xxx](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/markdown-check.md#xxxx)


图片类型超出
[xxx](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/markdown-check/figures/stepc4.raw.md)


链接中存在空格
[链接中存在空格](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/health-service-kit       /cross-file.md)


链接中存在br标签
[xxx<br>](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/markdown-check/xxxxxx.md)
[xxx<br/>](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/markdown-check/xxxxxx.md)

优化建议

Section titled “优化建议”

按照链接要求处理

Readme中urlpath检查

Section titled “Readme中urlpath检查”

标准格式

Section titled “标准格式”

Readme中，节点必须有urlpath 可参考website或已有kit的Readme

  • 通过注释添加在节点后方。
  • 长度超过50个字符后，从后向前取50个字符。
  • urlpath属性不能为空，且仅支持小写字母、数字、 中划线、下划线。
  • 存在具体文档时使用文档名称

说明： 以Readme-CN.md或Readme-EN.md 结尾的默认不检测。 例如： [Data Protection Kit（数据保护服务）](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/markdown-check/DataProtectionKit/Readme-CN.md)

- 入门<!--application-getting-started-->
  - 快速入门<!--quick-start-->
    - [开发准备](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/markdown-check/quick-start/start-overview.md)
    - [构建第一个ArkTS应用（Stage模型）](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/markdown-check/quick-start/start-with-ets-stage.md)

报错信息

Section titled “报错信息”

Urlpath_Error

问题原因

Section titled “问题原因”
  1. 当前文档中存在urlpath重复
  2. urlpath不符合格式要求

优化建议

Section titled “优化建议”

按照urlpath要求填写

标题存在序号

Section titled “标题存在序号”

标题中判定为序号的规则

Section titled “标题中判定为序号的规则”
  1. 中文序号：序号和内容之间至少有一个空格
  2. 数字序号，仅检测大于两位数的场景，防止匹配成错误码
1. Name
1.1 Name
1、Name
1、 Name
1 Name
一、Name
一 Name
No.1 Name

报错信息

Section titled “报错信息”

标题中不可出现序号

问题原因

Section titled “问题原因”

标题中存在序号

优化建议

Section titled “优化建议”

按照标准的格式书写

示例代码中不可使用console.log

Section titled “示例代码中不可使用console.log”

标准格式

Section titled “标准格式”

示例代码风格-【规则】使用console.info进行正常日志打印

检测文档中是否使用console.log

报错信息

Section titled “报错信息”

日志打印方式错误；不可使用console.log进行日志打印。

优化建议

Section titled “优化建议”

根据实际业务需要，整改为console.info或console.error

代码注释符

Section titled “代码注释符”

标准格式

Section titled “标准格式”

整体要求

  1. 仅检测IDE中的格式范围，其他错误格暂时不检测
  2. 不允许有空行仅空格或者没有内容
  3. 单行和多行的注释符与注释内容之间，有且仅有一个空格
  4. 多行注释，第一行，可以没有为空，没有空格
  5. 第一行的第一个星号与最后一行的星号同位置
  6. 多行注释内容不能超过第一行内容
// 第一行
   //  第二行


   /* 单行注释 */


 /** 多行注释 */


/* x
多行注释
 */


/** x
多行注释
 */
   /* xxxxxxxxxxxx
   多行注释
   第二行
   第三行
   */
   /*xxxxxxxxxxxx
   多行注释
   第二行
   第三行
   */

报错信息

Section titled “报错信息”

代码注释格式异常

问题原因-单行注释空格数量问题

Section titled “问题原因-单行注释空格数量问题”

注释符与注释内容之间没有空格 或者存在多个空格

//   存在多个空
//没空格
/*没有空格*/
/*   存在多个空格*/

问题原因-多行注释

Section titled “问题原因-多行注释”
  1. 第一行的第一个星号与最后一行的星号未对齐
  2. 多行注释内容不能超过第一行内容
     /* xxxxxxxxxxxx
      第一行的第一个星号与最后一行的星号未对齐
  */
     /* xxxxxxxxxxxx
 多行注释内容超过第一行内容
      */

优化建议

Section titled “优化建议”

按照标准的格式书写

JSON/JSON5代码格式检查

Section titled “JSON/JSON5代码格式检查”

标准格式

Section titled “标准格式”

json标准格式

json与json5格式差异

特性 JSON JSON5
注释 不支持 支持// 和 /* */
尾随逗号 不允许 允许
对象键引号 必须使用双引号 可省略（支持单引号）
字符串 仅双引号 可用单引号
数字 十进制 支持十六进制、Infinity、NaN、-0
关键字 小写 true/false/null 大小写不敏感

说明：

当前已对代码片段进行适配，适配方式为，在代码片段外加一对大括号{}。

报错信息

Section titled “报错信息”

json代码块中格式存在异常，请将代码块放置在IDE中进行确认处理。 json5代码块中格式存在异常，请将代码块放置在IDE中进行确认处理。

问题原因

Section titled “问题原因”
  1. json中存在注释。
  2. json中存在多余/缺失符号，如逗号，大括号，引号等。
  3. 代码块中存放多个json对象

问题现象

Section titled “问题现象”
// 代码块中放入多个json对象。
{
   "name" : "xxxxx"
},
{
   "name" : "xxxxx"
}

优化建议

Section titled “优化建议”
  1. 建议在IDE中创建对应类型文档，如json、json5，然后将问题代码放入文件中，依据IDE的提示处理对应问题。
  2. json代码块中使用了json5的格式，将代码块格式由json替换为json5。

段落格式

Section titled “段落格式”

标准格式

Section titled “标准格式”
  1. 段落后面使用一个空行来表示重新开始一个段落。
  2. 可以使用br标签来换行
这是第一段


这是第二段


这是第三段




这是一句话<br>   </br>  <br/>
这是另外一句话

报错信息

Section titled “报错信息”

段落之间需要存在空行

问题原因

Section titled “问题原因”

每行后边使用两个空格换行

第一行  后边有两个空格
第二行
第三行

问题现象

Section titled “问题现象”

优化建议

Section titled “优化建议”

按照标准的格式书写