作为 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]

1. 斜体、粗体、删除线

使用 * **~~ 分别表示斜体、粗体和删除线。

示例:

这是 *斜体*,这是 **粗体**,这是 ~~删除线~~。

这是 斜体,这是 粗体,这是 删除线

2. 分级标题

在行首加不同数量的 # 表示不同级别的标题 (H1-H6)。

最高层级不一定要从一级标题开始,目录解析过程会自动识别整个目录的最高层级。

示例:

## 这是一个二级标题
### 这是一个三级标题
#### 这是一个四级标题
##### 这是一个五级标题

这是一个二级标题

这是一个三级标题

这是一个四级标题

这是一个五级标题

3. 外链接

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

示例:

点击[程小白](https://www.chengxiaobai.cn)一起来交流探讨吧。

点击程小白一起来交流探讨吧。

4. 无序列表

使用 *+- 表示无序列表。

示例:

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

5. 有序列表

使用数字和点表示有序列表。

示例:

1. 有序列表项 一
2. 有序列表项 二
3. 有序列表项 三
  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 及之后版本支持)

  1. 默认(default) - 这是所有图表的默认主题。
  2. 墨水(neutral) - 这个主题非常适合将要打印的黑白文档。
  3. 暗黑(dark) - 这个主题与深色元素或深色模式搭配得很好。
  4. 森林绿(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? ​```
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?

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]
​```
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
​```
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]
​```
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]
​```
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" 属性。


  1. 来源于插件更新记录:https://www.chengxiaobai.cn/php/markdown-parser-library.html 

本作品由 程小白 创作,采用 知识共享署名-相同方式共享 4.0 国际许可协议 进行许可,可自由转载、引用但需署名作者且注明文章出处。
原文地址:https://www.chengxiaobai.cn/record/markdown-concise-grammar-manual.html