编写规范

标题

• 标题层层递进，不要跨层级。例如：一级标题下只能使用二级标题，不要直接出现三级或者四级标题。
• 下级标题内容尽量不要与上级标题内容相同。
• 标题尽量不要超过四级。
• 尽量不要出现某一级标题只出现一次的情况。
• 标题不要加拖尾的标点符号。
• 标题要被空行包围，即标题前后都是空行。

文本

• 中文字符和英文字符之间保持一个空格，标点符号与英文字符之间不用空格。

示例：

这是一篇介绍 JavaScript 的文章，是的这真的是介绍 JavaScript。

• 尽量避免句子过长，不含标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在20个字以内。如果超出，不得超过40个字。

示例：

本教程适用于初学者。无论是初学者，还是资深前端工程师，均能在本教程中有所收获。

• 语句中的关键词要使用``标注。

• 中英文标点符号应避免混用。

• 如果整句为英文，该句应使用英文标点。

• 中文句子，并列词使用、分隔。英文句子，并列词使用,分隔。

示例：

我最喜欢的公司有华为、小米、地平线、 Supercell 和阿里等。

Office includes Word, Excel, PowerPoint, Outlook and other components.

• 省略号的使用，中文后面跟中文省略号，英文后面跟英文省略号。

示例：

5 分钟过去了......

5 minutes later...

• 专有名词或专业术语格式一定要写对。

示例：

JavaScript √ javaScript ×

• 数字一律使用半角形式。
• 数值超过1,000，尽量添加英文逗号。

段落

• 一个段落只能有一个主题。
• 一个段落长度不要超过7行，最佳不超过4行。
• 段落之间用空行隔开。
• 段落开头不要留有空白字符。

引用

• 引用第三方内容时，应注明出处。
• 使用外部图片，尽量注明来源。

代码块

• 代码块上下空行，用空行包围。

• Shell 命令注意添加$符号。

示例：

$ docker ps

• 代码要指明对应的语言。

示例：

const genSidebarConfig = (dir, { hasSub, exclude }) => {
  const p = path.join(__dirname, '../', dir)
  const files = fs.readdirSync(p)
  const subDir = hasSub ? dir.split('/')[1] : ''
  const arr = []
  files.forEach(item => {
    if (exclude.indexOf(item) !== -1) return
    item = subDir ? subDir + '/' + path.basename(item, '.md') : path.basename(item, '.md')
    arr.push(item)
  })
  // console.log('🚀 ~ file: config.js ~ line 26 ~ genSidebarConfig ~ subDir', subDir)
  arr.unshift(subDir + '/')
  return arr
}

• 代码书写注意代码格式，缩进大小保持一致。

链接

• 不适用裸露的链接，请使用一般格式[百度官网](https:www.baidu.com/)。
• 链接文本尽量不要带有空格。

图片

• 图片一定要清晰。
• 图片大小尽量不要超过 300K。
• 图片的尺寸宽度尽量不要超过 700。

示例：