Markdown 实用教程¶

一、什么是 Markdown¶

Markdown 是一种轻量级的纯文本标记语言，用简单少量的符号对文字进行标注，从而实现以最小的输入代价生成印刷级排版格式的文档。它在流畅的书写和印刷级阅读体验之间找到了平衡，让人只需专注内容而不是纠结排版。

常用的标记符号 不超过十个，好记好用好效果。

二、Markdown 编辑器¶

Typora（Mac、Win、Linux），简约不简单，所见即所得；✓
MWeb（Mac、iOS），一款专注于 Markdown 的写作、记笔记和发布软件；
Obsidian（Mac、Win、Linux、iOS、Android），一款支持 Zettelkasten 笔记法的笔记管理软件，利用「双向链接」打造「知识循环」体系，支持基础的 markdown 语法；
YankNote（Mac、Win、Linux），一款强大可扩展的 Markdown 编辑器，满足了所有幻想，还可以在线体验；✓
mdx-notes（Mac、Win、Linux、Web），跨平台笔记软件，Web版在线编辑器可作为网文排版工具；
markdown-online-editor，Arya - 在线 Markdown 编辑器，支持所有基础语法、数学公式、Mermaid 图表、Echarts 图表、五线谱，以及 PPT 模式、视频音频解析等；✓
md，在线微信 Markdown 编辑器，支持所有基础语法、数学公式、Mermaid 图表、GFM 警告块；

使用推荐¶

日常工具使用：推荐 Typora、Arya - 在线 Markdown 编辑器；
用作网文排版：推荐 Arya - 在线 Markdown 编辑器，在线微信 Markdown 编辑器；
知识库笔记库：推荐 YankNote；
- Obsidian 的问题是对 HTML 的支持太弱了，比如 HTML 锚点链接识别不出来，另外导出功能也很弱，就支持一个PDF格式且还不带目录大纲；

使用和体验过不下二十款 Markdown 编辑器，从 简洁易用、基础功能完善、语法兼容、扩展性、跨平台 角度看，给大家以上建议，我自己的习惯是 Typora 和 YankNote 的组合，至少到 2024年是这样。

三、Markdown 实用语法¶

本教程基于流行的 CommonMark 规范和 GitHub Flavored Markdown (GFM) 语法拓展。

1. 标题¶

两种写法：

用 1-6 个 # 加空格，分别表示 1-6 级标题；
= 或 - 号，只能表示一二级标题，不常用；

# 一级标题
## 二级标题
#### 四级标题


这是一个一级标题
=====

这是一个二级标题
-----

2. 文字样式¶

Markdown 语法：

*斜体*    _斜体_
**粗体**    __粗体__
***加粗斜体***    ___加粗斜体___
~~删除线~~
<u>下划线</u>
<mark>背景高亮</mark>

斜体斜体
粗体粗体
加粗斜体 加粗斜体
~~删除线~~
下划线
背景高亮

3. 列表¶

无序列表¶

使用 - 或 + 或 * 加空格表示无序列表：

- 无序列表项 一
- 无序列表项 二
    - 无序列表
- 无序列表项 三

示例效果：

无序列表项一
无序列表项二
- 无序列表
无序列表项三

有序列表¶

使用 数字+点 加空格表示有序列表：

1. 有序列表项 一
2. 有序列表项 二
    1. 有序列表
3. 有序列表项 三

示例效果：

有序列表项一
有序列表项二
1. 有序列表
有序列表项三

4. 链接¶

使用 [描述](链接地址) ，为文字增加链接：

这是去往 [Apple](https://www.apple.com.cn) 的链接。

示例效果：

这是去往 Apple 的链接。

5. 图像¶

使用 ![描述](图片链接地址) 插入图像，图片链接地址可以是本地图片路径，也可以是网络图片url：

![网络图片](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkphgeh7nuvspognuhbo/douyin_web/img/images/logo-horizontal.svg)
![本地图片](file:///Users/aaron/Pictures/cat.jpg)
![本地图片](/Users/aaron/Pictures/cat.jpg)

示例效果：

6. 引用¶

使用 > 加空格表示引用，也可以多个组合：

> 野火烧不尽，春风吹又生。
> > 春风吹又生

示例效果：

野火烧不尽，春风吹又生。

春风吹又生

7. 代码片¶

使用一个反引号 ` 前后包围的方式表示代码片段：

让我们聊聊 `html`。

示例效果：

让我们聊聊 html。

8. 代码块¶

使用三个反引号 ``` 上下包围的方式表示代码块。后面跟编程语言可以支持语法高亮显示，支持所有主流编程语言。

JavaScript 示例：

```javascript
function myFunction(a, b) {
    return a * b;
}
myFunction(10, 2); 
```

示例效果：

function myFunction(a, b) {
    return a * b;
}
myFunction(10, 2);

9. 分割线¶

可以在一行中用 3 个以上的 - 或 * 或 _ 来建立一个分隔线：

Markdown 语法：

---
- - -
***

示例效果：

10. 表格¶

Markdown 语法：

| 项目(左对齐) | 价格(居中) | 数量(右对齐) |
| :--- | :---: | ---: |
| 计算机 | 1600 | 5 |
| 手机 | 12 | 12 |
| 管线 | 1 | 234 |

示例效果：

项目(左对齐)	价格(居中)	数量(右对齐)
计算机	1600	5
手机	12	12
管线	1	234

11. 复选框¶

Markdown 语法：

- [x] 支持 导出 HTML、PDF、ePub、Word 等；
- [x] 支持 高亮代码段；
- [x] 支持 数学公式；
- [x] 支持 幻灯片；
- [x] 支持 思维导图；
- [x] 支持 流程图、序列图、甘特图和各类图表；
- [ ] 任务一，未做任务；
    - [ ] 子任务；

示例效果：

支持导出 HTML、PDF、ePub、Word 等；
支持高亮代码段；
支持数学公式；
支持幻灯片；
支持思维导图；
支持流程图、序列图、甘特图和各类图表；
任务一，未做任务；
- 子任务；

12. 文档目录¶

使用 [TOC] 会自动提取全文标题，生成目录结构。字母用大小写都可以。

13. 脚注¶

标准语法为 [^keyword]，keyword随意，保证唯一就行。

Markdown 语法：

Markdown到底是什么？[^ftnt]

[^ftnt]: Markdown 是一种方便记忆、书写的纯文本标记语言，用户可以使用这些标记符号以最小的输入代价生成极富表现力的文档。

示例效果：

Markdown到底是什么？¹

普通用户到此，足够了。

四、HTML 扩展¶

Markdown 兼容 HTML 标签，可以和 HTML 混编来拓展更多实用功能。使用参考 Typora 文档 HTML Support 和 HTML 元素参考。

布局容器：

行内元素：<span>、 <a>、 <br> 等，表示一行中一小段内容；
块级元素：<div>、<section>、<p>、<pre>、<h1> ~ <h6> 等，表示一块内容区域；
行内块元素：<img>、<input> 等，既有行内元素特点，也有块元素特点；

1. 文字样式¶

使用 <span style="color:red">红色文字</span> 设置红色文字。

2. 图像样式¶

使用 <img> 标签来显示图片，然后在标签中设置样式。

修改大小：

<img src="url" width="200px" height="100px" />
<img src="url" style="width:200px; height:100px;" />
<img src="url" style="zoom:50%;" />

对齐方式：

<!-- 缩放50%且对齐左边 -->

<div style="text-align: left;">
<img src="https://www.w3cschool.cn/attachments/image/20170526/1495798408306247.jpg" 
     style="zoom:50%;" />
</div>

3. 多列布局¶

使用 <div> 多层嵌套，然后再设置其 CSS 属性。

第1列
- Bullet
Bullet
Bullet

第2列
1. List
List
List

YankNote、MWeb、MiaoYan 均支持多列布局渲染。Typora 不支持，但可导出 HTML 正常显示。

详细教程，参考另一篇文档 CSS排版布局。

4. 表格技巧¶

4.1 表格中换行¶

可用 <br /> 标签。

示例代码：

| Header1 | Header2 |
| --- | --- |
| item 1 | 1\. one<br /> 2\. two<br /> 3\. three |

示例效果：

Header1	Header2
item 1	1. one 2. two 3. three

4.2 多列表格简写¶

另外多列表格的表示方式还可以简写。

示例代码：

Header1 | Header2
--- | ---
item 1 | 1\. one
item 2 | 2\. two

示例效果：

Header1	Header2
item 1	1. one
item 2	2. two

5. 任意跳转¶

设置锚点：在目标位置添加空的 <span> 或 <a> 标签；
链接锚点：使用 [显示文字](#锚点id) 格式设置锚点链接；

示例代码：

<span id="simplification"></span>  <!-- 添加在目标位置 -->
<a id="newline"></a>

点击跳转 [表格中换行](#newline)。    <!-- 设置在链接点击的发起位置 -->
点击跳转 [多列表格简写](#simplification)。

示例效果：

点击跳转表格中换行。
点击跳转多列表格简写。

6. 视频音频¶

使用 <video> 和 <audio> 标签：

<video style="width:100%;" controls>
  <source src="file:///Users/aaron/Movies/明日边缘.mp4"  type="video/mp4">
</video>

<audio controls style="width:100%;" >
  <source src="file:///Users/aaron/Music/最伟大的作品 - 周杰伦.mp3" type="audio/mpeg">
</audio>

7. iframe 嵌入¶

示例代码：

<iframe height="300" style="width: 100%;" scrolling="no" title="multi-column-layout" src="https://codepen.io/aaronwang30/embed/yyBBpdg?default-tab=css%2Cresult" frameborder="no" allowtransparency="true" allowfullscreen="true"></iframe>

示例效果：

五、编辑器特性¶

各编辑器都扩展了一些除标准 Markdown 规范之外的独有特性，这里分别罗列一些实用的。

1. Emoji 表情¶

使用 emoji 简码（编辑器特性）。详情参考 Emoji 简码表。
用 :smile: 表示
使用 UTF-8 字符集（HTML 扩展）。详情参考 Emoji Unicode 参考手册。
十进制：用 😄 表示 😄
十六进制：用 😄 表示 😄

更多 emoji 简码参考：emoojees、emoji-cheat-sheet。

2. 标题跳转¶

部分编辑器会自动生成标题锚点，然后使用 [显示文字](#标题) 直接链接标题，相比前面的任意跳转，不再需要设置锚点。

如果标题重复，则添加从 1 开始的编号后缀，例如用 [显示文字](#标题-1) 表示第一个，以此类推；
如果标题中含空格，则用 - 代替；

3. YAML 前言¶

YAML：一种更简洁更易读写的数据序列化语言，通常用于编写配置文件。具体介绍看什么是 YAML，语法参考：YAML 入门教程。
YAML Front Matter：头信息，一种在文件顶部使用 YAML 语法定义变量的方式，通常用于为 Markdown 或 HTML 添加元数据、控制布局、定义版本等。

语法：必须在文章最顶部用3虚线 --- 前后包围的形式声明。

---
title: Markdown实用教程
author: 汪鸿俊
---

4. 富文本转换¶

Markdown 本质还是 HTML，可以和 HTML 互相转换。这样可以在其它任意地方使用带样式的 Markdown 内容，也可以把其它网页内容粘贴为 Markdown 文本，非常方便。

HTML → Markdown：Typora、YankNote 都支持把复制的网页内容粘贴为富文本；
Markdown → HTML：Typora 还可以把当前内容复制为 HTML；

5. 导出文档¶

大部分编辑器支持导出 PDF、HTML、Image 格式文档，借助 Pandoc 还可以导出 Word、Epub、RTF、Jupyter Notebook 等几乎所有常用格式文档。

Typora 的导出功能最全面，使用参考 Typora Export。

6. YankNote 特性¶

单独讲一下 YankNote，因为好用的太多了。

增强 TOC¶

大部分编辑器都支持使用 [TOC] 自动生成文档目录。YankNote 还可设置列表方式和目录层级。

<!-- 常规写法（根据标题自动生成目录） -->
[toc] 

<!-- YankNote写法（ul无序，ol有序，[2,3]表示：只显示2和3级标题） -->
[toc]{type: "ul", level: [2,3]}

列表转脑图¶

只需在「列表」的根节点后加上 {.mindmap} 即可。

<!-- 列表写法 +-* 都可以，[1]只表示数字图标（可选），不是顺序 -->
+ 中心节点{.mindmap}
    + [1] 状态可见原则
    + [2] 环境贴切原则
    + [3] 用户可控原则
    + [4] 一致性原则

此外，还支持一堆的其它图表嵌入，还有直接运行代码片段、HTML小程序、AI 助手、版本控制、宏替换、文档加密等功能。

六、数理公式¶

排版与渲染¶

计算机中，通常用 LaTeX、MathML 或 AsciiMath 标记语言来编写数理公式，用 MathJax 或 KaTeX 渲染引擎来显示这些公式。

TeX，计算机排版系统，在学术界十分流行，特别是数学、物理学、统计学与计算机科学。
LaTeX，基于ΤeΧ的排版系统，支持复杂数学公式的编写。详情参考：LaTeX 基础教程。
MathML，基于XML的数学标记语言。使用参考：使用 MathML 编写数学公式。
AsciiMath，基于ASCII字符的易于编写的数学标记语言。兼顾表现力和可读性，没有LaTeX中反斜杠。参考：AsciiMath 教程。
MathJax，支持 TeX/LaTeX、MathML 和 AsciiMath 等标记语言的 JS 渲染引擎，功能全面，兼容性好。
KaTeX，另一个 JS 渲染引擎，渲染速度快。

1. 数学公式¶

使用 Tex/LaTeX 编写数学公式，语法参考：Math and Academic Functions 。不过，即使有语法参考，编写起来也很费劲，这时，可用以下编辑神器：

MyScript Math：支持手写数学公式，自动转 LaTeX 或 MathML，MyScript 此外还有集成手写框架 iinkTS 及 iOS、Android 手写计算器 Calculator，好评如潮，图标是 $\sqrt{3}$ 。
SimpleTex：好用的公式识别编辑神器，提供跨平台客户端和在线体验供使用。
- 支持手写、截屏截图、PDF文件的公式识别。
- 支持80+语言识别、各种类型的复杂公式、化学结构式识别。
- 支持识别后在结果上直接编辑，支持常见 LaTeX 命令补全。
- 识别结果支持 Markdown 或 LaTeX 格式。

内联公式¶

使用 $ 前后包围方式。

用 $E=mc^2$ 表示：$E=mc^2$
用 $\sum_{i=1}^n a_i=0$ 表示：$\sum_{i=1}^n a_i=0$

块级公式¶

使用 $$ 前后包围的方式。

用 $$ \displaystyle x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$ 表示：

\[ \displaystyle x = {-b \pm \sqrt{b^2-4ac} \over 2a} \]

用 $$ f(x_1,x_x,\ldots,x_n) = x_1^2 + x_2^2 + \cdots + x_n^2 $$ 表示：

\[ f(x_1,x_x,\ldots,x_n) = x_1^2 + x_2^2 + \cdots + x_n^2 \]

2. 化学方程式¶

通过 mhchem 扩展实现，支持 MathJax 和 KaTeX。

用 $$ \ce{CH4 + 2 $\left( \ce{O2 + 79/21 N2} \right)$} $$ 表示：

\[ \ce{CH4 + 2 $\left( \ce{O2 + 79/21 N2} \right)$} \]

3. 更多公式¶

七、图形与图表¶

使用 Markdown 快速生成各类图形与图表，参考另一篇文档 Markdown 图形与图表。

八、静态网站¶

使用 Markdown 快速生成静态网站，参考另一篇文档 Markdown 静态网站。

九、幻灯片¶

使用 Markdown 快速生成精美幻灯片，参考另一篇文档 Markdown 幻灯片。

Markdown 是一种方便记忆、书写的纯文本标记语言，用户可以使用这些标记符号以最小的输入代价生成极富表现力的文档。 ↩

Markdown 实用教程¶

一、什么是 Markdown¶

二、Markdown 编辑器¶

使用推荐¶

三、Markdown 实用语法¶

1. 标题¶

2. 文字样式¶

3. 列表¶

无序列表¶

有序列表¶

4. 链接¶

5. 图像¶

6. 引用¶

7. 代码片¶

8. 代码块¶

9. 分割线¶

10. 表格¶

11. 复选框¶

12. 文档目录¶

13. 脚注¶

四、HTML 扩展¶

1. 文字样式¶

2. 图像样式¶

3. 多列布局¶

4. 表格技巧¶

4.1 表格中换行¶

4.2 多列表格简写¶

5. 任意跳转¶

6. 视频音频¶

7. iframe 嵌入¶

五、编辑器特性¶

1. Emoji 表情¶

2. 标题跳转¶

3. YAML 前言¶

4. 富文本转换¶

5. 导出文档¶

6. YankNote 特性¶

增强 TOC¶

列表转脑图¶

六、数理公式¶

排版与渲染¶

1. 数学公式¶

内联公式¶

块级公式¶

2. 化学方程式¶

3. 更多公式¶

七、图形与图表¶

八、静态网站¶

九、幻灯片¶

评论