Markdown 深度写作指南

本教程仅供学习传播,转载请注明出处@Tianxing Zhang's Blog

注:教程目前仍在维护中,尚有大量工作没有完成,请见谅!

0. 前言


本教程最初来自于我对互联网上流传的各类 Markdown 教程的整理,原意是为供自己遗忘时参考,但鉴于现有 Markdown 中文教程质量参差不齐、内容多有不全,遂撰此教程,希望能对读者朋友们有所帮助。

本教程主要参考了以下资料:

个人作品,错误和疏漏之处在所难免,恳请读者批评指正。

Email:zhangtianxing93@gmail.com

1. 认识 Markdown


1.0 什么是 Markdown

这是 Wikipedia 上对 Markdown 的定义:

Markdown is a lightweight markup language with plain text formatting syntax.

Markdown 是一种轻量级标记语言,可使用纯文本编辑器(如Vim、Emacs等)进行编写,通过简单的标记语法,它能为纯文本文件添加格式。
使用 Markdown 编辑器/解释器,它能够很方便地被转换为 HTML、PDF、LaTex 等格式,从而实现“一次书写,到处流通”。

John Gruber 在 2004 年与 Aaron Swartz 合作发明了 Markdown,旨在创造一种“易于阅读、易于书写的纯文本格式”。他使用 Perl 语言写了第一个能够把 .md 文件转为 .html 文件的解释器。

今天,Markdown 已经成为世界上最流行的几种标记语言之一。

1.1 为什么使用 Markdown

为什么使用 Markdown?这里有几个不错的理由:

  • 内容和格式分离,专注于写作本身而不是排版。
  • 作为纯文本内容,兼容于所有文本编辑器和字处理软件。
  • 可以轻松导出成多种格式的文件:.md/.pdf/.html/.tex/.doc等。
  • 支持LaTeX公式,方便进行科技写作。
  • 方便进行版本控制,不必像字处理软件那样生成多个文件导致版本混乱。
  • 直观、可读性好、学习成本低。

正因如此,无论是撰写博客文章、软件README文档、学术论文,还是在论坛发帖子,Markdown 都是很好的选择。

1.2 Markdown 工具


1.2.0 文本编辑器

俗话说得好:磨刀不误砍柴工。书写 Markdown 首先需要一款称手的编辑器,它不仅可以帮助你将文件导出为各种丰富的格式,还可以给你“所见即所得”的写作体验。

  • 桌面端
    • Windows 平台上,建议你使用 MarkdownPad 或 Typora。
    • Mac OS X 平台上,建议你使用 Ulysess、Byword 或 Mou。
    • Linux 平台上,建议你使用 Remarkable 或 ReText。
  • 移动端
    • iOS 平台上,建议你使用 Ulysses 和 iA Writer。
    • Android 平台上,建议你使用 MarkdownX。
  • Web端

事实上,这些编辑器很多都是跨平台的:

关于软件的选择,你还可以参考:

另外,很多常用编辑器如 Vim、Emacs、Sublime、Atom 等经过配置后,也非常适合 Markdown 写作。

1.2.1 图床

很多人对文本编辑器比较熟悉,对“图床”却没有概念。

什么是图床呢?说白了,图床就是一种特殊的网盘,能提供托管个人图片和图片外链分享的服务,而我们日常所使用的大多数网盘都没有图片外链分享的功能。

那图床和 Markdown 又有什么关系吗?这就要说到 Markdown 的一个小缺点了:插入图片。Markdown 中插入图片得靠链接,因为图片本身是不可能包含在纯文本文件里的。这样做有两个缺点:一是本地图片其他人看不到,二是外链图片有丢失的风险,你一定不希望有朝一日,自己写的博文配图都不见了吧。

因此,最好的方法就是把文件中要用到的图片全都上传到一个私有图床上,自己搭建服务器代价太高,只能去网上找相关的云服务提供商。所幸目前还是有免费的解决方案的,我给个链接,感兴趣的同学可以尝试一下:

其实大多数情况下文章的配图还是能在网上找到的,而且图片一般也不太会丢失,所以多数情况下,要求低一些或者懒得折腾的同学用外链图片也没什么问题。

2. Markdown 语法规则


2.0 标题(Headers)

标题是每篇文章都有的常见格式。将一句话定义为标题,只需在前面加上几个##越多标题等级越低# Header1表示一级标题,# Header6表示六级标题:

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

实际效果:

一级标题

二级标题

三级标题

四级标题

五级标题
六级标题

虽然标题名和#之间有没有空格、有几个空格无关紧要,但良好的写作风格要求#和标题名称之间保持一个空格距离,这样能让源码读起来更舒服。

更多关于写作风格上的建议,会在 Markdown 书写风格一章中陆续给出。

2.1 列表(Lists)

列表常用于表示一连串平级的概念,Markdown 中的列表又可以分成无序列表有序列表两大类。

无序列表需要在文字前加上-*,并注意符号和文字之间的空格是必须的:

- 苹果
- 香蕉
- 梨子

实际效果:

  • 苹果
  • 香蕉
  • 梨子

有序列表则要在文字前加上1. 2. 3.等数字编号,实际上数字的顺序并不会影响最终显示效果:

2. 苹果
1. 香蕉
5. 梨子

实际效果:

  1. 苹果
  2. 香蕉
  3. 梨子

除此以外,列表的嵌套也很常见,只需要

2.2 块引用(BlockQuotes)

2.3 链接(Links)

2.4 图片(Images)

2.5 短语强调(Phrase Emphasis)

2.6 表格(Tables)

2.7 代码(Codes)

2.8 分割线(Horizontal Rule)

使用***---表示水平分割线(*-的数量必须大于等于三个),分割线能使你的文章看起来结构清晰、更有条理:

## 

实际效果:

事实上,你会发现有的 Markdown 解释器会自动在某一等级的标题下方添加一条细横线(比分割线更细,离文字更近),比如我所使用的 MarkdownPad 就会在二级标题下方添加横线,VS Code 会在一级标题下方添加横线,而简书则完全不会在标题下加任何东西。所以当你移植有分割线的 Markdown 文件时,最好先搞清楚目标解释器的特点。

3. Markdown 书写风格


什么是“书写风格”?

风格可以理解成做同一件事的不同方法。在 Markdown 里,同样的文本可以有多种合法的源码,比如我想写一个有序列表,可以这样写:

1. 苹果
2. 香蕉
3. 梨子

也可以这样写:

1. 苹果
1. 香蕉
1. 梨子

两种写法显示效果完全一样:

  1. 苹果
  2. 香蕉
  3. 梨子

到底应该用哪种写法呢?我相信聪明的你一定已经有了答案,没想出来也不要紧,我们很快就会讲到,耐心向下看即可。

为什么要保持良好的书写风格?符合语法还不够吗?

遵循特定风格不是必须的,但有这些好处:

  • 良好的书写风格有助于增加代码的可读性,使代码的维护更加容易。
  • 从读者角度考虑,排版美观的文本阅读起来也更加高效。
  • 不同解释器对于 Markdown 源码的解释有一定出入,同样的代码经不同解释器呈现出的效果可能大不相同,保持一个标准的书写风格有利于文本的可移植性。

我们要使用哪种书写风格呢?

本教程讲解的书写风格主要参考了 Markdown 书写风格指南以及 Google Markdown Style Guide,这是两种比较主流的、被实践证明行之有效的风格。
事实上,如果你认为你自创的书写风格也有以上优点,使用你自己的风格也是完全可以的,尤其是当使用场景比较特殊的时候,更是如此。

书写风格的哲学

  • 如果在 Markdown 中有几种做事情的方法,请只选择常见的一种并坚持下去。
  • Markdown 的核心在简洁实用,而不是让自己变得和 Word 一样全面庞杂,所以不要用 Markdown 去做它不擅长的事情,比如画复杂的表格乃至流程图,把这些留给插图吧。

4. 后记

可以说,这篇教程首先是写给我自己看的

有人说,Markdown 这么简单,五分钟学会的事,有必要写长篇大论吗?为什么不让 Markdown 只专注内容,把样式留给 CSS 呢?好吧,我承认我有点强迫症,虽然到最后.md还是会变成.html,但我就是不喜欢用一堆杂交的语法来写作。我喜欢做一件事只有一种方法,而 Markdown 本身已经能满足我的要求。

你当然可以只学五分钟 Markdown 就开始使用它,这正体现了 Markdown 的简洁实用,好的工具应该有最低的学习成本和最棒的效果。但如果你和我一样热爱 Markdown,并希望坚持使用它来写作,多花一点时间确定写作风格也是值得的。

学习 Markdown 和学其他知识没什么不同,一定要多练习多琢磨。当我下决心写这篇教程的时候,我和你们中的很多人一样只是个热爱 Markdown 的新手,但当我完成这篇 xxx 字的文章后,我和曾经的我已不可同日而语。

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 211,423评论 6 491
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 90,147评论 2 385
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 157,019评论 0 348
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 56,443评论 1 283
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 65,535评论 6 385
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 49,798评论 1 290
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,941评论 3 407
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 37,704评论 0 266
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 44,152评论 1 303
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 36,494评论 2 327
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 38,629评论 1 340
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 34,295评论 4 329
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,901评论 3 313
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,742评论 0 21
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,978评论 1 266
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 46,333评论 2 360
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 43,499评论 2 348

推荐阅读更多精彩内容