目录

前言 1.1

Markdown简介 1.2

Markdown是什么 1.2.1

Markdown特点 1.2.2

Markdown能干什么 1.2.3

Markdown语法 1.3

Markdown心得和坑 1.4

Markdown编辑器 1.5

Markdown应用 1.6

成套成系统的工具 1.6.1

其他支持Markdown的工具 1.6.2

附录 1.7

参考资料 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简介

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

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

Markdown是什么

Markdown是什么

Markdown术语上叫做：标记语言

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

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

Markdown特点

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能干什么？

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语法

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心得和坑

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编辑器

各种编辑器支持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有如此多的优点，所以大家愿意使用。

现在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的工具

其他支持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