關(guān)鍵字
- Markdown語(yǔ)法
- Markdown轉(zhuǎn)義字符
- HTML標(biāo)簽
- HTML字符實(shí)體
聲明
本文在創(chuàng)作時(shí)使用的是Obsidian。由于簡(jiǎn)書(shū)對(duì)于HTML標(biāo)簽支持有所限制，導(dǎo)致排版效果無(wú)法正常顯示。具體而言本文內(nèi)容，體現(xiàn)于<code>標(biāo)簽無(wú)法被正常渲染，因此相關(guān)涉及部分只能依賴(lài)讀者自行調(diào)整和調(diào)試，敬請(qǐng)?jiān)彙?/p>
背景概述
眾所周知，Markdown是一種基于HTML的排版語(yǔ)法，會(huì)使用眾多特殊符號(hào)來(lái)實(shí)現(xiàn)特定的排版需求。在Markdown排版語(yǔ)法中，經(jīng)常用到的特殊符號(hào)有：
| 符號(hào) | 作用和排版效果 | 代碼示例 |
|---|---|---|
# |
設(shè)置標(biāo)題等級(jí)，標(biāo)準(zhǔn)Markdown語(yǔ)法支持1~6級(jí)標(biāo)題，但各Markdown編輯器 支持情況各不相同。對(duì)應(yīng)于 HTML中的<h1>至<h6>標(biāo)簽。 |
# 一級(jí)標(biāo)題## 二級(jí)標(biāo)題### 三級(jí)標(biāo)題
|
! |
在標(biāo)準(zhǔn)Markdown語(yǔ)法中用于插入圖片，對(duì)應(yīng)于HTML中的<img>標(biāo)簽。但是，很多Markdown編輯器都會(huì)對(duì)標(biāo)準(zhǔn)語(yǔ)法有所擴(kuò)展。 例如：在Obsidian中，如果需要引用視音頻文件和PDF文檔， 以及使用 #塊引用 時(shí)就需要 !作為引導(dǎo)標(biāo)識(shí)。對(duì)應(yīng)于HTML中的<audio>和<video>等標(biāo)簽。 |
![無(wú)法加載時(shí)的提示信息(圖片網(wǎng)址)] |
* _
|
用于設(shè)置文字 粗體 和 斜體 樣式。 分別對(duì)應(yīng)于 HTML中的<strong>和<em>標(biāo)簽。 |
**粗體文字**_斜體文字_
|
~ |
用于設(shè)置文字 HTML中的<del>標(biāo)簽。 |
~~刪除線~~ |
+ -
|
用于表示無(wú)序列表，對(duì)應(yīng)于HTML中的<ul>和<li>標(biāo)簽組合。此外， +和-也會(huì)在表示任務(wù)列表時(shí)使用到。 |
- 無(wú)序列表第1項(xiàng)+ 無(wú)序列表第2項(xiàng)+ [ ] 沒(méi)有完成的任務(wù)列表- [x] 完成的任務(wù)列表
|
> |
用于表示引用信息。對(duì)應(yīng)于HTML中的<blockquote>標(biāo)簽。 |
> 路漫漫其修遠(yuǎn)兮> 吾將上下而求索
|
< >
|
使用HTML標(biāo)簽進(jìn)行排版以補(bǔ)充Markdown語(yǔ)法的不足之處。例如：添加<u>下劃線</u>、上標(biāo)和下標(biāo)效果。 |
<u>下劃線</u><sup>上標(biāo)</sup><sub>下標(biāo)</sub>
|
[ ]
|
用于設(shè)置超鏈接，對(duì)應(yīng)于HTML中的<a>標(biāo)簽。 |
[顯示文字](網(wǎng)址 "鼠標(biāo)懸停時(shí)文字") |
| ` | 用于書(shū)寫(xiě)行內(nèi)代碼或段間代碼。對(duì)應(yīng)于HTML中的<code>標(biāo)簽。行內(nèi)代碼不限于標(biāo)注編程語(yǔ)言，也可以強(qiáng)調(diào)專(zhuān)用術(shù)語(yǔ)詞匯等。 |
行內(nèi)代碼： `#include <stdio.h>` 段間代碼： ```c int a = 1; char b = 'a'; ``` |
. |
用于表示有序列表，對(duì)應(yīng)于HTML中的<ol>和<li>標(biāo)簽組合。 |
1. 有序列表第1項(xiàng)2. 有序列表第2項(xiàng)
|
^ |
用于表示腳注。 |
《詠鵝》[^腳注名稱(chēng)]是一首詩(shī)。[^腳注名稱(chēng)]: 作者是駱賓王。
|
這些特殊符號(hào)在實(shí)際排版中都有使用，但問(wèn)題也隨之而來(lái)：在寫(xiě)作技術(shù)文檔時(shí)，難免會(huì)在行文之間會(huì)用到這些具有特殊功能的符號(hào)。那么，如何才能將這些特殊符號(hào)書(shū)寫(xiě)在Markdown文檔之中？答案很簡(jiǎn)單，使用Markdown轉(zhuǎn)義字符 。然而在具體實(shí)踐過(guò)程中，由于各Markdown編輯器在實(shí)現(xiàn)中使用的編程方法不及相同，所以彼此之間會(huì)有所差異。但無(wú)論如何，通過(guò)嘗試或組合總能找到適合的方法。
實(shí)現(xiàn)方法
事實(shí)上，Markdown確實(shí)提供了一種相對(duì)通用的方法來(lái)實(shí)現(xiàn)特殊功能的轉(zhuǎn)義效果，即使用\字符。這種形式非常類(lèi)似于C語(yǔ)言中的轉(zhuǎn)義字符序列。然而，也正如前文所述，在實(shí)際排版過(guò)程中，由于編程過(guò)程中底層實(shí)現(xiàn)的原因，有時(shí)我們還是需要借助一些特殊技巧才能實(shí)現(xiàn)特定效果。
前綴\實(shí)現(xiàn)轉(zhuǎn)義
Markdown轉(zhuǎn)義字符是\。也就是說(shuō)，在這些具有特殊含義的字符前加上\后，Markdown編輯器在渲染排版效果時(shí)將展現(xiàn)其原始的含義。
舉例來(lái)說(shuō)：
- 針對(duì)
HTML標(biāo)簽。使用HTML上下標(biāo)標(biāo)簽書(shū)寫(xiě)數(shù)學(xué)公式Sin2(x1)[1]，當(dāng)然應(yīng)該錄入Sin<sup>2</sup>(x<sub>1</sub>)。但如需展示的是完整的HTML代碼，則應(yīng)在文檔中鍵入Sin\<sup\>2\</sup\>(x\<sub\>1\</sub\>)才能實(shí)現(xiàn)。 - 針對(duì)
Markdown排版：使用Markdown語(yǔ)法展示強(qiáng)調(diào)效果，應(yīng)當(dāng)錄入**強(qiáng)調(diào)**。但是如需展示的只是Markdown代碼則應(yīng)在文檔中鍵入\*\*強(qiáng)調(diào)\*\*才能顯示成功。
此處兩例演示了\引導(dǎo)進(jìn)行Markdown轉(zhuǎn)義字符的方式，可以解決絕大多數(shù)轉(zhuǎn)義字符的需求，讀者大可以自行嘗試。但極少數(shù)情況下，不能適用時(shí)則需使用下文中的補(bǔ)足用法。
補(bǔ)足用法
最難處理的Markdown轉(zhuǎn)義字符情況，往往出現(xiàn)在循環(huán)嵌套的情況之中。
例如：
- 在文檔中演示被強(qiáng)調(diào)的內(nèi)容中包含字符
*[2]。 - 在文檔中演示
行內(nèi)代碼中包含字符<code>`</code>。
針對(duì)這種嵌套，在底層的編程實(shí)現(xiàn)過(guò)程中很難以?xún)?yōu)雅的方式完美解決，甚至很難被有效解決。無(wú)奈之下，我們最好抱持一事一論的態(tài)度進(jìn)行嘗試。下面的幾種方式，就是最常見(jiàn)的解決方法。
使用HTML標(biāo)簽或HTML字符實(shí)體
論及Markdown時(shí)，開(kāi)宗明義即強(qiáng)調(diào)其為基于HTML加以實(shí)現(xiàn)。毫無(wú)疑問(wèn)，在Markdown能夠?qū)崿F(xiàn)HTML中的眾多特性，其中也包括了HTML標(biāo)簽（HTML tags）以及HTML字符實(shí)體（HTML entities）。也正是因?yàn)榭梢砸眠@些特性，使得我們能夠相對(duì)較為容易的滿(mǎn)足Markdown轉(zhuǎn)義字符的特殊需求。
相信下面的示例能給予讀者一些啟發(fā)：
注意：本節(jié)中會(huì)有經(jīng)常出現(xiàn)類(lèi)似于<code>`</code>的情況，這是由于簡(jiǎn)書(shū)只對(duì)HTML標(biāo)簽提供有限支持所致。之所以沒(méi)有使用`的形式，是因?yàn)榉?hào)`非常小，不適于被強(qiáng)調(diào)顯示出來(lái)。這也是由于行間代碼中鍵入HTML 字符實(shí)體`后無(wú)法顯示出<code>`</code>所呈現(xiàn)的效果所致。
需求：在行間代碼中加入<code>`</code>。即：顯示諸如<code>ctrl+`</code>的效果。
問(wèn)題：可能是某種Bug使然，在行間代碼中加入<code>`</code>不能使用前置\的方法，此時(shí)只得借助于HTML標(biāo)簽。
解決方案：
- 只借助于
HTML標(biāo)簽：`ctrl+`<code>\`</code>。毫無(wú)疑問(wèn)，<code>\`</code>有其作用，但必須借助<code>標(biāo)簽才能完整的解決問(wèn)題。 - 借助
HTML標(biāo)簽和HTML字符實(shí)體：`ctrl+`<code>`</code>。其中，`是HTML字符實(shí)體，用于顯示字符<code>`</code>。
最后需要強(qiáng)調(diào)注意的是：
-
HTML標(biāo)簽(HTML tags)能夠補(bǔ)足Markdown語(yǔ)法不足，能夠?qū)崿F(xiàn)特定語(yǔ)法效果。但是，無(wú)論如何，在排版時(shí)還是應(yīng)當(dāng)優(yōu)先使用Markdown語(yǔ)法。 -
HTML實(shí)體字符（HTML entities）[3]只起到顯示作用，無(wú)法替換Markdown中的特殊語(yǔ)法符合，可以算是一種更為通用的Markdown轉(zhuǎn)義字符方式。
在標(biāo)題中加入#
最后的謎題，到了此時(shí)已經(jīng)變得相對(duì)容易。已有的解決方法有：
- 在標(biāo)題中使用
\#加以解決，缺點(diǎn)是會(huì)有個(gè)別Markdown編輯器會(huì)出現(xiàn)解析問(wèn)題。 - 使用
HTML字符實(shí)體替換，即在標(biāo)題中加入#；，缺點(diǎn)是行文語(yǔ)義表達(dá)不夠流暢。
假如，你使用等待Markdown編輯器在渲染時(shí)存在問(wèn)題，不妨借用下面這種形式：
-
Markdown關(guān)于標(biāo)題的語(yǔ)法可以采用## 二級(jí)標(biāo)題 ##的形式。所以，我們可以利用語(yǔ)法形式實(shí)現(xiàn)在標(biāo)題中加入#符號(hào)。具體實(shí)現(xiàn)為：### 三級(jí)#標(biāo)題 ###。
注釋
-
事實(shí)上，由于
Markdown編輯器廣泛支持Mathjax渲染數(shù)學(xué)公式，所以更好的方式是使用LaTeX語(yǔ)法錄入數(shù)學(xué)公式。例如，應(yīng)當(dāng)使用<code>$Sin^2(x_1)$</code>的方式來(lái)顯示<code></code>。這樣不但更符合數(shù)學(xué)公式排版對(duì)于字體方面的要求，同時(shí)也能實(shí)現(xiàn)更為復(fù)雜的效果。 ?
-
在
Markdown文檔中強(qiáng)調(diào)*其實(shí)非常容易處理，可以參照下面的示例：- 使用通用的Markdown轉(zhuǎn)義字符，即
\作為前綴的方法：**\***。這也是最應(yīng)被推崇的方法，通常不會(huì)引起Markdown編輯器異常，也最為符合Markdown語(yǔ)法規(guī)定。 - 使用
HTML字符實(shí)體：*****。這種方法當(dāng)然也能適用，但可能會(huì)引發(fā)某些Markdown編輯器渲染問(wèn)題。例如：在Obsidian中使用這種用法，在預(yù)覽模式中沒(méi)有任何問(wèn)題，但在編輯模式下則會(huì)引發(fā)顯示問(wèn)題。 - 當(dāng)然使用
HTML中的<strong>標(biāo)簽也是一種方法，即使用<strong>\*</strong>的方式。但是，為了保證顯示的正確性，還是要書(shū)寫(xiě)為\*方能有效避免在顯示方面潛藏的問(wèn)題。類(lèi)似的，也可以使用<strong>*</strong>的方式加以實(shí)現(xiàn)。
- 使用通用的Markdown轉(zhuǎn)義字符，即
-
關(guān)于完整的HTML字符實(shí)體列表，可以參考https://www.freeformatter.com/html-entities.html。
由于HTML字符實(shí)體參考了ASCII代碼，所以ASCII碼值可應(yīng)用于HTML字符實(shí)體。例如：#在ASCII中碼值為96，則對(duì)應(yīng)的HTML字符實(shí)體碼值為`。 ?
