目录

1. 前言   1.1

2. Markdown简介   1.2

1. Markdown是什么   1.2.1

2. Markdown特点   1.2.2

3. Markdown能干什么   1.2.3

3. Markdown语法   1.3

4. Markdown心得和坑   1.4

5. Markdown编辑器   1.5

6. Markdown应用   1.6

1. 成套成系统的工具   1.6.1

2. 其他支持Markdown的工具   1.6.2

7. 附录   1.7

1. 参考资料   1.7.1

最流行的文档格式：Markdown

- 最新版本： v1.0

- 更新时间： 20190530

简介

总结目前最流行的编写文档所用的语法格式： Markdown ，包括markdown的简介、基本语法和举例、相关心得和常见的坑、各种相关工具和软件、以及具体的应用领域等等。

源码+浏览+下载

本书的各种源码、在线浏览地址、多种格式文件下载如下：

Gitbook源码

- crifan/doc_format_markdown: 最流行的文档格式：Markdown

如何使用此Gitbook源码去生成发布为电子书

详见：crifan/gitbook_template: demo how to use crifan gitbook template and demo

在线浏览

- 最流行的文档格式：Markdown book.crifan.com

- 最流行的文档格式：Markdown crifan.github.io

离线下载阅读

- 最流行的文档格式：Markdown PDF

- 最流行的文档格式：Markdown ePub

- 最流行的文档格式：Markdown Mobi

版权说明

此电子书教程的全部内容，如无特别说明，均为本人原创和整理。其中部分内容参考自网络，均已备注了出处。如有发现侵犯您版权，请通过邮箱联系我  admin 艾特 crifan.com ，我会尽快删除。谢谢合作。

鸣谢

感谢我的老婆陈雪的包容理解和悉心照料，才使得我 crifan 有更多精力去专注技术专研和整理归纳出这些电子书和技术教程，特此鸣谢。

更多其他电子书

本人 crifan 还写了其他 100+ 本电子书教程，感兴趣可移步至：

crifan/crifan_ebook_readme: Crifan的电子书的使用说明

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2021-01-17 00:10:34

Markdown 简介

下面对于Markdown做个基本的介绍。

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 09:36:40

Markdown是什么

Markdown术语上叫做： 标记语言

翻译为人话就是： 一种语法格式  =  一种文件类型

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 09:37:41

Markdown特点

Markdown 的最大特点：

- 轻量级

- 易学易读易写

-》不轻量级，重量级的，有哪些？

比如 Docbook，（虽然功能更强大，但是）写起来，使用起来，相对比较麻烦，且生成各种格式的文档需要复杂的配置和过程才能实现。

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 09:39:19

Markdown能干什么？

Markdown 去配合相关工具：

- 能生成各种格式的文件，或者叫 电子书

- pdf

- html

- epub

- mobi

- 其他格式等

- 建自己的 wiki系统

- 建自己的（ 静态 、博客类的） 网站

- 给代码写基本的 说明文档

- 比如对于 github 、 gitee ，都默认支持md类型文件，在浏览器端自动格式化显示很好的文档效果

- 给代码写 API接口文档

- 比如之前整理的：

- 用Markdown写API文档 · HTTP后台端：RESTful API接口设计

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 09:41:47

Markdown语法

TODO:

把基本的语法都整理过来，且贴上截图，

最好汇总成表格形式，一目了然

包括：

- 内容类型

- 语法

- 效果截图

- 额外说明

包括借鉴：

- 【简明版】有道云笔记Markdown指南 | 有道云笔记官方博客

- 【进阶版】有道云笔记Markdown指南 | 有道云笔记官方博客

markdown的发明者的权威的markdown的语法： Daring Fireball: Markdown Syntax Documentation

献给写作者的 Markdown 新手指南 - 简书

其他的整理的markdown的语法：

gitbook官网： Markdown - GitBook

推荐的：

Markdown Reference

Markdown Cheatsheet · adam-p/markdown-here Wiki

Markdown Syntax | Grav Documentation

Markdown-Syntax-CN/syntax.md at master · riku/Markdown-Syntax-CN

有足够影响力的Github官网采用的markdown的语法，叫做： Github Flavored Markdown ，语法： Basic writing and formatting syntax - User Documentation

Mastering Markdown · GitHub Guides

中文翻译： guodongxiaren/README: README文件语法解读，即Github Flavored Markdown语法介绍

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 10:31:02

Markdown心得和坑

代码段中包含反引号的代码段

整段代码：

- 三个反引号  ```   开始

- 三个反引号  ```   结束

比如：

```javascript

$(document).ready(function () {

alert('hello world');

});

```

后来才知道，不是一定是3个反引号，而是前后一致就可以：

【已解决】markdown中三个反印号表示代码段中如何写反印号

表格内特殊符号 [ ] 不容易支持

【已解决】Markdown中表格中包含中括号的链接无效

表格 宽度不方便自定义

【部分解决】Markdown中如何指定表格某列的宽度百分比

粘贴图片不方便

【未解决】PyCharm中markdown编辑器支持粘贴图片

不过后来找到了vscode可以加插件实现粘贴剪贴板图片：

【已解决】寻找Mac中支持直接粘贴剪贴板中的图片的Markdown的客户端

表格内单元格合并有点麻烦

只能内嵌原始的table的html代码了

且此处加了表头的背景色，文本颜色的自定义

代码：

<table>

<tr>

<td colspan="2" align="center" style="background-color:#2674BA; color:white; font-weight:700;">总部库存</td>

<td colspan="2" align="center" style="background-color:#2674BA; color:white; font-weight:700;">经销商库存</td>

</tr>

<tr>

<td>（在产线上）生产中</td>

<td>已下线（到总部的库存中）</td>

<td>（用大卡车从总部）在途中（运往经销商4S店）</td>

<td>已到店（进去4S店的库存）</td>

</tr>

</table>

效果：

详见：

【间接解决】Gitbook的markdown中如何实现表格内组合单元格

gitbook的markdown内支持内嵌html代码

用于间接实现表格中单元格内列表的效果

ul的方式

代码：

| HTTP Verb=HTTP方法 | 操作类型=CRUD | 返回 | 说明 |

| :--- | :--- | :--- | :--- |

| POST | Create创建 | <ul><li>正常</li><ul><li>最常用：200 (OK)</li><li>不太常用：201 (Created)</li></ul><li>异常</li><ul><li>404 (Not Found)</li><li>409 (Conflict)</li></ul></ul>| |

效果：

br的方式

代码：

## 上汽大众的车系车型名称

| 车系=车型大类 | 中文名 | 子车系 |

| ----------- | ----- | ----- |

| Polo | 波罗 | New Polo<br/>Cross Polo<br/>Polo GTI |

| Santana | 桑塔纳 | 桑塔纳B2<br/>桑塔纳志俊<br/>New Santana新桑塔纳<br/>Cross Santana<br/>Gran Santana 桑塔纳 浩纳 |

| Lavida | 朗逸<br/>朗行 | New Lavida 全新朗逸<br/>Gran Lavida 全新朗行<br/>Cross Lavida 全新朗境 |

| Lamando | 凌渡 | Lamando 凌渡<br/>Lamando GTS 凌渡GTS |

| Passat | 帕萨特 | 帕萨特领驭<br/>New Passat新帕萨特 |

| Phideon | 辉昂 | |

| Tiguan | 途观 | Tiguan Silk Road 途观丝绸之路版<br/>All New Tiguan L 全新途观L |

| Touran | 途安 | All New Touran L 全新途安L |

| Sharan | 夏朗 | |

效果：

详见：

【基本解决】Gitbook中markdown如何实现表格单元内显示多级列表

自定义文字的颜色

比如代码：

从上图的颜色构思角度来说：

* <p style="color: blue;">蓝军=我方=4S店</p>：4S店的所有人，算作一个总体的团队，齐心协力，共同目的目标就是：红色的目标：客户，想尽一切办法，让其尽快买车

* 且尽量买车之后，后续订单和交车的相关的业务，都在我们4S店办理

* 且买车的长远之后的，售后和保养，都尽量来我店处理

* 如果可能，等二次换车，也来我店买

* 4S店的`友军`是（背后撑腰的）车厂

* 负责批售车辆给4S店

* 4S店的订单和交车数据也会上报给车厂

* 用于获得车厂店返现和补贴

* <p style="color: red;">红军=敌人=客户</p>：要买车店客户

* 被4S店`攻击`的对象

* 但是拥有自己的自主权

* 是否买车，取决于各种条件

* 包括价格

* 服务体验

* 其他相关内容处理的是否合适

效果：

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 11:09:33

Markdown编辑器

各种编辑器支持Markdown

比如：

- VSCode

- Sublime

- Atom

等等

软件：

- 支持多平台的小书匠

- Mac

- Typora

- Mou

相关：

印象笔记最终没有完整支持markdown，而只是实现了部分小功能的快捷方式

比如：

- 有序列表 ：输入1后面加上一个点后，回车，就自动变成编号了

- 代码块 ：输入三个反引号后回车就变成code代码块了，详见：

- 【整理】印象笔记对于code代码的支持还可以

等等

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 10:10:23

Markdown应用

由于Markdown有如此多的优点，所以大家愿意使用。

现在Markdown在各个领域都有很多的应用。

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 10:17:47

成套成系统的工具

Gitbook用于发布电子书

详见：电子书制作利器：GitBook

用markdown搭建wiki系统

jekyll wiki

How do I let users log into my RESTful API? - The RESTful cookbook

-》

GitHub - restcookbook/restcookbook: Jekyll cms site for restcookbook.com

-》

Home · jekyll/jekyll Wiki · GitHub

-》

Jekyll (software) - Wikipedia, the free encyclopedia)

一套Ruby写的wiki博客系统。

作者是Github的联合创始人

-》

搜：

jekyll wiki 系统

gollum:轻量级的wiki系统

个人认为github，jekyll，gollum可以并称为码农的三大神器，github用来敲代码，jekyll用来写技术博客，gollum用来搭建自己的知识管理wiki系统。

markdown + git 最适合程序员的wiki系统 · Example Code

gollum 是github的使用的一个基于markdown的 wiki系统。 最重要的是gollum直接和git集成不需要数据库，你可以选择在Web页面撰写文档，也可以用你喜欢的markdown工具编辑文档在命令行进行提交。 “markdown+git = wiki” 这对程序员来讲绝对是最棒的选择。

在Github上建立自己的Wiki | Aitter Blog

gollum 是github的使用的一个基于markdown的 wiki系统的构造工具，简单实用。

gollum直接和git集成不需要数据库，你可以选择在Web页面撰写文档，也可以用你喜欢的markdown工具编辑文档在命令行进行提交，用来搭建自己的知识管理wiki系统。 “markdown+git = wiki” 这对程序员来讲绝对是最优(zhe)雅(teng)的方式。

类似于博客系统jekyll和hexo的功能。写博客与写wiki的区别是，前者在于创作，后者在于对知识的整理，非原创的文章适合使用wiki来整理归档。

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 14:20:39

其他支持Markdown的工具

Postman中支持markdown

详见：

给接口添加描述 · API开发利器：Postman

Trello中描述支持markdown

How To Format Your Text in Trello - Trello Help

举例：

保存后的效果：

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 10:29:21

附录

下面列出相关参考资料。

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 09:22:47

参考资料

- 【简明版】有道云笔记Markdown指南 | 有道云笔记官方博客

- 【进阶版】有道云笔记Markdown指南 | 有道云笔记官方博客

- Markdown——入门指南 - 简书

- 25.io | Mou - Markdown editor for developers, on Mac OS X.

- Markdown编辑器语法指南 - SegmentFault

crifan.com，使用署名4.0国际(CC BY 4.0)协议发布 all right reserved，powered by Gitbook最后更新： 2018-07-03 10:30:34

Table of Contents

前言

Markdown简介

Markdown是什么

Markdown特点

Markdown能干什么

Markdown语法

Markdown心得和坑

Markdown编辑器

Markdown应用

成套成系统的工具

其他支持Markdown的工具

附录

参考资料