Markdown 书写风格指南 | 安云网

发表评论
150 次浏览

A+

所属分类：系统文档

在线 Markdown 书写风格指南

关于
- 设计目标
- 著名用户
- 可选
- 书写约定
- 可供选择
- Lint tools
通用规则
- 文件
  - 文件扩展名
  - 文件名
- 空白
  - 新行
  - 句子结束空格
    - 可选 space-sentence:1
    - 可选 space-sentence:2
- 自动换行
  - 可选 wrap:inner-sentence
  - 可选 wrap:no
  - 可选 wrap:space
  - 可选 wrap:sentence
- 代码
  - Shell中美元符号
  - 标记代码内容
  - 拼写和语法
区块
- 换行符
- 标题
  - 可选 header:atx
  - 可选 header:setex
  - 顶级标题
  - 标题大小写
  - 标题结尾
  - 标题长度
  - 标题结尾标点
  - 标题同义词
- 引用
- 列表
  - 标记
    - 无序
    - 有序
  - 列表项中的空格
    - 可选 list-space:mixed
    - 可选 list-space:1
    - 解释: list-space mixed vs 1
  - 列表内容的缩进
  - 列表中的空行
  - 列表外的空行
  - 列表项首字母大小写
  - 列表项结尾标点
- 定义列表
- 代码区域
  - 可选 code:fenced
  - 可选 code:indented
- 水平横线
- 表格
- 分离相连的列表
Span元素
- 链接
  - 参考样式链接
  - 单引号或双引号标题
- 强调
  - 加粗
  - 斜体
  - 大写强调
  - 强调与标题
- 自动链接
  - 使用尖括号自动链接
  - 内容的自动链接
  - 电子邮件自动链接

关于

参考原始设计规范,
CommonMark 和其他扩展。

本项目由社区驱动, 尝试达成共识。
只有当社区达成一致时，项目维护者才将其加入此文档。

讨论将在 GitHub issue 展开。

本文档源代码托管在 GitHub。

设计目标

易读
可移植性: 通过不同的实现，产生相同的输出或者更好的输出文本。

移植性测试在 Markdown Test Suite 开展。
容易书写和修改
友好的文件差异对比
容易记忆，容易被编辑器实现
从不同的选择中抽取基本原理

每一个需要解释的区域或者段落都会标注 rationale
所以，如果你只对最后的规范感兴趣，可以跳过解释。

著名用户

你在使用这份风格指南吗？将你的名字添加到我们的 wiki.

如果你很著名? 给我们发送一个 pull request.

如果你是一个著名的用户：

你会在此标准遇到较大更新时得到提醒。
在提交 pull request 之前请提前了解。
你对此标准的决定，制定者会有更大的考虑。

如果你的项目满足以下条件，请毫不犹豫的发送 pull request吧：

大量使用 Markdown . 比如说: markdown 引擎, markdown 文本编辑器, 大量 markdown 文档等等。
是否受到欢迎的标准。任何的流行评判标准都会考虑。比如说，GitHub 加星数,
Google Rank 等等. 2K+ GitHub 加星会很有说服力。

可选

有争议的内容会给出多种可选择的风格。

每一种可选项会用小写连字符分割提示。

每一种可选项都会有以下格式的说明:

# Option key:value

The first option header that appears in this text is the default value.

比如，如果自动换行 wrap 有三种风格，我们会给出关键词 wrap,
并且给每一种风格一种名字，比如：

# Option wrap:space
# Option wrap:no
# Option wrap:sentence

当引用此标准时，准确标明所有非默认选项的风格，并用逗号分割：

Use the Markdown Style Guide wrap:space, code:indented

书写约定

当这份风格指南需要多种表示空格的方式，或者在代码区块开始或结束时出现空格时，点号将被用来表示空格。

例如:

a, 空格, b:

a b

a, 2 空格, b:

a..b

空格, ab:

.ab

ab, 空格:

ab.

可供选择

Google 风格指南

这份指南最初从carwin/markdown-styleguide fork 得来.
原始文档已经被大规模的改动，一些决定已经被修改，几乎已经找不到原文。

Miguel de Icaza (GNOME, Mono) 已经提出一份简短的风格指南
http://tirania.org/blog/archive/2014/Sep-30.html

Lint tools

在 Stack Exchange 上的提问: http://softwarerecs.stackexchange.com/questions/7138/markdown-lint-tool/

通用规则

文件

文件扩展名

使用 .md.

解释: 为什么不使用 .mkd 或者 .markdown?

更短
更加流行
没有明显冲突

文件名

文件名建议使用如下的风格:

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

建议使用:

file-name.md

不建议, 多个连续的连字符:

file--name.md

不建议, 包围的连字符:

-file-name-.md

解释: 为何不使用下划线和驼峰大小写？连字符是现在最流行的网址分隔符，并且 Markdown 文件在上下文中经常使用:

可能在同一个项目中有连字符分割的HTML文件使用Markdown相同的目录。
文件名会被直接使用到 URL 中. 比如: GitHub blobs.

空白

新行

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

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

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

建议使用:

- list
- list

# Header

建议, 代码区块:

The markup language X requires you to use triple newlines to separate paragraphs:

    p1


    p2

不建议：

- list
- list


# Header

解释: 多空行占用更多的竖直屏幕空间，并且会严重影响到可读性。

句子结束空格

可选 space-sentence:1

句子结束使用一个空格

不建议, 使用2个空格:

First sentence.  Second sentence.

建议使用:

First sentence. Second sentence.

解释: 相比于space-sentence:2的优点:

容易编辑
通常不是必须的，如果使用 wrap:inner-sentence or wrap:sentence
space-sentence:2 对可读性造成一种错误的感觉，因为忽略了输出的 HTML 文件。
更加流行

相较于 space-sentence:2 的优势:

容易查看一句话的结束

可选 space-sentence:2

不建议, 单个空格:

First sentence. Second sentence.

建议使用:

First sentence.  Second sentence.

自动换行

可选 wrap:inner-sentence

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

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

一行中超过80个字符是可以接受的，但是记住长句子不适合阅读，并且在 git diff 中会很难看。

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

建议使用:

This is a very very very very very very very very very very very very very long not wrapped sentence.
Second sentence of of the paragraph,
third sentence of a paragraph
and the fourth one.

解释:

Diffs 工具看起来更好, 因为一个子句的修改在 diff 工具中显示为一行修改.
临时的换行不会降低对 Markdown 文件的可读性，
因为唯一的语言特性，可以缩进表示层次结构的就是嵌套列表。
现在除了 GitHub 在 README 和评论中将单独一行解释成回车。
没有其他主流的解释引擎这么做，使用换行是非常安全的。
一些工具对较长的一行不友好，比如 Vim 并且 git diff 默认并不换行.
这些不友好都可以通过配置除去，对于git，使用 git config --global core.pager 'less -r' 对于Vim可以使用 set wrap 来自动换行.

缺点:

需要在写作时增加顾虑，尤其是在修改代码的时候。
Markdown 看起来和渲染输出不同, 输出没有换行符。

手动的换行可以让 Markdown 比生成的文档更加易读，
当然这样做的同时，也造成了一种虚假的可读性错觉，让人感觉没有长段落。
需要用户拥有使用可编程文本编辑器，类似 Vim，可以通过配置来换行。EditorConfig gave it WONTFIX

可选 wrap:no

不要自动换行.

解释: 很容易编辑。但是长句子的 diffs 很难阅读。

可选 wrap:space

在超过80个字符的第一个单词换行。

解释: 源文件易读，并且文本编辑器支持。Diff 比较难读，并且修改困难。

可选 wrap:sentence

解释: 和 wrap:inner-sentence 相似的优点, 但是规则通俗易懂:
在句号后换行。对于长句子依然面临 Diff 难以阅读的困扰。

著名事件: ProGit 2.

代码

Shell中美元符号

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

如果目的是表明确切的语言，那么直接在代码前标明。

解释: 复制粘贴比较困难，不利于阅读。

建议使用:

echo a
echo a > file

不建议：

$ 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.
```
注意将工具名字和项目工程名字区别开来。比如： gcc vs GCC.
文件路径
程序版本号

大写的缩写解释:

xinetd stands for `eXtended Internet daemon`

其他和电脑相关的术语，想要单独标明

不要标记为代码：

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

拼写和语法

使用正确的拼写和语法。

尽量选用英语，更准确的说美式英语。
解释: 美式英语使用者占有最大的GDP，尤其是在计算机行业。

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

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

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

一旦有疑惑，尽量选用和维基百科相同的缩写。

避免使用非正式的缩写:

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

区块

换行符

避免使用换行符, 因为他们没有被广泛认可的语义。

在少数确实需要使用的时候，在行尾使用两个空格。

标题

可选 header:atx

不建议：

Header 1
========

Header 2
--------

### Header 3

建议使用:

# Header 1

## Header 2

### Header 3

解释: 相比 Setex 优势有:
- 容易书写，因为在 Setex 中，为了好看需要书写和标题相同数量的符号
- 可以生成所有的等级，而 Setex 只能生成两种等级
- 只占用一行，而 Setex 占用两行
Setex 的优点
- 更加明显。 Not very important if you have syntax highlighting.
在 # 和标题之间加入一个空格.

不建议：
```
#Header

#..Header
```
建议使用:
```
# Header
```
不要使用闭合的 # .

不建议：
```
# Header #
```
建议使用:
```
# Header
```
解释: 容易维护。
不要在 # 前加入空格.

不建议：
```
.# Header
```
建议使用:
```
# Header
```

可选 header:setex

不建议：

# Header 1

## Header 2

### Header 3

建议使用:

Header 1
========

Header 2
--------

### Header 3

不要跳跃使用标题等级.

不建议：
```
# Header 1

### Header 3
```
建议使用:
```
# Header 1

## Header 2
```

在标题上下用空行隔开，除非标题在文档开头。

不建议：

Before.
# Header 1

## Header 2
After.

建议使用:

Before.

# Header 1

## Header 2

After.

不建议：

Before.
Header 1
========

## Header 2
-----------
After.

建议使用:

Before.

Header 1
========

## Header 2
-----------

After.

避免在相同 Markdown 文件中使用相同的标题.

解释: 许多的 Markdown 解释器会依据标题的内容生成标题的IDs。

不建议：
```
# Dogs

## Anatomy

# Cats

## Anatomy
```
建议使用:
```
# Dogs

## Anatomy of the dog

# Cats

## Anatomy of the cat
```

顶级标题

如果你想要 HTML 直接输出，这样唯一的 h1 标记就是输出的第一件事，并且会成为文档的标题。这就是HTML的顶级标题。

h1 标题的产生受到使用的 Markdown 引擎的直接影响：
一些引擎会从元数据（metadata）中产生标题，比如 Jekyll 就是从 front-matter 中产生标题。

将顶级标题保存为元数据（metadata）可以更加方便的在其他地方使用，
比如，在全局索引中，但也有缺点，比如降低了可读性和移植性。

如果目的不是生成顶级标题，
include it in your markdown file. E.g., GitHub.

索引文件中的顶级标题比如 README.md 或者 index.md
应该作为他们父目录的标题。

顶级标题的缺点：

占用了一级标题。这就意味只剩下5个层级标题可以使用。
并且这样每一个新的标题就会多使用一个 # 符号,这样看起来不好。
重复了文件名, 通常已经可以直接从 URL 中读到。
在大多数的情况下，文件名可以直接转换成顶级标题，
比如: 从 some-filename.md 到 Some filename.

顶级标题的优点:

比URL更加易读，尤其是对非技术出身用户。

标题大小写

标题开头使用大写字母，除非标题内容总是以小写出现, 例如，计算机代码。

建议使用:
```
# Header
```
建议使用, 代码通常以小写开始：
```
# int main
```
不建议：
```
# header
```
其他字母按照句子中原始大小写。

建议使用:
```
# The header of the example
```
不建议：
```
# The Header of the Example
```
例外, 首字大写
对顶级标题可选择性支持。
请异常谨慎地使用, in cases where typographical perfection is important,
比如：项目的 README .

解释: 为什么对所有标题首字大写 ?
如果要决定句子中每一个单词大小写会花费太多精力。

标题结尾

显示标题的内容，而不是用新标题和水平线紧随其后：

# Header

Content

---

Outside header.

标题长度

保证标题越短越好。

避免使用长句子，总结长句子作为标题，然后将长句子作为标题下的第一小节。

解释: 以后引用方便，尤其是自动生成 IDs 或者生成 TOC 。

建议使用:

# Huge header

Huge header that talks about a complex subject.

不建议：

# Huge header that talks about a complex subject

标题结尾标点

不要在标题中以 : 结尾。

解释: 每一个标题都是接下来内容的简介，这也就正是冒号的作用。

不要在标题中以 . 结尾。

解释: 每一个标题都包含一个简短的句子，也就不需要句号来分隔他们。

建议使用:

# How to do make omelet

不建议：

# How to do make omelet:

不建议：

# How to do make omelet.

标题同义词

标题用作用户索引的关键词。

正由于这个原因，你可能希望在标题中用多个关键词。

要做到这一点，简单的创建一个同义词标题在主标题之前，并且标题下不包含内容。

比如：

# Purchase

# Buy

You give money and get something in return.

每一个同层级的空标题都假定是同义的。如果层级不一样，那就是另外的含义：

# Animals

## Dog

引用

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

建议使用:
```
> a
```
不建议：
```
>a
```
不建议, 2个空格:
```
>  a
```
在每一行使用 > 符号，包括换行的句子。

不建议：
```
> Long line
that was wrapped.
```
建议使用:
```
> Long line
> that was wrapped.
```
不要在单独的引用中使用空行。

建议使用:
```
> a
>
> b
```
不建议：
```
> a

> b
```

列表

标记

无序

使用连字符.

建议使用：

- a
- b

不建议：

* a
* b

+ a
+ b

解释:

星号 * 可能和加粗和斜体符号产生混淆。
加号 + 不流行。

有序

尽量选用 1. 来标记有序的列表, 除非你打算通过数字在相同 Markdown 文件或者外部文件中引用他们。

尽量使用无序的列表，除非有通过数字引用的需求。

最佳则是从来不通过序号来引用他们：

- a
- c
- b

较好的方法, 仅仅使用 1.:

1. a
1. c
1. b

较差的方法, 不要通过序号来标注列表项的顺序:

1. a
2. c
3. b

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

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.

解释:

如果你想要改变列表中的一个列表项，你不要修改它下面的列表项。

Diffs 工具只会显示被修改的重要的内容。
如果序列有两位，也不需要额外注意，内容保持一致。比如：下面不对齐：
```
9. a
10. b
```
如果新列表项被加入，引用会破坏。尽量减少这种问题：
- 保证引用靠近列表，这样作者会更少可能的忘记去更新
- 当从外部引用时，总是引用到一个固定版本的 markdown 文件

列表项中的空格

可选 list-space:mixed

如果每一个列表项的内容都只有一段，使用 1 个空格。
否则，对于列表中的每一项:
- 给无序列表使用 3 个空格。
- 给有序列表使用 2 个空格。
  比无序少一个空格，因为符号占用两个字符。

不建议, 每一项一行:

-   a
-   b

建议使用:

- a
- b

不建议, 每一项一行:

1.  a
1.  b

建议使用:

1. a
1. b

每一项超过一行，不建议：

- item that
  is wrapped

- item 2

建议使用:

-   item that
    is wrapped

-   item 2

每一项超过一行，不建议：

- a

  par

- b

建议使用:

-   a

    par

-   b

可选 list-space:1

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

不建议, 使用三个空格:

-   a

    b

-   c

建议使用:

- a

  b

- c

不建议, 两个空格:

1.  a

    b

1.  c

建议使用:

1. a

   b

1. c

解释: list-space mixed vs 1

使用 list-space:1 的有点：

它去除了你需要决定在列表符号后面放置多少空格的顾虑：
因为只放一个

我们也可以选择在列表项中如下缩进：
```
-   a
-   b
```
但是这样非常丑。
你不会因为新列表项而改变整个列表的缩进。

但是这样的情况会发生在 list-space:mixed 如果你有：
```
- a
- b
```
并且想要增加一个多段落列表项：
```
-   a

-   b

-   c

    d
```
注意， a 和 b 都因为 c 而改变了。

使用 list-space:1 的缺点：

产生了三种缩进方式：
- 4 for 缩进的代码块
- 3 for 有序列表
- 2 for 无序列表
这意味着你不能轻松的配置编辑器缩进来处理所有的情况，当你想要改变缩进层级的时候需要调整多行。
没有被编辑器实现。

具体来说下面的情况会发生什么:
```
- a

        code
```
这个(2 个空格):
```
<pre><code>  code
```
或者没有空格：
```
<pre><code>code
```
原始的 markdown 说不需要空格:

To put a code block within a list item, the code block
needs to be indented twice — 8 spaces or two tabs

但是许多第三方的实现了。

CommonMark adds the 2 spaces.

列表内容的缩进

列表中内容的缩进层级必须和第一个列表项一致：

不建议：

-   item that
  is wrapped

-   item 2

建议使用:

-   item that
    is wrapped

-   item 2

不建议：

-   item 1

  Content 1

-   item 2

      Content 2

建议(如果符合列表标记之后的空格):

-   item 1

    Content 1

-   item 2

    Content 2

不建议：

- item 1

    Content 1

- item 2

    Content 2

建议(如果符合列表标记之后的空格):

- item 1

  Content 1

- item 2

  Content 2

避免开始直接使用缩进的代码列表项，因为这样不容易实现。CommonMark states that 一个单独的空格需要加入:

-     code

  a

列表中的空行

如果每一个列表项只有一行, 不要在列表项之间增加空行，否则，在每一个列表项之间增加空行。

不建议, single lines:

- item 1

- item 2

- item 3

建议使用:

- item 1
- item 2
- item 3

多行情况下，不建议:

-   item that
    is wrapped
-   item 2
-   item 3

建议使用:

-   item that
    is wrapped

-   item 2

-   item 3

不建议, 多行:

-   item 1

    Paragraph.

-   item 2
-   item 3

建议使用:

-   item 1.

    Paragraph.

-   item 2

-   item 3

不建议, 多行:

-   item 1

    - item 11
    - item 12
    - item 13

-   item 2
-   item 3

建议使用:

-   item 1

    - item 11
    - item 12
    - item 13

-   item 2

-   item 3

解释: 如果没有空行，很难分别多行的列表项开始和结束。

列表外的空行

列表外建议留有一空行。

不建议：

Before.
- item
- item
After.

建议使用:

Before.

- list
- list

After.

列表项首字母大小写

每一个 list 使用原来在句子中的大小写.

建议使用:

I want to eat:

- apples
- bananas
- grapes

因为它可以被如下替换：

I want to eat apples
I want to eat babanas
I want to eat grapes

建议使用:

To ride a bike you have to:

- get on top of the bike. This step is easy.
- put your foot on the pedal.
- push t the pedal. This is the most fun part.

因为它可以被如下替换：

To ride a bike you have to get on top of the bike. This step is easy.
To ride a bike you have to put your foot on the pedal.
To ride a bike you have to push the pedal. This is the most fun part.

建议使用:

# How to ride a bike

- Get on top of the bike.
- Put your feet on the pedal.
- Make the pedal turn.

因为它可以被如下替换：

# How to ride a bike

Get on top of the bike.
Put your feet on the pedal.
Push the the pedal.

列表项结尾标点

列表项结尾标点，除非:

包含多个句子或者短语
以大写字母开头

否则, 如果以句号结尾的话，省略标点.

不建议使用，以:

- apple.
- banana.
- orange.

建议使用:

- apple
- banana
- orange

同上:

- go to the market
- then buy some fruit
- finally eat the fruit

建议使用, 不以句号结尾，而是以其他标点结尾：

- go to the marked
- then buy fruit?
- of course!

不建议, 多个句子时末尾不加标点:

- go to the market
- then buy some fruit. Bad for wallet
- finally eat the fruit. Good for tummy

建议使用:

- go to the market
- then buy some fruit. Bad for wallet.
- finally eat the fruit. Good for tummy.

注意：没有任何理由阻止，一个列表项以句号结尾，另一个列表项没有。

不建议, 多段落:

-   go to the market

-   then buy some fruit

    Bad for wallet

-   finally eat the fruit

    Good for tummy

建议使用:

-   go to the market

-   then buy some fruit.

    Bad for wallet.

-   finally eat the fruit.

    Good for tummy.

不建议, 如果以大写字母开头，添加标点:

- Go to the market
- Then buy some fruit
- Finally eat the fruit

建议使用:

- Go to the market.
- Then buy some fruit.
- Finally eat the fruit.

定义列表

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

相反, 使用:

格式化列表:

用加粗，链接，或者代码，格式化需要定义的内容
将内容和定义使用冒号和空格分割 :.
不要对齐定义，这样难以维护，并且不会显示在 HTML 输出

建议使用:

- **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

不建议, 没有冒号:

- **apple** red fruit
- **dog** noisy animal

不建议, 在术语和冒号之间有空格:

- **apple** : red fruit
- **dog** : noisy animal

不建议, 定义对齐:

- **apple**: red fruit
- **dog**:   noisy animal

headers.

建议使用:

# Apple

Red fruit

# Dog

Noisy animal

代码区域

可选 code:fenced

仅仅使用 fenced code blocks.

和缩进代码区块比较：

不足: 不是标准 markdown 语法, 因此缺少移植性，但是加入到CommonMark.
优点: 实现方式多, 包括 GitHub’s, 并且允许指定代码的语言。

不要缩进 fenced code blocks.

总是指定代码的语言。

建议使用:

```ruby
a = 1
```

不建议：

```
a = 1
```

可选 code:indented

仅仅使用缩进代码区域。

代码区域缩进4个空格。

代码区块必须以一空行隔开。

尽量在代码块之前使用冒号结束短语 :。

建议使用:

use this code to blow up your PC:

    sudo rm -rf /

不建议, 没有冒号

use this code to blow up your PC

    sudo rm -rf /

水平横线

不要使用水平线除非表明End of a header.

解释:

标题比区块更好，因为标题就是区块的开始，并且说明了区块的内容。
水平线没有可接受的语义。
这份风格指南给了语义。

使用 3 个无空格连字符:

---

表格

扩展.

用一空行包围表格。
不要缩进表格。
用 | 包裹表格的每一行。
竖直对齐所有表格边框。
将标题和内容用连字符分割，用对齐的 |。
| 周围必须要有一个空格，除非是外部的 |。
列的宽度通过列中最长的单元格确定。

建议表格:

Before.

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

After.

解释:

不对齐的表格很容易书写，但是对齐的表格更加易读，并且人们读代码比编辑要更多。
开始的 | 更加容易看出表格的开始和结束。结尾的 | 让人看起来更加舒服，因为对称。
这些工具让表格对齐更加容易。比如，Vim 有 Tabular plugin 插件，这个插件让我们可以使用 :Tabular /| 来使整个表格对齐。
为什么在连字符分割行 | 没有空格包围, 比如: |---| 而不是 | - |?
没有空格看起来更好，在GitHub可行，缺点: 编辑器中自动对齐实现困难，因为对于分割行需要特殊的规则。

分离相连的列表

分离连续:

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

使用一个空白的 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)
[name]

不建议：

** bold **
` code `
[ link ]( http://a.com )
 [name]

对于空格至关重要的行内代码：

在写作过程中解释空格存在的必要性
如果可能在空格之后加入其他内容

建议使用:

使用连字符并跟随一个空格来表示无序列表。

解释: 大多数的浏览器不会生成包围的空格，或者复制的时候不会将他们添加到粘贴板。

链接

参考样式链接

链接:

使用结尾的 [] 隐式链接：

建议使用:
```
[a][]
```
不建议：
```
[a]
```
解释: 省略 [] 大多数主要的实现都可以使用，但是这种方式并没有在文档中有实现，原始 Markdown 也没有提到。

定义:

必须写到文件末
必须以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"

不建议, 没有安装 id 排序:

[b] http://a.com
[a] http://b.com

不建议, 没有对齐:

[id] http://id.com
[long id] http://long-id.com

单引号或双引号标题

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

解释: 单引号并不是在所有的实现中都有效，但是双引号可以。

强调

加粗

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

解释: 比双下划线格式__bold__更加常见和可读性更高.

斜体

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

解释:

比下划线格式更加常见，易读性更高
与加粗格式一致, 同样使用星号标记

大写强调

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

解释: CSS 有 text-transform:uppercase 属性,如果你愿意的话，可以轻松在全网站实现相同的效果。

强调与标题

不要使用强调元素(加粗或者斜体) 来介绍多行区块: 使用标题代替.

解释: 这个就是确切的标题的语义, 使用强调的并不是必须的。作为结果，许多实现，给标题增加有用的功能，并没有给强调元素，比如自动 id 来更加容易的引用标题。

建议使用:

# 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`
```
解释: 许多工具自动将 http 开头的字串解释成链接。

内容的自动链接

所有自动链接必须以字串 http 开始。

特别的, 不要在相对链接时使用自动链接。如果遇到相对链接，使用括号的方式创建链接。

建议使用:

[file.html](file.html)

不建议：

<file.html>

建议使用:

<https://github.com>

不建议：

<github.com>

解释: 将自动链接从HTML tags区分开很困难.
如果你想要一个相对的链接指向一个 script 的文件？

电子邮件自动链接

不要使用电子邮件自动链接 <[email protected]>. 使用纯HTML .

解释: 标准 markdown 设计规范这样描述:

“performs a bit of randomized decimal and hex entity-encoding
to help obscure your address from address-harvesting spambots”.

因此, 输出是随机的，丑陋的, 并且像规范中提到的:

but an address published in this way will probably eventually start receiving spam

我的微信
这是我的微信扫一扫

我的微信公众号
我的微信公众号扫一扫

关于

设计目标

著名用户

可选

书写约定

可供选择

Lint tools

通用规则

文件

文件扩展名

文件名

空白

新行

句子结束空格

可选 space-sentence:1

可选 space-sentence:2

自动换行

可选 wrap:inner-sentence

可选 wrap:no

可选 wrap:space

可选 wrap:sentence

代码

Shell中美元符号

标记代码内容

拼写和语法

区块

换行符

标题

可选 header:atx

可选 header:setex

顶级标题

标题大小写

标题结尾

标题长度

标题结尾标点

标题同义词

引用

列表

标记

无序

有序

列表项中的空格

可选 list-space:mixed

可选 list-space:1

解释: list-space mixed vs 1

列表内容的缩进

列表中的空行

列表外的空行

列表项首字母大小写

列表项结尾标点

定义列表

代码区域

可选 code:fenced

可选 code:indented

水平横线

表格

分离相连的列表

Span元素

链接

参考样式链接

单引号或双引号标题

强调

加粗

斜体

大写强调

强调与标题

自动链接

使用尖括号自动链接

内容的自动链接

电子邮件自动链接

登录 找回密码

登录找回密码