时间戳

首页 > 技术文章 > Markdown个人使用规范

Markdown个人使用规范

9stars 2019-02-22 22:29 原文

参考文章

通用规则

文件

  • 文件扩展名使用： .md.

  • 文件名：

    • 用小写代替大写
    • 把开头 the , a , an 除去
    • 用连字符： - ， 代替标点和空格
    • 用一个连字符代替连续多个连字符，当多个连字符出现时，只使用一个
    • 不在文件名前后使用连字符

  • 建议命名格式：file-name.md

空白

  • 新行：

    • 不要 使用连续两空行，也就是说，不要连续使用两个换行符，除非是在代码块中不得已而必须出现。

    • 以回车换行结束文件。不要在文件结束时留下空行。

    • 不要在行尾留空格，除非是在行尾空出两个空格插入换行符

    • 建议使用：

        只使用了一行空行来分隔
    - list
    - list

    # Header

  • 句子结束空格：句子结束使用一个空格分隔

    • 例如:
        First sentence. Second sentence.

自动换行

  • 尝试将一行限制在 80 个字符以下，将长段落按照以下的逻辑分开，例如:

    • 句子: 一句话结束 . 之后, 问句问号 ? 或者感叹句 ! 之后
    • 子句 clauses: 在单词 and, which, if ... then, 逗号 , 之后
    • 短语 phrases

  • 设置你的文本编辑器对 Markdown 文件一行不要超过80字符，以免忘记。

代码

  • 不要 在 shell 代码前加 $ 符号，除非你想要展示命令的输出。

    • 建议使用：
        echo a
    echo a > file
    • 建议展示输出：
        $ echo a
    a
    $ echo a > file
    • 建议, 在代码前标明代码语言:
        Use the following Bash code:

    echo a
    echo a > file

  • 标记代码内容:使用代码块，或者行内代码

    • 可执行文件：
        `gcc` is the best compiler available.
    • 文件路径
    • 程序版本号
    • 大写的缩写解释
        xinetd stands for `eXtended Internet daemon`
    • 其他和电脑相关的术语，想要单独标明

  • 不要标记为代码

    • 项目名。 比如： GCC
    • 函数库名。比如： libc, glibc

拼写和语法

  • 使用正确的拼写和语法。

  • 尽量选用英语，更准确的说美式英语。

  • 类似 URL 或者代码，添加代码标记，这样拼写检查程序会自动忽略。

  • 注意大小写敏感的拼写错误，尤其是项目名，品牌名，或者缩写。

    • 建议使用: URL, LinkedIn, DoS attack
    • 不建议： url, Linkedin, dos attack

  • 避免使用非正式的缩写。

    • 建议使用: biography, repository, directory
    • 不建议： bio, repo, dir

区块

换行符

  • 避免使用换行符, 因为他们没有被广泛认可的语义。在少数确实需要使用的时候，在行尾使用两个空格。

标题

标题基本格式

  • 在 # 和标题之间加入一个空格。
    • 不建议使用，其中 . 表示空格：
        #Header

    #..Header
  • 不要 使用闭合的 # .
    • 不建议使用，其中 . 表示空格：
        # Header #
  • 不要 在 # 前加入空格.
    • 不建议使用，其中 . 表示空格：
        .# Header
  • 不要 跳跃使用标题等级.
  • 在标题上下用空行隔开，除非标题在文档开头。
  • 避免 在相同 Markdown 文件中使用相同的标题.
  • 使用范例：
    • 建议使用：
        # Header 1

    ## Header 2

    ### Header 3

顶级标题

  • 如果你想要 HTML 直接输出，这样唯一的 h1 标记就是输出的第一件事，并且会成为文档的标题。这就是HTML的顶级标题。
  • 建议不使用（不了解）

标题大小写

  • 标题开头使用大写字母，除非标题内容总是以小写出现, 例如，计算机代码。
  • 标题第一个单词后的其他单词的首字母按照句子中原始大小写。
    • 建议使用:
        # The header of the example
    • 不建议：
        # The Header of the Example

标题结尾

  • 使用 ---
# Header
---  
Content

标题的长度

  • 保证标题越短越好。
  • 避免使用长句子，总结长句子作为标题。 然后将长句子作为标题下的第一小节
建议使用
# Huge header

Huge header that talks about a complex subject.  


不建议：

# Huge header that talks about a complex subject

标题结尾标点

  • 不要使用诸如: 冒号 :, 句号 . 之类的标点符号结尾。

标题同义词

  • 标题用作用户索引的关键词，由于这个原因，你可能希望在标题中用多个关键词。

  • 创建一个同层级的同义词标题在主标题之前，并且标题下不包含内容：

    • 建议使用：
        每一个同层级的空标题都假定是同义的
    # Purchase

    # Buy

    You give money and get something in return.

  • 如果层级不一样，那就是另外的含义：

    • 例如：
        # Animals

    ## Dog

引用

  • 在符号 > 后面接一个空格。

  • 在每一行使用 > 符号，包括换行的句子。

  • 不要在单独的引用中使用空行。

    • 建议使用：
        > a
    >
    > b
    • 不建议使用：
        > a
    
    > b

列表

列表基本语法

  • 无序列表：

    • 使用连字符 - ， 尽量不要使用 * 号和 + .

  • 有序列表：

    • 尽量选用 1. 来标记有序的列表, 除非你打算通过数字在相同 Markdown 文件或者外部文件中引用他们。
    • 尽量使用无序的列表，除非有通过数字引用的需求。但是如果在原有有序列表中间加入新的列表，原有的引用会被破坏。

  • 可接受的, 使用文本引用:

    The ouput of the `ls` command is of the form:

        drwx------  2 ciro ciro        4096 Jul  5  2013 dir0
        drwx------  4 ciro ciro        4096 Apr 27 08:00 dir1
        1           2

    Where:

    1. permissions
    2. number of files directory contains
  • 可接受，通过外部 markdown 文件引用:
    Terms of use.

    1. I will not do anything illegal.  
    2. I will not do anything that can harm the website.

  • 如果新列表项被加入，引用会破坏。尽量减少这种问题：

    • 保证引用靠近列表，这样作者会更少可能的忘记去更新
    • 当从外部引用时，总是引用到一个固定版本的 markdown 文件

列表项中的空格

  • 列表项标记前总是留有一个空格。
    - a

      b

    - c
    
    或
    1. a

       b

    1. c

列表内容的缩进

  • 列表中内容的缩进层级必须和第一个列表项一致
    - item 1

      Content 1

    - item 2

      Content 2

列表中的空行

  • 如果每一个列表项只有一行, 不要在列表项之间增加空行。
    - item 1
    - item 2
    - item 3
  • 如果某一列表项不止一行，在每一个列表项之间增加空行。
    - item that
      is wrapped

    - item 2

    - item 3
  • 列表嵌套：
    - item 1

      - item 11
      - item 12
      - item 13

    - item 2

    - item 3

列表外的空行

  • 列表外建议留有一空行
    Before.

    - list
    - list

    After.

列表项首字母大小写

  • 每一个 list 使用原来在句子中的大小写
    I want to eat:

    - apples
    - bananas
    - grapes

列表项结尾标点

  • 列表项结尾标点，除非:

    • 包含多个句子或者短语
    • 以大写字母开头，添加标点
    • 否则, 如果以句号结尾的话，省略标点.
    • 建议使用：
        不含标点
    - apple
    - banana
    - orange

    包含多个句子
    - go to the market
    - then buy some fruit. Bad for wallet.
    - finally eat the fruit. Good for tummy.

    包含非句号
    - go to the marked
    - then buy fruit?
    - of course!

    大写字母开头
    - Go to the market.
    - Then buy some fruit.
    - Finally eat the fruit.

    多段落
    - go to the market

    - then buy some fruit.

      Bad for wallet.

    - finally eat the fruit.

      Good for tummy.

定义列表

  • 避免 使用定义列表扩展，因为他并没有被多数实现，也没有出现在 CommonMark

  • 若要使用，格式化列表:

    • 用加粗，链接，或者代码，格式化需要定义的内容
        加粗
    - **apple**: red fruit
    - **dog**: noisy animal

    -   **apple**: red fruit.

        Very tasty.

    -   **dog**: noisy animal.

        Not tasty.

    链接
    - [apple](http://apple.com): red fruit
    - [dot](http://dog.com): red fruit

    代码
    - `-f`: force
    - `-r`: recursive

    • 将内容和定义使用冒号和空格分割 :.

    • 不要对齐定义，这样难以维护，并且不会显示在 HTML 输出

        不建议下面这样的，冒号或者冒号后面的文字定义对齐
    - **apple**: red fruit
    - **dog**:   noisy animal

代码区域

  • code fence blocks

  • 不要 缩进 fenced code blocks.

  • 总是指定代码的语言

         ```ruby
         a = 1
         ```
  • 也可以仅仅使用缩进代码区域，代码区域缩进4个空格。（个人一般不采用）

水平横线

  • 水平横线为 3 个无空格连字符: ---。
  • 仅仅在表明End of a header时使用水平横线。（博客园中不推荐使用在标题下方）

表格

  • 用一空行包围表格。

  • 不要缩进表格。

  • 用 | 包裹表格的每一行。

  • 竖直对齐所有表格边框, 中英文混用可能出现无法对齐的情况，尽量即可。

  • 将标题和内容用连字符分割，用对齐的 |。

  • | 周围必须要有一个空格，除非是外部的 |。

  • 列的宽度通过列中最长的单元格确定。

Before.

| h    | Long header |
|------|-------------|
| abc  | def         |
| abc2 | def2        |

After.

分离相连的列表

  • 分离连续:

    • 列表
    • 缩进的代码块
    • 引用
    • 列表之后跟随额外的代码块

  • 使用一个空白的 HTML 注释 ：<!-- --> .

  • 示例:

分离列表：
- list 1
- list 1

<!-- -->

- list 2
- list 2

分离缩进的代码块：
    code 1
    code 1

<!-- -->

    code 2
    code 2

分离引用：
> blockquote 1
> blockquote 1

<!-- -->

> blockquote 2
> blockquote 2

分离列表之后跟随额外的代码块：
- list
- list

<!-- -->

    code outside list
    code outside list

Span 元素

  • 不要使用内部空格
不建议使用
** bold **
` code `
[ link ]( http://a.com )
[text] [name]

建议使用
**bold**
`code`
[link](http://a.com)
[text][name]

链接

参考样式链接

  • 必须写到文件末
  • 必须以ID字符顺序排列
  • 不要使用尖括号包裹 URL
  • align URLs and link names as in a table(各列内容像在表格中一样对齐，间隔一个空格)
  • 链接 IDs 仅仅使用小写字母. 解释: 因为 IDs 区分大小写, 只用小写容易书写，并且可读性比大小写混合单词大很多。
[id2]     http://long-url.com
[long id] http://a.com        "name 1"

单引号或双引号标题

使用双引号，不要 使用单引号。

强调

加粗

  • 使用双星号格式: **bold**.

斜体

  • 使用单星号格式: *italic*.

大写强调

  • 不要使用大写来强调: 使用强调语法例如 加粗 或者 斜体

强调与标题

  • 不要使用强调元素(加粗或者斜体) 来介绍多行区块: 使用标题代替.
不建议：
**How to make omelets:**

Break an egg.

...

**How to bake bread:**

Open the flour sack.

...

建议：
# How to make omelets

Break an egg.

...

# How to bake bread

Open the flour sack.

...

自动链接

使用尖括号自动链接

  • 使用带尖括号的自动链接
建议：
<http://a.com>

不建议：
http://a.com
  • 如果你不想文字链接自动链接，将他们以代码区块方式包裹，例如：
`http://not-a-link.com`

内容的自动链接

  • 不要在相对链接时（一般是链接到某个文件或者目录）使用自动链接。如果遇到相对链接，使用括号的方式创建链接
建议使用：
[file.html](file.html)

不建议使用：
<file.html>
  • 自动链接必须以字串 http 开始
建议：
<https://github.com>

不建议：
<github.com>

电子邮件自动链接

  • 不要 使用电子邮件自动链接 <address@example.com>. 使用纯HTML

注意

  • 博客园的 markdown 编辑器不支持标题下方的 ---。
  • 若在博客园的 markdown 编辑器编辑的文档中，标题下使用了 --- 作为标题结束，会导致标题无法渲染。
  • 博客园的 markdown 文档标题总是从一级标题开始，并且标题下不要使用 ---， 这样才能渲染标题，生成目录。

推荐阅读