markdown-style-guide.zh-CN.md

摘自: markdown-写作规范

markdown 写作规范格指南

目的

1. 统一内部工作日志等 markdown 写作规范。
2. 为了提高内部 markdown 文本的可读性、统一性。

基本约束

• 每行字数限制在 80 个以内。
• 表示 我黑 样式时，使用星号表达式: **我黑**。
• 表示 我倒 样式，时使用下划线表达式: _我倒_。
• 表示换行时，强制使用两个或两个以内的空格。

标题

• 标题内容文本使用非闭合的 # 字符表达式。

• # 与标题内容间使用一个空格。

  # 标题一
  ## 标题二
  ### 标题三
  

• 标题内容超出 80 个字数时，需要重新设计。

• 除在文档开头外，标题内容前后都需用空行隔开。

水平分隔符

水平分隔符约定使用 - 符（而非 * 或 _），- 数量在 3 - 80 之间。

--------------------------------------------------------------------------------

列表

• 列表项 约定相对父级使用 4 个空格缩进。

• 无序列表使用 -。

  这是一段随笔，下面的无序列表需要间隔一行。
  
      - 无序列表项一
      - 无序列表项二
          - 子列表项
  

• 一级列表块前后必须空一行。

• 子列表块与父列表项无空行。

  处理列表的一些注意事项。
  
        - 列表项一
        - 列表项二
            1. 子列表项一
            2. 子列表项二
  
        - 列表项三
        - 列表项四
  
  列表后面的任何文字都需要与之间隔一行。
  

• 列表项内容超出 80 字时，相对该列表项开头垂直缩进（省略 80 个字） 对齐即可。

    - (省略 80 个字）继
      续唠嗑
  

代码

• 内联代码 使用单反引号括起来，内容与单反引号之间没有空格。

  # 扔砖
  ` 有空格-不紧凑 `
  
  # 鼓励
  `这样写-很舒服`
  

• 代码块 前后都需要空行隔开。

• 在 列表项 内，代码块 相对父级列表项缩进 4 个空格。

    - 本列表会包含代码块
    - 下面来展示如何让代码块看起来是列表项子级。
  
      ```
      .code-example {
        property: value;
      }
      ```
  
  本段落前面的空格，不仅因为在列表之后，也是因为在代码块之后。
  

字母、数字、特殊符号

中文与字母、数字及特殊符号之间用空格隔开，这样阅读体验更佳。

比如:

住在美国的英国人 “屠腾罕” 发起拒说 “awesome 运动”, 这件事本身就很 awesome。

更新日志

• 16/07/25 17:20 - 19:39

  规范确定，参与人员: 炳翰、鲁直、义飞、孙宇、锐麟、文斌、宝峰、俊杰、颜卿。