标签：site   mpi   contains   table   输出   文件   contain   purchase   apple   

参考文章

• 参考 ：【Markdown: Syntax】
  
• 参考 ：【Markdown 书写风格指南】
  
• 参考 ：【Markdown Style Guide】
  
• 参考 ：【Markdown 书写风格规范及美化】
  
• 参考 ：【令人惊艳的博客】

通用规则

文件

• 文件扩展名使用： .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 文档标题总是从一级标题开始，并且标题下不要使用 ---， 这样才能渲染标题，生成目录。

Markdown个人使用规范

标签：site   mpi   contains   table   输出   文件   contain   purchase   apple   

原文地址：https://www.cnblogs.com/bogonogob/p/10421084.html