@ -3,209 +3,452 @@ title: Markdown 语法
description: Halo 编辑器中所支持的 Markdown 语法说明
---
## 写在前面
从 1.5.0 版本开始， markdown-it ](https://github.com/markdown-it/markdown-it )，我们也对此进行了封装：[@halo-dev/markdown-renderer](https://github.com/halo-dev/js-sdk/tree/master/packages/markdown-renderer)。后续我们会在任何需要渲染 Markdown 的地方都使用此库，保证 Markdown 渲染结果一致。
## 基础语法
Halo 使用的 `Markdown` 解析器为 [flexmark-java ](https://github.com/vsch/flexmark-java )，基于 [CommonMark (spec 0.28) ](https://spec.commonmark.org/0.28/ ) 标准开发，语法参考：[https://spec.commonmark.org/0.28/](https://spec.commonmark.org/0.28/)。
markdown-it 使用了 [CommonMark spec ](https://spec.commonmark.org ) 规范，基础语法请参考 [CommonMark spec ](https://spec.commonmark.org )。
## 代码块
## 自动链接（ ）
````markdown
支持自动将一个链接格式的文本转换为 a 标签链接。
语法规则：
```plain
https://halo.run
```
渲染结果：
```html
< a href = "https://halo.run" > https://halo.run< / a >
```
预览：
< https: / / halo . run >
## 代码块（ ）
语法规则：
````markdown {1}
```language
代码块
内容
```
````
其中，
示例 ：
````markdown
````markdown {1}
```java
public static void main(String[] args){
System.out.println("Hello World!");
}
```
````
````markdown
````markdown {1}
```javascript
console.log("Hello World!")
```
````
## TOC
:::info
注意：代码高亮需要主题添加插件支持，不同的主题可能有实现差异。
:::
## 缩写（ ）
语法规则：
```markdown
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
The HTML specification
is maintained by the W3C.
```
渲染结果：
在文章的最前面加上 `[TOC]` 即可。
```html
< p >
The
< abbr title = "Hyper Text Markup Language" >
HTML
< / abbr >
specification
< br / >
is maintained by the
< abbr title = "World Wide Web Consortium" >
W3C
< / abbr >
.
< / p >
```
## 自动链接
## Attrs
支持自动将一个链接解析为可点击的格式，如下：
此语法支持将 `id` `class` `target` 添加到渲染后的 HTML 标签上。
示例：
```markdown
https://halo.run
# Halo {#halo}
```
```markdown
> Hello Halo {.info}
```
```markdown
[https://halo.run ](https://halo.run ) {target="_blank"}
```
将被解析为：
渲染结果 ：
```html
< a href = "https://halo.run" > https://halo.run< / a >
< h1 id = "halo" tabindex = "-1" > Halo< / h1 >
```
```html
< blockquote class = "info" > < p > Hello Halo< / p > < / blockquote >
```
```html
< a href = "https://halo.run" target = "_blank" > https://halo.run< / a >
```
## Emoji
支持将 Emoji 的文字形式转化为图片形式，如下：
支持将 Emoji 的文字形式转化为图片形式。
示例：
```markdown
:100:
```
将被解析为 ：
渲染结果 ：
```html
💯
```
更多 Emoji 表情可访问：[https://emoji.svend.cc](https://emoji.svend.cc)
## 数学公式
## 脚注（ ）
行内公式 ：
语法规则：
```markdown
$a \ne 0$
[^脚注名]
[^脚注名]: 脚注内容
```
段落公式 ：
示例 ：
```markdown
$$
x = {-b \pm \sqrt{b^2-4ac} \over 2a}.
$$
```html
驿外[^1]断桥边，寂寞开无主。已是黄昏独自愁，更着风和雨
[^1]: 驿（ ） ： ，
```
> 需要注意的是，并不是每一款主题都支持显示数学公式，你可以先到你使用的主题设置中查看是否支持，如不支持，请看下面的解决方案。
首先，登陆到后台，进入 `系统 -> 博客设置 -> 其他设置` 。将下面的代码复制到 `自定义内容页面 head` 。
渲染结果：
```html
< script src = "//cdn.jsdelivr.net/npm/mathjax@2.7.5/unpacked/MathJax.js?config=TeX-MML-AM_CHTML" defer > < / script >
< script >
document.addEventListener('DOMContentLoaded', function () {
MathJax.Hub.Config({
'HTML-CSS': {
matchFontHeight: false
},
SVG: {
matchFontHeight: false
},
CommonHTML: {
matchFontHeight: false
},
tex2jax: {
inlineMath: [
['$','$'],
['\\(','\\)']
],
displayMath: [["$$", "$$"], ["\\[", "\\]"]]
}
});
});
< / script >
```
## 图表
饼图：
````markdown
```mermaid
pie title NETFLIX
"Time spent looking for movie" : 90
"Time spent watching it" : 10
< p >
驿外
< sup class = "footnote-ref" >
< a href = "#fn1" id = "fnref1" >
[1]
< / a >
< / sup >
断桥边，寂寞开无主。已是黄昏独自愁，更着风和雨
< / p >
< hr class = "footnotes-sep" >
< section class = "footnotes" >
< ol class = "footnotes-list" >
< li id = "fn1" class = "footnote-item" >
< p >
驿（ ） ： ，
< a href = "#fnref1" class = "footnote-backref" >
↩︎
< / a >
< / p >
< / li >
< / ol >
< / section >
```
````
更多用法查看：[https://mermaidjs.github.io/#/](https://mermaidjs.github.io/#/)
## 下划线（ ）
示例：
> 需要注意的是，并不是每一款主题都支持显示图表，你可以先到你使用的主题设置中查看是否支持，如不支持，请看下面的解决方案。
```markdown
++inserted++
```
首先，登陆到后台，进入 `系统 -> 博客设置 -> 其他设置` 。将下面的代码复制到 `自定义内容页面 head` 。
渲染结果：
```html
< script src = "https://cdn.jsdelivr.net/npm/mermaid@8.4.4/dist/mermaid.min.js" > < / script >
< ins> inserted< / ins >
```
## 短连接
预览：
:::tip
这属于实验性特性，也许我们将在未来的版本移除这个特性。
:::
< ins > inserted< / ins >
## 标记（ ）
示例：
```markdown
==marked==
```
渲染结果：
Halo 内置一些短连接以更好地支持一些 HTML 语法，但是编辑器目前并不能解析，只能发布之后才可以看到效果，如下：
```html
< mark > marked< / mark >
```
预览：
### 网易云音乐
< mark > marked< / mark >
#### 语法
## 下标（ ）
示例：
```markdown
[music:id]
H~2~0
```
#### 示例
渲染结果：
```html
H< sub > 2< / sub > 0
```
预览：
H< sub > 2< / sub > 0
## 上标（ ）
示例：
```markdown
[music:32507038]
29^th^
```
#### 解析结果
渲染结果：
```html
< iframe frameborder = "no" border = "0" marginwidth = "0" marginheight = "0" width = 330 height = 86 src = "//music.163.com/outchain/player?type=2&id=32507038&auto=1&height=66" > < / iframe >
29< sup > th< / sup >
```
### 哔哩哔哩动画
预览：
29< sup > th< / sup >
## 目录（ ）
#### 语法
此语法支持根据标题生成文档目录。
示例：
```markdown
[bilibili:aid,width,height]
[toc]
# Heading
## Sub heading 1
Some nice text
## Sub heading 2
Some even nicer text
```
渲染结果：
```html
< p >
< div class = "table-of-contents" >
< ul >
< li >
< a href = "#heading" >
Heading
< / a >
< ul >
< li >
< a href = "#sub-heading-1" >
Sub heading 1
< / a >
< / li >
< li >
< a href = "#sub-heading-2" >
Sub heading 2
< / a >
< / li >
< / ul >
< / li >
< / ul >
< / div >
< / p >
< h1 id = "heading" tabindex = "-1" >
Heading
< / h1 >
< h2 id = "sub-heading-1" tabindex = "-1" >
Sub heading 1
< / h2 >
< p >
Some nice text
< / p >
< h2 id = "sub-heading-2" tabindex = "-1" >
Sub heading 2
< / h2 >
< p >
Some even nicer text
< / p >
```
#### 示例
## 任务列表（ ）
示例：
```markdown
[bilibili:65898131,256,256]
- [x] Apple
- [ ] Banana
```
#### 解析结果
渲染结果：
```html
< iframe height = "256" width = "256" src = "//player.bilibili.com/player.html?aid=65898131" scrolling = "no" border = "0" frameborder = "no" framespacing = "0" allowfullscreen = "true" > < / iframe >
< ul class = "contains-task-list" >
< li class = "task-list-item" >
< input class = "task-list-item-checkbox" checked = "" disabled = "" type = "checkbox" >
Apple
< / li >
< li class = "task-list-item" >
< input class = "task-list-item-checkbox" disabled = "" type = "checkbox" >
Banana
< / li >
< / ul >
```
## 脚注
预览：
- [x] Apple
- [ ] Banana
语法：
## 数学公式（ ）
我们使用了 Katex 作为数学公式渲染的插件，因为从 1.5.0 开始，我们将直接保存编辑器渲染的内容，在保存的时候就已经保存了渲染好的 Katex 结构。所以在前台无需引入 Katex 插件来进行渲染，但目前仍需要引入 Katex 的样式文件，如果主题没有支持，可以在系统设置的 `自定义内容页 head： 中加入以下代码：
```html
< link rel = "stylesheet" href = "https://unpkg.com/katex@0.12.0/dist/katex.min.css" / >
```
### 行内公式
示例：
```markdown
[^脚注名]
[^脚注名]: 脚注内容
$\sqrt{3x-1}+(1+x)^2$
```
预览：
Example：
### 块级公式
示例：
```markdown
驿外[^1]断桥边，寂寞开无主。已是黄昏独自愁，更着风和雨
[^1]: 驿（ ） ： ，
$$\begin{array}{c}
\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &
= \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\
\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\
\nabla \cdot \vec{\mathbf{B}} & = 0
\end{array}$$
```
解析结果：
预览 ：
```html
< p > 驿外< sup class = "footnote-ref" > < a href = "#fn1" id = "fnref1" > [1]< / a > < / sup > 断桥边，寂寞开无主。已是黄昏独自愁，更着风和雨< / p >
< hr class = "footnotes-sep" >
< section class = "footnotes" >
< ol class = "footnotes-list" >
< li id = "fn1" class = "footnote-item" > < p > 驿（ ） ： ， < a href = "#fnref1" class = "footnote-backref" > ↩︎< / a > < / p >
< / li >
< / ol >
< / section >
$$\begin{array}{c}
\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &
= \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\
\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\
\nabla \cdot \vec{\mathbf{B}} & = 0
\end{array}$$
## 图表（ ）
从 Halo 1.5.0 开始，编辑器支持渲染 Mermaid 图表为 svg 内容，并直接保存渲染后的内容，所以无需在前台引入 Mermaid 插件进行渲染。
示例：
````markdown
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
````
````markdown
```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts < br / > prevail!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```
````
预览：
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts < br / > prevail!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```
## 短连接
参考 [1.4.17/Markdown 语法 ](../../versioned_docs/version-1.4.17/user-guide/markdown.md#短连接 )。目前已经在 1.5.x 移除，建议直接使用官方提供的嵌入代码。
Ryan Wang
3 years ago
committed by
GitHub