Markdown Syntax

一、Markdown 概述

设计理念

Markdown 易于阅读，方便创作 Web 文档，利于各平台无缝分发。
Markdown 语法灵感最大的来源还是纯文本 email 的格式，完全由标点符号标签组成的纯文本。
Markdown 文件应该以纯文本形式原样发布，不应该包含标记标签和格式化指令。

内联 HTML 语法

HTML 是一种发布格式，Markdown 是一种创作格式。
Markdown 语法集合比较小，只是 HTML 标签的一小部分。
对于 Markdown 中未包含的标签, 可以直接使用 HTML 标签，例如用 HTML <a> 标签替代 Markdown 的链接语法。

特殊字符自动转义

在 HTML 中, 有两个字符需要特殊对待: < 和 &，左尖括号用于起始标签。果你想将它们用作字面量, 你必须将它们转义为字符实体, 例如 < 和 & 左尖括号用于起始标签。果你想将它们用作字面量

二、语法分类

1.基础语法 (Basic Syntax)：由 John Gruber 所定义的语法
2.扩展语法 (Extended Syntax)：由第三方定义，且被大多数编辑器所引入的语法
3.方言：仅在特定软件中生效的语法

因为现在常用的编辑器都支持了扩展语法 (特别是 GitHub 定义的 GFM)，所以真正需要区分的只有少部分方言
后文也不再对基础语法和扩展语法进行区分
由于我自己主要就用那么一两个软件，方言这块知道的不多，见谅
建议尽可能不使用方言，要考虑文档迁移时的兼容性

元素分类

元素：组成文章的各个部分，包括语法符号和文字内容

1.块级元素 (Blocks)

* 容器块 (Container blocks)
    * 引用 (block quotes)
    * 列表 (list)
        * 有序列表 (unordered list, ul)
        * 无序列表 (ordered list, ol)
        * 任务列表 (task list, to do list, 扩展语法)
* 子叶块 (Leaf blocks)
    * 分割线 (thematic breaks)
    * 标题 (heading)
        * ATX heading
        * Setext heading
        * TOC (目录，属于方言)
    * 代码块 (code bolcks)
        * Indented
        * Fenced
            * 语法高亮 (highlight)
            * 画流程图，时序图等 (可能需要插件)
    * 表格 (tables，部分属于扩展语法)
    * HTML 块 (HTML blocks)
    * LaTeX 数学公式 (`$公式$` 可能需要插件)

2.行级元素 (Inlines)

* 逃逸 / 转义字符 (backslash escapes)
* 行内代码 / 代码区 (code spans)
* 严格换行 (line breaks)
* 字体效果
    * 斜体 (emphasis)
    * 粗体 (strong)
    * 粗斜体 (strong emphasis)
    * 删除线 (strikethrough，扩展语法)
    * 下划线 (md 没有，用 html)
    * 键盘文本 (md 没有，用 html)
    * 居中 (md 没有，用 html)
    * 高亮强调 (属于方言)
* HTML 实体字符
* LaTeX 数学公式 (`$公式$` 可能需要插件)
* emoji 表情 (可能需要插件)
* 链接 (links)
* 图片 (images)
* 音频 (用 html)
* 视频 (用 html)
* 角标注释 (扩展语法)
* 标题 ID 及跳转 (扩展语法)

优先级

容器块 > 子叶块 > 行级元素

这是元素分类的依据
容器块可包含所有类型的元素
- 于容器块，列表和引用可以多级嵌套，列表里面可以套引用，引用里面也可以有列表
- 于子叶块，可以在引用里加表格，在列表里放代码块
子叶块不可以包含块级元素，比如标题里面可以放链接，但不可以放列表
块级元素里可以放行级元素，比如在表格里加粗某几个字，但这并不是绝对的，比如在代码块中和 HTML 块中的 md 语法会失效

插件

如上可以看出，Markdown 的文本里可以放置 HTML 和 LaTeX 的语法，这是其他语法手册杂糅现象的重灾区。在 Obsidian 中可以直接使用部分非 md 的语法，但在 hexo 中则大多需要添加插件，如 MathJax (渲染 LaTeX)、Mermaid (画功能图)。具体应用具体场景具体分析，本文的重点在于 md 的语法，不涉及插件的安装等琐细事情

Markdown 与 HTML

https://www.markdownguide.org/getting-started/#how-does-it-work

无论是 md 语法，LaTeX 公式还是各类图的语法，都会最终被解释成 HTML 格式
md 文件可以渲染成静态页面 (用于博客)，也可以导出为 PDF，甚至是 PPT
md 与 HTML 的定位不同，前者用于书写，其源文件就足够可读，后者则用于发表

三、容器块：引用，列表

引用

1	> 语法：大于号的后面加个空格

语法：大于号的后面加个空格

多行

> 多行
> 引用

中间断开视为多个引用

> 段内换行时 
> 
> 加一行空白引用即可

> 或者
偷懒
> 
> 换行同上

多行
引用

中间断开视为多个引用

段内换行时

加一行空白引用即可

或者
偷懒

换行同上

多重

> 多重
> > 引用
> >
> > > 套娃
> >
>
> > 需要在两层之间
> 多加一行空白
>
> 才能结束套娃

多重

引用

套娃

需要在两层之间
多加一行空白

才能结束套娃

嵌套

> * 嵌套列表时 
* 可能会  
* 偷不了懒

> * 还是得
> * 写全语法

嵌套列表时

可能会
偷不了懒

还是得

写全语法

建议：不用偷懒的写法，多打几个符号而已

列表

无序列表

语法：* + - 后加空格
渲染后的效果是相同

* a
* b

+ a
+ b

- a
- b

+ 嵌套列表时
  - 子层前加两三个空格缩进即可
  - 要回到上级列表则去掉空格
+ 也就是这样
+ 列表同引用
  - 可以
    * 多重
      + 嵌套

嵌套列表时
- 子层前加两三个空格缩进即可
- 要回到上级列表则去掉空格
也就是这样
列表同引用
- 可以
  - 多重
    - 嵌套

md 有多个无序列表符具有明显的好
在同层级的列表项前用统一的符号
在嵌套里用不同的符
即增加了可读性，也使得渲染不易出错

有序列表

1
2
3

语法：数字+句号+空格
1. 第一项
2. 第二项

第一项
第二项

* 无序列表
  1. 和有序列表间
  2. 可相互嵌套
     - 效果如下 
     - > 还有引用

无序列表
1. 和有序列表间
2. 可相互嵌套
  - 效果如下
  - 还有引用

100. 列表的第一项可以是任意自然数
01. 不考虑那该死的溢出
123. 后面的数字会自动顺延
103. 所以第一项的序数很重要

0. 以0为起始也是可以的

-1. 但是负数不行，减号会渲染失
1/2. 分数也不行，因为有个斜杠

10) 还有这种写法`10)`，但是不推荐
11) 属于Typora支持的方言
12) 且括号本身是个容易导致渲染出错的危险符号

列表的第一项可以是任意自然数
不考虑那该死的溢出
后面的数字会自动顺延
所以第一项的序数很重要
以0为起始也是可以的

-1. 但是负数不行，减号会渲染失败
1/2. 分数也不行，因为有个斜杠

10). 还有这种写法10)，但是不推荐
11). 属于 Typora 支持的方言
12). 且括号本身是个容易导致渲染出错的危险符号

尽量以 1 为起始，顺延的数字也按顺序填正确；不使用方言写法

任务列表

1 2	- [ ] 减号+空格+方括号+空格 - [x] 方括号里，空格为未填充，x为已填充

减号+空格+方括号+空格
方括号里，空格为未填充，x为已填充

1
2
3

任务列表的嵌套同上
  - [ ] > to do
  - [x] have done

任务列表的嵌套同上

to do
have done

四、子叶块：分割线、标题、代码块、功能图、表格

分割线

语法：3个或以上的"_","-","*"单独成行
___
---
***

标题

|Markdown|渲染效果|
|:--|:--|
|# H1|<h1>这是一级标题</h1>|
|## H2|<h2>切记#后面要有空格</h2>|
|### H3 ##|<h3>标题后的#会被隐藏</h3>|
|###### H6|<h6>最多支持六级标题</h6>|

Markdown	渲染效果
# H1	这是一级标题
## H2	切记#后面要有空格
### H3 ##	标题后的#会被隐藏
###### H6	最多支持六级标题

Setext

|Markdown|渲染效果|
|:--|:--|
|H1<br>\=|<h1>紧跟一行1个或以上的等号</h1>|
|H2<br>\-|<h2>用减号，最多支持二级标题</h2>|

Markdown	渲染效果
H1 =	紧跟一行1个或以上的等号
H2 -	用减号，最多支持二级标题

建议：用 ATX 格式的标题
首先是它支持到了 H6，而 Setext 仅支持到 H2，一般是不够用的
其次是 Setext 中，另起一行紧跟 — 是 H2，不紧跟就成了下划线，容易出错

目录(方言)

1	语法：[TOC]，某些解析支持用它将目录自动列出来

代码块

在代码块中，所有语法都不会被渲染，它会展现出最原本的形式

Indented

缩进形式的代码块，在最左边打四个空格
    #include<stdio.h>
    int main() {
        printf("Hello World !");
	    return 0;
	}

#include<stdio.h>
int main() {
    printf("Hello World !");
    return 0;
}

Fenced

围栏形式的代码块，在上下各起一行打3个`或者~
	```c
	#include<stdio.h>
	int main() {
	    printf("Hello World !");
	    return 0;
	}


```c
#include<stdio.h>
int main() {
    printf("```");
    return 0;
}

语法高亮

这是 Fenced 形式的代码块独有的功能，如上，c 可换成 html、java 等
如无需高亮，或语言不被支持 (如 AT&T 格式的汇编)，可不填或者填 none、txt

功能图

这又是 Fenced 形式的代码块独有的功能，如若把上例的 c 换成 mermaid ，则可用 mermaid 的语法画流程图，换成 seq 可以画序列图。这里涉及到了其他语法，不拓展

```mermaid
graph TD;
A((1));B((2));C((3));
A-->B;A-->C;


```mermaid
graph TD;
A((1));B((2));C((3));
A-->B;A-->C;

建议

4 空格缩进式的代码块 (indented) 也有其优点，如在一些主题下没有代码框，更简洁

尽量用 ` 号而不用～号，也尽量不要嵌套代码块，因为后者可能和行级元素的删除线冲突

留意：md 不支持 tab 键，tab 会被解释成 1 个空格，所以在打代码时要将 tab 转化为 4 个空格 (Obsidian 中可以开启设置自动转化)，或者在主题样式 (如 styles.styl) 中自定义 pre {tab-size: 4;}

如果会用画图的语法，那可太好了，比起用其他软件生成图片后再插入到文档中，方便非常多，文件更小，可迁移性也更高

表格

一般简单表格

这是最简单的表格  

|表头|最上面的字体|会稍微有点不一样|
|--|--|---|
|最上面那行确定了列数|中间的减号个数不限|表身多余的竖线会被无视||
|最左边的行数|确定了整个表的行数|
|表格会被自动补全|

表头	最上面的字体	会稍微有点不一样
最上面那行确定了列数	中间的减号个数不限	表身多余的竖线会被无视
最左边的行数	确定了整个表的行数
表格会被自动补全

这是控制了各列内容对齐方式的表格  

|默认|左对齐|居中|右对齐|
|--|:--|:--:|--:|
|仅有减号|冒号在左边|冒号在两边|冒号在右边|
|A|B|C|D|

默认	左对齐	居中	右对齐
仅有减号	冒号在左边	冒号在两边	冒号在右边
A	B	C	D

这是 md 语法唯一能支持的表格形式，方便但有限
更复杂的，比如合并某些框框，将表头设置在左侧，就得通过其他的手段来实现了
各个表格的宽度是以各列中最长的那个为准的，竖线不需要手动对齐；如果有闲情，还是对齐为好，为了 md 源文件的可读性

更复杂的表格

前文提到，md 最终会被解释成 html，所以可以直接在 md 文件中添加 html 的语句，同样，借助软件或插件，也可以添加 LaTeX 的部分语句

可以看看这个网站，用 HTML 或者 LaTeX 定制表格，不多介绍。若还是不合心意，可用其他软件生成后，导出为图片，再插入到 md 中

关于 LaTeX

四个 $ 之间添加的是 LaTeX 的公式，它会自动单独成段，居中对齐

$$\begin{split}H_n
&= 1+\dfrac{1}{2}+\dfrac{1}{3}+\dfrac{1}{4}+\cdots+\dfrac{1}{n}\\
&= \sum_{k=1}^{n}\dfrac{1}{k}\\
&= \ln{n}+O(1)
\end{split}$$

$$\begin{split}H_n
&= 1+\dfrac{1}{2}+\dfrac{1}{3}+\dfrac{1}{4}+\cdots+\dfrac{1}{n}\
&= \sum_{k=1}^{n}\dfrac{1}{k}\
&= \ln{n}+O(1)
\end{split}$$

两个 $ 之间的属于行级元素

1	即可以放在行内的式子，如$a^2+b^2$=$c^2$

即可以放在行内的式子，如$a^2+b^2$=$c^2$

关于 HTML

一般来说，如 <code> 等带尖括号的标签，和带 &; 的实体符号，属于 html

五、行级：转义字符、行内代码、换行、字体、表情、公式

转义字符

语法：\，反斜杠 + 要转义的字符

转义字符可太常用了
如果想打 *，则需要 \*，以防渲染出错
如果在表格中需要用到 |，则可以 \|

行内代码

语法	markdown	渲染效果
两个重音符 '	`code` or `word`	code or word

没有代码高亮，可以单纯地用它来强调某个词

换行

Markdown 源文本的行数和渲染后的页面所显示的行数往往是不一样的，这里就涉及到了换行的问题

段内换行

若在源文本的文字末尾直接回车，仅是在 md 文件中换行，而渲染后的页面中不是显示换行，而是显示 1 个空格
若在文字末尾 + 两个空格 + 回车，即软换行，在渲染后的页面中成功换行
若在文字中任意位置 + <br>，即硬换行，在渲染后的页面中强行换行，虽然这在 md 中可读性不够，但是在有些时候，能出奇效，比如在标题中，可用它创造出占多行的标题：## H2's line1<br>and line2

起新段落

在 md 源文行末，若是单个回车，则在渲染后的页面中，视为空格；连续回车 (3 个及以上)，则在渲染后的页面中，另起一段，但仅是显示一行空行
在分割线处会强制分段

字体

字体	markdown	渲染效果	说明
斜体	两个符号之间	两个符号之间	虽然用 _ 也是一样的，但建议用 *，用 _ 时文本左右需要有空格，容错空间较小
粗体	四个符号之间	四个符号之间	同上
粗斜体	*六个符号之间*	六个符号之间	可将 * 和 _ 配对混用，但是没有必要
删除线	~~四个波浪线之间~~	~~四个波浪线之间~~
下划线	<u>这里有个下划线</u>	这里有个下划线	md 没有对应语法，用的 html
键盘文本	<kbd>模拟键帽</kbd>	`模拟键帽`	同上
高亮强调	==四个等号之间==	==四个等号之间==	Obsidian 支持的方言写法
居中对齐	<center>这几个字被居中了</center>	这几个字被居中了	的 html，标题、图片等适用

HTML 实体字符和 LaTeX 行内公式

参照下列网站

html: HTML 符号实体参考手册 (runoob.com)
latex: 在线编辑器 (latexlive.com)，latex 常用符号离线版 (kz16.top)

其中 HTML 实体字符以 &; 为标志，常用的有 &ensp; 缩进 1/2 个中文格，&emsp; 缩进 1/1 个中文格；而 LaTeX 公式以 $公式$ 为标志

两者都可以显示一些符号，也许是个好的装饰符，如 $\spadesuit$ ™，(\spadesuit) ™

Emoji 表情

字体	markdown	渲染效果	说明
两个冒号	:joy:	:joy:	需要软件支持，见这里
直接复制		😀	需要软件支持，叫这里
内嵌图标	<i class=”icon-name”></i>		HTML

六、行级：链接、图片、视频、角标、跳转

链接

内式 (inline)

markdown	渲染效果	说明
[shown info](link)	shown info	这里的 link 可以是整个网址也可以是相对链接
[shown info](link “hidden info”)	shown info	双引号中是 title，即鼠标悬停时能看到的字
\ https://www.doing.wang\	https://www.doing.wang	自动链接，直接贴网址，并在两边各加个空格
<https://www.doing.wang\>	https://www.doing.wang	也可以用尖括号把链接括起来 (shown info = link)

参考式 (reference)

语法：[shown info][id] or [shown info] [id]
即是说，两者中间可以有空格
在段尾或文章末尾写上 [id]: link "hidden info"
链接也可以用尖括号括起来 <link>

id 可以是数字字母和符号，包括空格，大小写不敏感
id 为空时，即方括号内连空格都没有时，id = shown ifo
不能套娃，[id][another id] 的写法是非法 (不被允许) 的
id 只以第一次被定义为准

[例子][id]
这中间的 [例子] 都指向 link1
id:
id:
这中间的 [例子] 还是都指向 link1
id:

HTML 格式

建议：短的链接用行内式；长、且需要重复用到的链接，用参考式
参考式写起来不太方便，但它大大提高了 md 文本可读性和链接的复用性
HTML 格式可以自定义字体大小颜色位置等，但在链接上并不实用，不赘述
我自己很少写参考式，也不喜欢加 title
一般浏览器在鼠标悬停时，左下角会显示完整的链接