Markdown 简明语法手册
作为 typecho-markdown 的开发者,收到很多关于 Markdown 解析库的使用问题。
对于功能上的 bug 当然会第一时间(腹泻式更新)进行修复,非功能上的「问题」很难一个个去教大家如何使用,于是我将自己准备的插件 Test Case 重新编辑优化,整成了一个 「Markdown 简明语法手册」。
里面列出的每一项都是我自己的会用到的 Markdown 功能,每个功能点都有示例源码和渲染结果,解析渲染工具当然是 typecho-markdown,没有出现乱码、结构错乱问题即说明插件功能正常。
本插件符合 CommonMark 和 GFM(GitHub-Flavored Markdown)规范,开源免费,大家用的开心就行 😉。
同时本插件和 Typora 完全兼容,理论上通过 Typora 编辑的内容使用本插件就能正常解析,直接粘贴发布无需做任何修改,因为我就一直是这样用的 😎。
本博客运行环境:
- PHP - 8.3.2
- Typecho - 1.2.1
- MarkdownParse Plugin - 2.1.0
还在手动更新 Typecho 博客版本? 赶紧去试试 typecho-update-assistant 支持一键升级到最新版本,每次操作前均会备份,安全无虞。
因为每个人的运行环境和主题样式不一样,所以最终渲染样式供大家参考。
0.目录
使用 [TOC]
来标示插入目录,目录分级取决于文章已有的分级标题。
最高层级不一定要从一级标题开始,目录解析过程会自动识别整个目录的最高层级。
示例:
[TOC]
- 0.目录
- 1. 斜体、粗体、删除线
- 2. 分级标题
- 3. 外链接
- 4. 无序列表
- 5. 有序列表
- 6. 文字引用
- 7. 行内代码块
- 8. 代码块
- 9. 插入图像
- 10. 表格支持
- 11. LaTeX 公式
- 12. Mermaid(1.3.0 及之后版本支持)
- 13. 注脚
- 14. 文本高亮(2.0.0 及之后版本支持)
- 15. 任务列表(2.0.0 及之后版本支持)
- 16. 外部链接(2.0.0 及之后版本支持)
1. 斜体、粗体、删除线
使用 *
、 **
、~~
分别表示斜体、粗体和删除线。
示例:
这是 *斜体*,这是 **粗体**,这是 ~~删除线~~。
这是 斜体,这是 粗体,这是 删除线。
2. 分级标题
在行首加不同数量的 #
表示不同级别的标题 (H1-H6)。
最高层级不一定要从一级标题开始,目录解析过程会自动识别整个目录的最高层级。
示例:
## 这是一个二级标题
### 这是一个三级标题
#### 这是一个四级标题
##### 这是一个五级标题
这是一个二级标题
这是一个三级标题
这是一个四级标题
这是一个五级标题
3. 外链接
使用[描述](链接地址)
为文字增加外链接。
示例:
点击[程小白](https://www.chengxiaobai.cn)一起来交流探讨吧。
点击程小白一起来交流探讨吧。
4. 无序列表
使用 *
,+
,-
表示无序列表。
示例:
- 无序列表项 一
- 无序列表项 二
- 无序列表项 三
- 无序列表项 一
- 无序列表项 二
- 无序列表项 三
5. 有序列表
使用数字和点表示有序列表。
示例:
1. 有序列表项 一
2. 有序列表项 二
3. 有序列表项 三
- 有序列表项 一
- 有序列表项 二
- 有序列表项 三
6. 文字引用
使用 >
表示文字引用。
示例:
> 有一种鸟是关不住的,因为它的每一根羽毛都闪耀着自由的光辉。
有一种鸟是关不住的,因为它的每一根羽毛都闪耀着自由的光辉。
7. 行内代码块
使用 `代码` 表示行内代码块。
示例:
`php`
php
8. 代码块
使用 ```代码``` 表示代码块。
示例:
```php
public function __construct(array $config = [])
{
$this->configureDefaults($config);
}
```
public function __construct(array $config = [])
{
$this->configureDefaults($config);
}
9. 插入图像
使用 ![描述](图片链接地址)
插入图像。
示例:
![浪浪山](https://cdn.chengxiaobai.com/2023/01/30/langlangshan.webp)
图片延迟加载
支持浏览器原生的图片延迟加载,无 JavaScript 依赖,默认开启,参考文档:MDN-Lazy loading,现代浏览器基本都支持,详细见 Can I use。
10. 表格支持
表格语法。
示例:
| base_uri | uri | result |
| :--------------------: | :-----: | :--------------------------: |
| chengxiaobai.cn/first/ | /second | chengxiaobai.cn/second |
| chengxiaobai.cn/first/ | second | chengxiaobai.cn/first/second |
| chengxiaobai.cn/first | /second | chengxiaobai.cn/second |
| chengxiaobai.cn/first | second | chengxiaobai.cn/second |
base_uri | uri | result |
---|---|---|
chengxiaobai.cn/first/ | /second | chengxiaobai.cn/second |
chengxiaobai.cn/first/ | second | chengxiaobai.cn/first/second |
chengxiaobai.cn/first | /second | chengxiaobai.cn/second |
chengxiaobai.cn/first | second | chengxiaobai.cn/second |
11. LaTeX 公式
使用 $
和 $$
包裹公式内容,分别代表行内公式和公式块。
示例:
这是一个行内公式:$f(x,y,z) = 3y^2z \left( 3+\frac{7x+5}{1+y^2} \right)$
这是一个公式块:
$$
F^{HLLC}=\left\{
\begin{array}{rcl}
F_L & & {0 < S_L}\\
F^*_L & & {S_L \leq 0 < S_M}\\
F^*_R & & {S_M \leq 0 < S_R}\\
F_R & & {S_R \leq 0}
\end{array} \right.
$$
这也是一个公式块
$$
\begin{align*}
\nabla \times \mathbf{B} - \frac{1}{c} \frac{\partial \mathbf{E}}{\partial t} &= \frac{4\pi}{c} \mathbf{J} \\
\nabla \cdot \mathbf{E} &= 4\pi \rho \\
\nabla \cdot \mathbf{B} &= 0 \\
\nabla \times \mathbf{E} + \frac{1}{c} \frac{\partial \mathbf{B}}{\partial t} &= \mathbf{0}
\end{align*}
$$
这是一个行内公式:$f(x,y,z) = 3y^2z \left( 3+\frac{7x+5}{1+y^2} \right)$
这是一个公式块:
$$ F^{HLLC}=\left\{ \begin{array}{rcl} F_L & & {0 < S_L}\\ F^*_L & & {S_L \leq 0 < S_M}\\ F^*_R & & {S_M \leq 0 < S_R}\\ F_R & & {S_R \leq 0} \end{array} \right. $$这也是一个公式块
$$ \begin{align*} \nabla \times \mathbf{B} - \frac{1}{c} \frac{\partial \mathbf{E}}{\partial t} &= \frac{4\pi}{c} \mathbf{J} \\ \nabla \cdot \mathbf{E} &= 4\pi \rho \\ \nabla \cdot \mathbf{B} &= 0 \\ \nabla \times \mathbf{E} + \frac{1}{c} \frac{\partial \mathbf{B}}{\partial t} &= \mathbf{0} \end{align*} $$12. Mermaid(1.3.0 及之后版本支持)
将代码块的语言标记为 mermaid
即可使用 mermaid 作图,支持所有 mermaid 语法,点击查看官方语法文档。
配置 Mermaid 主题颜色(2.0.0 及之后版本支持)
- 默认(default) - 这是所有图表的默认主题。
- 墨水(neutral) - 这个主题非常适合将要打印的黑白文档。
- 暗黑(dark) - 这个主题与深色元素或深色模式搭配得很好。
- 森林绿(forest) - 这个主题包含绿色的色调。
Sequence Diagram
```mermaid
sequenceDiagram
Alice ->> Bob: Hello Bob, how are you?
Bob-->>John: How about you John?
Bob--x Alice: I am good thanks!
Bob-x John: I am good thanks!
Note right of John: Bob thinks a long
long time, so long
that the text does
not fit on a row.
Bob-->Alice: Checking with John...
Alice->John: Yes... John, how are you?
```
long time, so long
that the text does
not fit on a row. Bob-->Alice: Checking with John... Alice->John: Yes... John, how are you?
Flowchart
```mermaid
flowchart LR
A[Hard edge] -->|Link text| B(Round edge)
B --> C{Decision}
C -->|One| D[Result one]
C -->|Two| E[Result two]
```
Gantt Diagrams
```mermaid
gantt
title A Gantt Diagram
dateFormat YYYY-MM-DD
section Section
A task :a1, 2014-01-01, 30d
Another task :after a1 , 20d
section Another
Task in sec :2014-01-12 , 12d
another task : 24d
```
Quadrant Chart
```mermaid
quadrantChart
title Reach and engagement of campaigns
x-axis Low Reach --> High Reach
y-axis Low Engagement --> High Engagement
quadrant-1 We should expand
quadrant-2 Need to promote
quadrant-3 Re-evaluate
quadrant-4 May be improved
Campaign A: [0.3, 0.6]
Campaign B: [0.45, 0.23]
Campaign C: [0.57, 0.69]
Campaign D: [0.78, 0.34]
Campaign E: [0.40, 0.34]
Campaign F: [0.35, 0.78]
```
XY Chart
```mermaid
xychart-beta
title "Sales Revenue"
x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
y-axis "Revenue (in $)" 4000 --> 11000
bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
```
13. 注脚
Typecho Markdown 插件第一版本发布于 2017-12-02[^1]。
[^1]: 来源于插件更新记录:https://www.chengxiaobai.cn/php/markdown-parser-library.html
Typecho Markdown 插件第一版本发布于 2017-12-021。
14. 文本高亮(2.0.0 及之后版本支持)
使用 ==
包裹起来的文本会被高亮展示,无 JavaScript 依赖,默认开启,参考文档:MDN-Mark,现代浏览器基本都支持,详细见 Can I use。
这句话里面==程小白==被高亮标记了。
这句话里面程小白被高亮标记了。
15. 任务列表(2.0.0 及之后版本支持)
任务列表展示,无 JavaScript 依赖,只读模式。
- [x] Typecho 最新版本插件系统适配
- [x] MarkdownParse 适配 GFM
- [ ] MarkdownParse 发布 2.0 版本
- Typecho 最新版本插件系统适配
- MarkdownParse 适配 GFM
- MarkdownParse 发布 2.0 版本
16. 外部链接(2.0.0 及之后版本支持)
内部链接:默认为博客域名,支持正则表达式 /(^|\.)example\.com$/
,多个可以用英文逗号区隔。
外部链接:非内部链接,接解析策略:默认在新窗口中打开,并加上 "noopener noreferrer" 属性。
来源于插件更新记录:https://www.chengxiaobai.cn/php/markdown-parser-library.html ↩
本作品由 程小白 创作,采用 知识共享署名-相同方式共享 4.0 国际许可协议 进行许可,可自由转载、引用但需署名作者且注明文章出处。
原文地址:https://www.chengxiaobai.cn/record/markdown-concise-grammar-manual.html
不知道能不能联系到你
希望支持新窗口中打开链接的语法兼容,非常感谢,已创建 Issue: https://github.com/mrgeneralgoo/typecho-markdown/issues/34
[...]https://www.chengxiaobai.cn/record/markdown-concise-grammar-manual.html[...]
Latex 公式兼容不了Degree