title: Markdown 语法

description: Halo 编辑器中所支持的 Markdown 语法说明

写在前面

从 1.5.0 版本开始，Halo 默认保存编辑器渲染的 html 文档。使用的 Markdown 渲染库为 markdown-it，我们也对此进行了封装：@halo-dev/markdown-renderer。后续我们会在任何需要渲染 Markdown 的地方都使用此库，保证 Markdown 渲染结果一致。

基础语法

markdown-it 使用了 CommonMark spec 规范，基础语法请参考 CommonMark spec。

自动链接（Auto Link）

支持自动将一个链接格式的文本转换为 a 标签链接。

语法规则：

  1. https://halo.run

渲染结果：

  1. <a href="https://halo.run">https://halo.run</a>

预览：

https://halo.run

代码块（Code Block）

语法规则：

````markdown {1}

  1. 内容
  2. 示例：
  4. ````markdown {1}
  5. ```java
  6. public static void main(String[] args){
  7.     System.out.println("Hello World!");
  8. }
  9. ```

````markdown {1}

  1. console.log("Hello World!")
  2. :::info
  3. 注意：代码高亮需要主题添加插件支持，不同的主题可能有实现差异。
  4. :::
  6. ## 缩写（abbr）
  8. 语法规则：
  10. ```markdown
  11. *[HTML]: Hyper Text Markup Language
  12. *[W3C]:  World Wide Web Consortium 
  13. The HTML specification
  14. is maintained by the W3C.
  15. ```
  17. 渲染结果：
  19. ```html
  20. <p>
  21.     The
  22.     <abbr title="Hyper Text Markup Language">
  23.         HTML
  24.     </abbr>
  25.     specification
  26.     <br />
  27.     is maintained by the
  28.     <abbr title="World Wide Web Consortium">
  29.         W3C
  30.     </abbr>
  31.     .
  32. </p>
  33. ```
  35. ## Attrs
  37. 此语法支持将 `id` `class` `target` 添加到渲染后的 HTML 标签上。
  39. 示例：
  41. ```markdown
  42. # Halo {#halo}
  43. ```
  45. ```markdown
  46. > Hello Halo {.info}
  47. ```
  49. ```markdown
  50. [https://halo.run](https://halo.run) {target="_blank"}
  51. ```
  53. 渲染结果：
  55. ```html
  56. <h1 id="halo" tabindex="-1">Halo</h1>
  57. ```
  59. ```html
  60. <blockquote class="info"> <p>Hello Halo</p> </blockquote>
  61. ```
  63. ```html
  64. <a href="https://halo.run" target="_blank">https://halo.run</a>
  65. ```
  67. ## Emoji
  69. 支持将 Emoji 的文字形式转化为图片形式。
  71. 示例：
  73. ```markdown
  74. :100:
  75. ```
  77. 渲染结果：
  79. ```html
  80. 💯
  81. ```
  83. ## 脚注（Footnote）
  85. 语法规则：
  87. ```markdown
  88. [^脚注名]
  89. [^脚注名]: 脚注内容
  90. ```
  92. 示例：
  94. ```html
  95. 驿外[^1]断桥边，寂寞开无主。已是黄昏独自愁，更着风和雨
  96. [^1]: 驿（yì）外：指荒僻、冷清之地。驿，驿站。
  97. ```
  99. 渲染结果：
  101. ```html
  102. <p>
  103.     驿外
  104.     <sup class="footnote-ref">
  105.         <a href="#fn1" id="fnref1">
  106.             [1]
  107.         </a>
  108.     </sup>
  109.     断桥边，寂寞开无主。已是黄昏独自愁，更着风和雨
  110. </p>
  111. <hr class="footnotes-sep">
  112. <section class="footnotes">
  113.     <ol class="footnotes-list">
  114.         <li id="fn1" class="footnote-item">
  115.             <p>
  116.                 驿（yì）外：指荒僻、冷清之地。驿，驿站。
  117.                 <a href="#fnref1" class="footnote-backref">
  118.                     ↩︎
  119.                 </a>
  120.             </p>
  121.         </li>
  122.     </ol>
  123. </section>
  124. ```
  126. ## 下划线（ins）
  128. 示例：
  130. ```markdown
  131. ++inserted++
  132. ```
  134. 渲染结果：
  136. ```html
  137. <ins>inserted</ins>
  138. ```
  140. 预览：
  142. <ins>inserted</ins>
  144. ## 标记（mark）
  146. 示例：
  148. ```markdown
  149. ==marked==
  150. ```
  152. 渲染结果：
  154. ```html
  155. <mark>marked</mark>
  156. ```
  158. 预览：
  160. <mark>marked</mark>
  162. ## 下标（sub）
  164. 示例：
  166. ```markdown
  167. H~2~0
  168. ```
  170. 渲染结果：
  172. ```html
  173. H<sub>2</sub>0
  174. ```
  176. 预览：
  178. H<sub>2</sub>0
  180. ## 上标（sup）
  182. 示例：
  184. ```markdown
  185. 29^th^
  186. ```
  188. 渲染结果：
  190. ```html
  191. 29<sup>th</sup>
  192. ```
  194. 预览：
  196. 29<sup>th</sup>
  198. ## 目录（TOC）
  200. 此语法支持根据标题生成文档目录。
  202. 示例：
  204. ```markdown
  205. [toc]
  207. # Heading
  209. ## Sub heading 1
  210. Some nice text
  212. ## Sub heading 2
  213. Some even nicer text
  214. ```
  216. 渲染结果：
  218. ```html
  219. <p>
  220.     <div class="table-of-contents">
  221.         <ul>
  222.             <li>
  223.                 <a href="#heading">
  224.                     Heading
  225.                 </a>
  226.                 <ul>
  227.                     <li>
  228.                         <a href="#sub-heading-1">
  229.                             Sub heading 1
  230.                         </a>
  231.                     </li>
  232.                     <li>
  233.                         <a href="#sub-heading-2">
  234.                             Sub heading 2
  235.                         </a>
  236.                     </li>
  237.                 </ul>
  238.             </li>
  239.         </ul>
  240.     </div>
  241. </p>
  242. <h1 id="heading" tabindex="-1">
  243.     Heading
  244. </h1>
  245. <h2 id="sub-heading-1" tabindex="-1">
  246.     Sub heading 1
  247. </h2>
  248. <p>
  249.     Some nice text
  250. </p>
  251. <h2 id="sub-heading-2" tabindex="-1">
  252.     Sub heading 2
  253. </h2>
  254. <p>
  255.     Some even nicer text
  256. </p>
  257. ```
  259. ## 任务列表（Task Lists）
  261. 示例：
  263. ```markdown
  264. - [x] Apple
  265. - [ ] Banana
  266. ```
  268. 渲染结果：
  270. ```html
  271. <ul class="contains-task-list">
  272.     <li class="task-list-item">
  273.         <input class="task-list-item-checkbox" checked="" disabled="" type="checkbox">
  274.         Apple
  275.     </li>
  276.     <li class="task-list-item">
  277.         <input class="task-list-item-checkbox" disabled="" type="checkbox">
  278.         Banana
  279.     </li>
  280. </ul>
  281. ```
  283. 预览：
  285. - [x] Apple
  286. - [ ] Banana
  288. ## 数学公式（Katex）
  290. 我们使用了 Katex 作为数学公式渲染的插件，因为从 1.5.0 开始，我们将直接保存编辑器渲染的内容，在保存的时候就已经保存了渲染好的 Katex 结构。所以在前台无需引入 Katex 插件来进行渲染，但目前仍需要引入 Katex 的样式文件，如果主题没有支持，可以在系统设置的 `自定义内容页 head：` 中加入以下代码：
  292. ```html
  293. <link rel="stylesheet" href="https://unpkg.com/katex@0.12.0/dist/katex.min.css" />
  294. ```
  296. ### 行内公式
  298. 示例：
  300. ```markdown
  301. $\sqrt{3x-1}+(1+x)^2$
  302. ```
  304. 预览：
  306. Example：$\sqrt{3x-1}+(1+x)^2$
  308. ### 块级公式
  310. 示例：
  312. ```markdown
  313. $$\begin{array}{c}
  315. \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &
  316. = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\
  318. \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\
  320. \nabla \cdot \vec{\mathbf{B}} & = 0
  322. \end{array}$$
  323. ```
  325. 预览：
  327. $$\begin{array}{c}
  329. \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &
  330. = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\
  332. \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\
  334. \nabla \cdot \vec{\mathbf{B}} & = 0
  336. \end{array}$$
  338. ## 图表（Mermaid）
  340. 从 Halo 1.5.0 开始，编辑器支持渲染 Mermaid 图表为 svg 内容，并直接保存渲染后的内容，所以无需在前台引入 Mermaid 插件进行渲染。
  342. 示例：
  344. ````markdown
  345. ```mermaid
  346. graph TD;
  347.     A-->B;
  348.     A-->C;
  349.     B-->D;
  350.     C-->D;
  351. ```
  1. ```mermaid
  2. sequenceDiagram
  3.     participant Alice
  4.     participant Bob
  5.     Alice->>John: Hello John, how are you?
  6.     loop Healthcheck
  7.         John->>John: Fight against hypochondria
  8.     end
  9.     Note right of John: Rational thoughts <br/>prevail!
  10.     John-->>Alice: Great!
  11.     John->>Bob: How about you?
  12.     Bob-->>John: Jolly good!
  13. ```

预览：

  1. graph TD;
  2.     A-->B;
  3.     A-->C;
  4.     B-->D;
  5.     C-->D;
  1. sequenceDiagram
  2.     participant Alice
  3.     participant Bob
  4.     Alice->>John: Hello John, how are you?
  5.     loop Healthcheck
  6.         John->>John: Fight against hypochondria
  7.     end
  8.     Note right of John: Rational thoughts <br/>prevail!
  9.     John-->>Alice: Great!
  10.     John->>Bob: How about you?
  11.     Bob-->>John: Jolly good!

短连接

参考 1.4.17/Markdown 语法。目前已经在 1.5.x 移除，建议直接使用官方提供的嵌入代码。