Markdown 编写规范

Markdown 编写规范

此为前端开发团队遵循和约定的 Markdown 编写规范,意在提高文档的可读性。

说明

文档中使用的关键字「MUST」,「MUST NOT」,「REQUIRED」,「SHALL」,「SHALL
NOT」,「SHOULD」,「SHOULD NOT」,「RECOMMENDED」,「MAY」和「OPTIONAL」在 RFC2119 中有说明。

还未定稿,对规范中提及的点有不赞同的欢迎提出 issues(请添加 markdown 标签)讨论。

规则

  • 后缀必须「MUST」使用 .md

  • 文件名必须「MUST」使用小写,多个单词之间使用-分隔。

  • 文件编码必须「MUST」用 UTF-8。

  • 文档标题应该「SHOULD」这样写。

    Markdown 编写规范
    ==========================
    
  • 章节标题必须「MUST」以 ## 开始,而不是 #

  • 章节标题必须「MUST」在 # 后加一个空格,且后面没有 #

    // bad
    ##章节1
    
    // bad
    ## 章节1 ##
    
    // good
    ## 章节1
    
  • 章节标题和内容间必须「MUST」有一个空行。

    // bad
    ## 章节1
    内容
    ## 章节2
    
    // good
    ## 章节1
    
    内容
    
    ## 章节2
    
  • 代码段的必须「MUST」使用 Fenced code blocks 风格,如下所示:

      ```
      console.log("");
      ```
    
  • 表格的写法应该「SHOULD」参考 GFM,如下所示:

    First Header  | Second Header
    ------------- | -------------
    Content Cell  | Content Cell
    Content Cell  | Content Cell
    
    | Left-Aligned  | Center Aligned  | Right Aligned |
    | :------------ |:---------------:| -----:|
    | col 3 is      | some wordy text | $1600 |
    | col 2 is      | centered        |   $12 |
    | zebra stripes | are neat        |    $1 |
    
  • 中英文混排应该「SHOULD」采用如下规则:

    • 英文和数字使用半角字符
    • 中文文字之间不加空格
    • 中文文字与英文、阿拉伯数字及 @ # $ % ^ & * . ( ) 等符号之间加空格
    • 中文标点之间不加空格
    • 中文标点与前后字符(无论全角或半角)之间不加空格
    • 如果括号内有中文,则使用中文括号
    • 如果括号中的内容全部都是英文,则使用半角英文括号
    • 当半角符号 / 表示「或者」之意时,与前后的字符之间均不加空格
    • 其它具体例子推荐阅读这里
  • 中文符号应该「SHOULD」使用如下写法:

    • 用直角引号(「」)代替双引号(“”),不同输入法的具体设置方法请参考这里
    • 省略号使用「……」,而「。。。」仅用于表示停顿
    • 其它可以参考知乎规范
  • 表达方式,应当「SHOULD」遵循《The Element of Style》:

    • 使段落成为文章的单元:一个段落只表达一个主题
    • 通常在每一段落开始要点题,在段落结尾要扣题
    • 使用主动语态
    • 陈述句中使用肯定说法
    • 删除不必要的词
    • 避免连续使用松散的句子
    • 使用相同的结构表达并列的意思
    • 将相关的词放在一起
    • 在总结中,要用同一种时态(这里指英文中的时态,中文不适用,所以可以不理会)
    • 将强调的词放在句末

扩展阅读

  • Google 后来也出了 Markdown 规范,很多和这里是一样的,但也增加了一些约定,可以参考

推荐阅读更多精彩内容

  • 我们首先要确认一点,那就是阅读媒介的根本目的,是以最有效的方式将内容传递给用户。所有的排版布局的目的,就是为了有效...
    LostAbaddon阅读 1,319评论 1 7
  • 原文地址:码字必备:18 款优秀的 Markdown 写作工具 | 2015 年度盘点 现在是 2015 年底,自...
    袁俊亮技术博客阅读 15,810评论 6 66
  • 01 今天我要说下昨天中午看见的一条新闻,“紧急!今早杭州火车东站,发现一个婴儿!急寻父母!” 其实我一直害怕、抵...
    何小然的视界阅读 580评论 0 0
  • 《耿耿于怀》填词 唱不顺 待修。 你还在依赖它 放纵快活才依赖它 动作机械不听话有快活样子吗 它又咬噬你或者你在结...
    脱壳蜗牛阅读 124评论 0 0
  • 此刻我还在这只摇摇晃晃的大瓢虫里,却是不慌不忙地,观察车里的人,想自己的生活,结婚了,抛下曾经父母不同意的那些恐慌...
    红豆小妮阅读 1,470评论 2 1
  • 新顺拿着大学录取通知书离开了大山,蜷缩在破旧的拖拉机上,望着眼前渐行渐远的故土,不禁感慨万分。 车在盘旋的山头打滑...
    素一航阅读 197评论 2 2
  • 1.Swift是强类型的语言 (oc 是弱类型)2.Swift 中任何一个标识符都有明确的类型注意:(1)如果定义...
    天蓝色的海岸阅读 231评论 0 2