有的時候我覺得我不會 Markdown

冴羽發表於2022-01-31

前言

在 《一篇帶你用 VuePress + Github Pages 搭建部落格》中，我們使用 VuePress 搭建了一個部落格，最終的效果檢視：TypeScript 中文文件。

在優化部落格的過程中，因為需要寫 markdown-it 外掛，翻了下 markdown 的 CommonMark Spec，突然發現對 Markdown 還遠不夠了解：

軟換行（Soft line breaks）

換行符不在行內程式碼或 HTML 標籤內，前面沒有兩個或以上的空格，將解析為軟換行（Soft line breaks）。渲染為 HTML 時是一個行結束符或空格。

輸入：

foo
baz

輸出：

<p>foo
baz</p>

表現：

硬換行（Hard line breaks）

換行符不在內聯程式碼或 HTML 標籤內，前面有兩個或多個的空格，並且不在塊的末尾， 將解析為硬換行（Hard line breaks） ，渲染為 HTML 時是一個
<br /> 標籤。

輸入（注意 foo 後面有兩個空格）：

foo  
baz

輸出：

<p>foo

baz</p>

表現：

反斜槓（backslash）

除了用於轉義，在行尾的反斜槓相當於硬換行：

輸入：

foo\
bar

輸出：

<p>foo

bar</p>

行內程式碼（code span）

我們通常會用一對反引號包裹字串，表示行內程式碼（code span）：

輸入：

`foo`

輸出：

<p><code>foo</code></p>

表現：

但其實行內程式碼只要求內聯程式碼以反引號串開始，以同樣長度的反引號串結束。

所以用多個反引號也是可以的：

```foo```

輸出：

<p><code>foo</code></p>

圍欄式程式碼塊（Fenced code blocks）

如果你使用了至少三個連續的反引號，並且新增了換行，就會變成圍欄式程式碼塊：

```
foo
```

輸出：

<pre><code>foo
</code></pre>

表現：

如同行內程式碼，不要求必須三個反引號，只要至少三個並且前後相同就行，所以當我們想在程式碼塊中使用三個反引號時，你可以使用四個反引號包裹：

````
```markdown
foo
```
````

表現為：

不使用反引號，使用波浪號也是可以的，但不能混用：

~~~
foo
~~~

輸出：

<pre><code>foo
</code></pre>

縮排式程式碼塊（Indented code blocks）

縮排式程式碼塊由空行隔開的數個縮排塊組成。

縮排塊是數個非空行，每行縮排四個或多個空格。

舉例一個縮排塊：

    a simple
      indented code block

輸出：

<pre><code>a simple
  indented code block
</code></pre>

表現：

舉例由空行隔開的數個縮排塊：

    chunk1

    chunk2




    chunk3

輸出：

<pre><code>chunk1

chunk2



chunk3
</code></pre>

三個縮排塊共同組成了縮排式程式碼塊。

表現：

連結引用定義（Link reference definitions）

連結引用定義由連結標籤、冒號(:)、可選的空白、連結目標、可選的空白及可選的連結標題組成。舉個例子：

[foo]: /url "title"

但這只是一個定義，並不會有任何展示，就像我們在 JavaScript 中宣告瞭一個變數一樣，如果我們要使用它：

[foo]

輸出：

<p><a href="/url" title="title">foo</a></p>

連結引用定義不對應於某個結構元素。實際上它定義了一個標籤，以用於在文件其它地方的引用連結及引用型別影像。它可以出現在引用連結的前面或後面。

當在圖片中使用連結引用定義時：

![foo][bar]

[bar]: /url

輸出：

<p><img src="/url" alt="foo" /></p>

自動連結（Autolinks）

自動連結是由尖括號(<...>)包裹的絕對 URI 與 email 地址。 它將解析為連結，以 URL 或 email 地址作為連結標籤。

<http://foo.bar.baz>

相當於：

[http://foo.bar.baz](http://foo.bar.baz)

輸出為：

<p><a href="http://foo.bar.baz">http://foo.bar.baz</a></p>

Setext 式標題（Setext headings）

Setext 是一種輕量級標記語言，用於格式化純文字文件，例如電子通訊，Usenet 帖子和電子郵件。與其他一些標記語言相比，該標記易於閱讀，而無需任何解析或特殊軟體。

Markdown 同樣提供了類似的語法：

Foo *bar*
=========

Foo *bar*
---------

輸出：

<h1>Foo <em>bar</em></h1>
<h2>Foo <em>bar</em></h2>

使用 =則是第一級標題，使用-字元則是第二級標題。底線長度任意。

水平線（Thematic breaks）

由 0-3 個空格的縮排及三或多個 -,_, * 字元組成的行，形成水平線。

輸入：

***
---
___

輸出：

<hr />
<hr />
<hr />

表現：

系列文章

部落格搭建系列是我至今寫的唯一一個偏實戰的系列教程，預計 20 篇左右，講解如何使用 VuePress 搭建、優化部落格，並部署到 GitHub、Gitee、私有伺服器等平臺。本篇為第 19 篇，全系列文章地址：https://github.com/mqyqingfen...

微信：「mqyqingfeng」，加我進冴羽唯一的讀者群。

如果有錯誤或者不嚴謹的地方，請務必給予指正，十分感謝。如果喜歡或者有所啟發，歡迎 star，對作者也是一種鼓勵。

相關文章