Markdown简明教程

最新推荐文章于 2025-06-12 16:50:03 发布

warp_drive

最新推荐文章于 2025-06-12 16:50:03 发布

阅读量6.4k

点赞数

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/pxzy/article/details/22045059

markdown 同时被 3 个专栏收录

1 篇文章

订阅专栏

教程

1 篇文章

订阅专栏

1 篇文章

订阅专栏

Markdown是什么

Markdown是一种轻量级标记语言，它允许人们“使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML(或者HTML)文档”。

作者：约翰.格鲁伯 (John Gruber)，这里是他博客上有关Markdown语法的文章

author1

作者：亚伦.斯沃兹 (Aaron Swartz) (已故)

author1

为什么使用Markdown

很多人在用，各大主要实现的开源工程非常活跃。
简洁，提高文档撰写效率。
只与文档内容有关，与文档样式无关，便于调整样式。
基于纯文本格式，便于搜索。
有丰富的解释器或工具支持。

标准语法

强调

斜体

    *斜体*

    _斜体_

粗体

    **粗体**

    __粗体__

换行

在行末输入两个空格然后回车即可实现文本的强制换行。

标题

标题演示

    主标题
    -

    主标题
    ----------

    主标题
    =

    主标题
    ==========

    # H1标题

    ## H2标题

    ### H3标题

    #### H4标题

    ##### H5标题

    ###### H6标题

数字列表

    1. 红

    2. 黄

    3. 蓝

    2. 红

    1. 黄

    3. 蓝

符号列表

    * 红

    * 黄

    * 蓝

    + 红

    + 黄

    + 蓝

    - 红

    - 黄

    - 蓝

层级式列表

颜色
1. 红
  - 紫红
  - 橘红
2. 黄
3. 蓝
  - 暗蓝
  - 亮蓝
  - 孔雀蓝

    * 颜色

      1. 红

        + 紫红

        + 橘红

      2. 黄

      3. 蓝

        - 暗蓝

        - 亮蓝

        - 孔雀蓝

引用

这是一段引用文本

    > 这是一段引用文本

这是一段引用文本

嵌套引用文本

嵌套引用文本

    > 这是一段引用文本
    >> 嵌套引用文本
    >>> 嵌套引用文本

水平分割线

三个或更多*号为分割线

***

---

代码段

使用一个反单引号可以生成一个行内代码块

`行内代码块`

行起始为4个空格或1个Tab占位符则后续文本将被识别为代码段

//代码段演示
function aaa(){
    alert("一段javascript代码");
}

图片

演示无效图片

![演示无效图片](http:// "无效图片")

演示本地路径图片

![演示本地路径图片](./imgs/admin.png '本地路径图片')

演示远程路径图片

![演示远程路径图片](https://i-blog.csdnimg.cn/blog_migrate/afbae5311a5cf0332c10df7a7483970e.gif "远程路径图片")

演示参考链接图片

![演示参考链接图片][002]
[002]: https://img-blog.youkuaiyun.com/20140325110441140?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvcHh6eQ==/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/SouthEast "参考链接图片"

链接

内联样式链接

[内联样式链接](http://example.com "提示文本")

参考样式链接描述文本A

参考样式链接描述文本B

[参考样式链接描述文本A][001]

[参考样式链接描述文本B][001]

[001]: http://about:blank "提示文本"

或

[001]: http://about:blank '提示文本'

或

[001]: http://about:blank (提示文本)

内联HTML标记

在MD文档里，你可以插入原生HTML标记，如：

一段红色文本

<font color='red' style='font-size:20pt'>一段红色文本</font>

第一列	第二列
第一行	文本1
第一行	文本2

<table>
    <thead>
        <tr>
            <th>第一列</th>
            <th>第二列</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>第一行</td>
            <td>文本1</td>
        </tr>
        <tr>
            <td>第二行</td>
            <td>文本2</td>
        </tr>
    </tbody>
</table>

Python-Markdown常用扩展

目录（toc）

功能

此插件可以在文档内根据标题自动生成目录。
用法

在文档起始处放置[toc]或者[TOC]标记即可让解析器自动生成目录。

表格（tables）

功能

在文档里通过简单标记插入表格。
用法

Markdown对表格的支持比较简陋，但可以满足一般的简单表格的展现需求。

注意：Markdown原生就支持内联HTML标记，因此，你也可以通过内联HTML的TABLE标记将表格插入到文档内。

例子

第一列	第二列	第三列	第四列
第一行	文本二	文本三	文本四
第二行	文本二	文本三	文本四

第一列 | 第二列 | 第三列 | 第四列  
----- | ----- | ----- | -----  
第一行 | 文本二 | 文本三 | 文本四  
第二行 | 文本二 | 文本三 | 文本四

第一列	第二列	第三列	第四列	第五列	第六列	第七列	第八列
第一行	文本二	文本三	跨两列文本	文本六	文本七	文本八
第二行	文本二	文本三	这是一段长文本	文本五	文本六	文本七	文本八

第一列 | 第二列 | 第三列 | 第四列 | 第五列 | 第六列 | 第七列 | 第八列  
----- | ----- | ----- | ----- | ----- | ----- | ----- | -----  
第一行 | _文本二_ | 文本三 | **跨两列文本** | 文本六 | 文本七 | 文本八  
第二行 | 文本二 | 文本三 | 这是一段<br/>长文本 | 文本五 | <font color='green'>文本六</font> | 文本七 | 文本八

注意：由上面这个表格可知 tables 的表格不支持合并单元格！

公式（mathjax）

功能

在文档中通过 MathJax 标记插入公式。
用法

此插件基于开源公式显示引擎 MathJax (语法为类LaTex标记语言，最终输出W3C的MathML标记语言)
例子

可以支持像 $\frac{\pi}{2}$ $\pi$ 这样的内联公式。

markdown 可以支持像 \$\frac{\pi}{2}\$ $\pi$ 这样的内联公式。

也可以是非内联的，如：

$$F(\omega) = \frac{1}{\sqrt{2\pi}} \int_{-\infty}^{\infty} f(t) \, e^{ - i \omega t}dt$$

\[\int_0^1 f(t) \mathrm{d}t\]

\[\sum_j \gamma_j^2/d_j\]

```markdown

$$F(\omega) = \frac{1}{\sqrt{2\pi}} \int_{-\infty}^{\infty} f(t) \, e^{ - i \omega t}dt$$
```
\\[\int_0^1 f(t) \mathrm{d}t\\]

\\[\sum_j \gamma_j^2/d_j\\]
```
```

注意： MathJax 一般都需要访问网络，因此保证网络畅通才能正常显示。大多数流行的浏览器都支持MathJax 。MathJax的语法是类LaTex语法，标记繁多而复杂，不便于记忆。

指定标题ID（headerid）

功能

在大型文档系统里，一般都有内容跳转功能，这种跳转通过链接实现，并且此功能必须基于设置在DOM元素上的id属性才能完成。这个扩展就能够指定某个标题的id属性。
用法

你需要在要设置id属性的标题文本后加上#{#id-attr-value}，其中id-attr-value是id属性的值:
例子

跳转到“常用扩展”章节

    [跳转到“常用扩展”章节][self-md-ext]

    [self-md-ext]: #md-ext

GitHub特性标记

注意：大多数MD解析器现在都支持全部或部分GitHub特性标记，但是在使用它们之前请还是要先确定一下是否支持！

代码段

与标准标记不同，GitHub风格的MD代码段是以两组三个连续的反单引号标记来标识，并且在第一组三个反单引号之后可以紧跟指定的代码语言名称，如：

javascript代码段定义：

```js
function aaa(){
    alert("一个javascript代码段");
}
```

Python代码段定义：

```python
import random
class CardGame(object):
    """ a sample python class """
    NB_CARDS = 32
    def __init__(self, cards=5):
        self.cards = random.sample(range(self.NB_CARDS), 5)
        print 'ready to play'
```

小图标

GitHub风格的MD标记可以让你将一些预置的小图标加入到文档内。

:+1: :heart: :beer:

:+1: :heart: :beer:

注意：所有这些图标资源都放在GitHub的服务器上而不是本地！解析器生成的HTML链接也是指向GitHub的服务器！

其他特性

更多GitHub特性Markdown语法请看这里

最佳实践

尽量不要在MD文档内使用内联HTML标记，增强兼容性。
将所有的参考式链接(包括图片参考链接)定义在MD文档的最后，便于维护。
尽量使用标准语法，少用或不用不流行的扩展语法或特性语法。
不要在一个MD文档内写非常多的内容，应该根据实际情况将内容分割到多个文件内，然后通过定义id属性值和链接来进行跳转。

Markdown编辑器

Sublime Text （win/linux/mac）官网

安装Markdown Preview插件后即可很好的支持Markdown文件的编辑和预览、转换。
特点：
- 基于Python-Markdown解析器。
- 语法高亮。
- 丰富的文本编辑功能。
- 自带简明语法手册(Cheat sheet)，能够给新手快捷指引。
- 支持GitHub特性语法。
- 支持HTML的导出和复制到剪贴板功能。
- 支持常用的一些扩展（需要修改默认配置）。
- 支持HTML模板。
- 支持自定义样式。
缺点：
- 不能导出除CSS以外的纯HTML标记代码段（需要手工复制）。
- Sublime Text 2/3在linux下的中文输入存在问题（一个bug）。
- 不支持实时预览，但可以先选择在浏览器中预览然后在文档修改后在浏览器中按F5刷新页面显示的方法来实现类似实时预览的功能。
reText（win/linux）官网

它是一个开源专业Markdown文档编辑器（同时也支持reStructuredText标记语言），一般在linux下使用。
特点：
- 语法高亮
- 支持GitHub特性语法。
- 生成的HTML文档中的样式为外部样式（即：使用）
- 支持导出HTML、PDF和ODT格式文件。
- 支持HTML模板。
- 支持自定义样式。
- 支持实时预览。
缺点：
- 在windows环境下难以安装（需要手动安装一大堆东西）。
- 不能导出除CSS以外的纯HTML标记代码段（需要手工复制）。
MarkdownPad（win）官网

是一款专业MD编辑器。
特点：
- 语法高亮。
- 支持GitHub特性语法。
- 支持导出HTML和PDF文件。
- 支持自定义样式。
- 支持实时预览。
- 离线支持GitHub风格MD标记
缺点：
- 商业软件，没有购买之前有功能限制。
- 没有HTML模板定制功能。
haroopad（win/linux/mac）官网

韩国人开发的一款新一代MD编辑器，很有潜力的MD编辑器。
特点：
- 基于Chromium开发。
- 语法高亮。
- 支持GitHub特性语法。
- 生成的HTML文档中的样式为外部样式（即：使用）。
- 支持导出除CSS以外的纯HTML标记代码段。
- 具有简洁的MD语法导航边栏。
- 支持导出HTML文件。
- 支持将解析出的内容作为邮件发送。
- 支持自定义样式。
- 支持实时预览。
- 支持编辑区与预览区域的同步滚动。
- 支持语法检测，在有问题的标记文本下面将显示红色波浪线。
- 支持VIM编辑模式。
- 与社交平台集成。
缺点：
- 当前还处在Beta测试阶段，功能不够稳定。
- 没有HTML模板定制功能。