Markdown 书写风格指南

Markdown 是一种轻量级标记语言。你不需要关心标题多大字号,段前距多少,列表缩进几格,只要在纯文本前后增加一些标记符号(例如 # - * >),就能够毫不费力地写出排版整齐的文章来。

Write once, export everywhere,不管在电脑上,还是手机上,用 Markdown 写出来的文章都能带来舒适、统一、美好的阅读体验,总是让人赏心悦目。最可怕的是,当学会 Markdown(几分钟出师),你可能再也不想碰 Word 了。接下来,就是见证奇迹的时刻。

入门

一开始你只要记住以下符号,就能排出清爽的文章:

标记符号 标记结果
# + 空格 一级标题
## + 空格 二级标题
### + 空格 三级标题
1 + . + 空格 有序列表
* + 空格 无序列表
> + 空格 引用

如果有些文字需要特殊说明:

标记符号 标记结果
** + 加粗 + ** 加粗
* + 斜体 + * 斜体
~~ + 删除线 + ~~ 删除线

Damn, easy-to-read and easy-to-write(易读易写),手痒了吧,赶紧下载一个Markdown 编辑器(例如 Typora有道云笔记, Keep calm and Markdown。

What You See Is What You Mean

进阶

在使用 Markdown 写作的这几年里,我发现了一些好用的 Tips(小技巧),下面介绍给你。

标题

  • # 作为文章的标题,## 作为正文的一级标题,### 作为正文的二级标题。这么做的理由是:# 作为出发点,## 作为分论点,这样的大纲结构可以很方便地转换为思维导图(Markdown to Xmind / MindNode / 幕布 / 百度脑图……)。
  • 虽然 Markdown 最大支持 ###### 六级标题,但不建议分太多层级,因为读者可能会迷失在混乱的大纲结构里,你可以使用 1.有序列表或 -无序列表代表末级标题。
  • 不要跳跃使用标题等级。
  • 标题要简短。
  • 标题结尾不带标点符号。
  • 标题前后空一行(段前距和断后据)。
  • 大标题和小标题之间要有内容过渡(引出或概括下文):
# Markdown

Markdown 是一种轻量级标记语言,创始人为约翰·格鲁伯(英语:John Gruber)。它允许人们「使用易读易写的纯文本格式编写文档,然后转换成有效的 XHTML(或者 HTML)文档」。这种语言吸收了很多在电子邮件中已有的纯文本标记的特性。

## 历史

❗不能省略此段❗ John Gruber 在 2004 年创造了 Markdown 语言,在语法上有很大一部分是跟亚伦·斯沃茨(Aaron Swartz)共同合作的。……

### 标准化

Markdown 已经成为典型的转换为 HTML 的非正式规范和参考实现。……

### CommonMark

从 2012 年开始,包括 Jeff Atwood 和 John MacFarlane 在内的一群人启动了 Atwood 的标准化工作。……

### GFM

2017 年,GitHub 发布了基于 CommonMark 的 GitHub Flavored Markdown(GFM)的正式规范。……

……

> by Wikipedia

表格

源代码:

| 左对齐           |                      居中对齐                      | 右对齐 |
| :--------------- | :------------------------------------------------: | -----: |
| **加粗** | [插入链接](https://tingtalk.me/) | ¥5.7 |
| `换行`<br />下一行 | ![插入图片](https://tingtalk.me/uploads/avatar.png) | ¥10.4 |

预览:

左对齐 居中对齐 右对齐
加粗 插入链接 ¥5.7
换行
下一行
插入图片 ¥10.4

注:

  • Markdown 是轻量级的标记语言,所以不支持合并和拆分单元格。对于复杂表格,你可以在 Markdown 编辑器中使用 HTML 标签标记。
  • 输入 <br /> 可以换行,但尽量少这么干。

代码块

写法:

​```python
print "Hello, Python!"

预览:
```python
print "Hello, Python!"

引用

在每一行使用 > 符号,包括换行的句子:

> 我们是为人民服务的,所以,我们如果有缺点,就不怕别人批评指出。
> by 毛泽东:《为人民服务》(1944 年 9 月 8 日)

我们是为人民服务的,所以,我们如果有缺点,就不怕别人批评指出。
by 毛泽东:《为人民服务》(1944 年 9 月 8 日)

无序列表

使用 *+ 并跟随一个空格来表示无序列表。

建议使用 (连字符,hyphen):

- 我是谁
- 我从哪里来
- 我到哪里去

不建议:

* 我是谁
* 我从哪里来
* 我到哪里去

+ 我是谁
+ 我从哪里来
+ 我到哪里去

解释:

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

有序列表

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

1. a
1. c
1. b

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

1. a
2. c
3. b

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

- item 1

- item 2

- item 3

建议使用:

- item 1
- 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

列表项结尾标点

列表项结尾标点,除非:

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

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

不建议使用,以:

- 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

其他

首行不缩进

直接在 Markdown 里用空格和 Tab 键缩进在渲染后会被忽略掉,需要借助 HTML 转义字符在行首添加空格来实现,&ensp; 代表半角空格,&emsp; 代表全角空格。

示例代码:

&emsp;&emsp;春天来了,又到了万物复苏的季节。

示例效果:

  春天来了,又到了万物复苏的季节。

分割线首选使用星号

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

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

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

不要 使用内部空格。

建议使用:

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

不建议:

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

购物清单

  • 一次性水杯
  • 西瓜
  • 豆浆
  • 可口可乐
  • 小茗同学

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

不建议:

Before.
# Header 1

## Header 2
After.

建议使用:

Before.

# Header 1

## Header 2

After.

To include a pipe | as content within your cell, use a \ before the pipe:

分行

Typero:Shift + Enter 插入 <br />

硬回车

需要在行末使用两个空格。

连续的两个换行符对应渲染结果中的新段落,而如果想得到一个「软回车」,则要输入两个空格,然后一次回车。

因为 h1 通常用作文章标题,不建议在正文中使用

重音符(backtick)前后空一格

- 推荐:使用键盘快捷键 `Ctrl + D` 可以将当前网页保存为书签
- 反对:使用键盘快捷键`Ctrl+D`可以将当前网页保存为书签

列表

1.  2 spaces after a numbered list.
4 space indent for wrapped text.

2. 2 spaces again.

* 3 spaces after a bullet.
4 space indent for wrapped text.
1. 2 spaces after a numbered list.
8 space indent for the wrapped text of a nested list.
2. Looks nice, don't it?
* 3 spaces after a bullet.

当然,如果列表规模很小、没有嵌套、只有单行,那么单个空格也足够了

* Foo
* Bar
* Baz.

1. Foo.
2. Bar.

Tab 键
Shift Tab

代码

列表内嵌代码块

  • Bullet.

    int foo;

* Next bullet.
*





[^1]: 脚注解释①
[^2]: 脚注解释②



## 编辑器

### Typora

使用Typora编辑Markdown文章后,可以导出成opml格式,再导入幕布。



一篇排版优美的文章就会呈现在你面前。



所见即所得 Typora

表格粘贴

Google 搜索





Word 的绝佳替代品。

Markdown here



###



## 练习

http://commonmark.org/help/tutorial/index.html

https://tableconvert.com/
庭勃士 wechat
0%