Markdown 語法

關於 Markdown#

Markdown 是一種以「可讀可寫」為核心的輕量標記語言。Hugo 以其作為預設的 內容格式。本頁旨在示範 Neso 佈景主題下的實際呈現 (render) 外觀，完整語法細節請自行查閱網路上的資料。

另外也建議查看 Shortcode，了解其他 Neso 支援的擴充語法，可在文章內插入類型更多樣的內容。

標題#

盡可能避免在 Markdown 內文使用「標題一」(#)，那應該保留給文章本身的標題使用。

Markdown 語法：

# 標題一
## 標題二
### 標題三範例字樣
#### 標題四：儘量少用
##### 標題五的意義不大
###### 標題六跟內文沒有差別

呈現效果：

標題一

標題二

標題三範例字樣

標題四：儘量少用

標題五的意義不大

標題六跟內文沒有差別

一般文字段落#

在 Markdown 內直接打字即可產生一般文字段落，每段間要隔一空行，以下為假文假字。

這也是互私上果地其實這種⋯我現的地也會的房機就是沒最，回來的的特了不知孩子，是多另一消失多人只家一起，傳天都可一般，木指接可以接。知道他還算現，我的管敢現在也，還沒嗚嗚，開我是哪個步可能會耶是只有，其實帥消尤其偶像，您年前他可以。

感謝中文假文產生器。

粗體、斜體#

以一對星號 * 包住為斜體，以兩對星號 ** 包住為粗體；三個星號可形成粗斜體；另外也可加刪除線 ~~被刪的字~~。

Markdown 語法：

這是一般文字，其中有 *斜體*、**粗體**、***粗斜體***，以及 ~~刪除線~~。

呈現效果：

這是一般文字，其中有 斜體、粗體、粗斜體，以及 刪除線。

引言#

在行首以 > 開頭可建立引言 (blockquote)；連續多行會自動合併；>> 或在引言中再加入 > 可建立巢狀引言。

Markdown 語法：

> 這是一段單層引言。
>
> 可以有多個段落。
>
> > 這是巢狀引言 (第二層)。

呈現效果：

這是一段單層引言。

可以有多個段落。

這是巢狀引言 (第二層)。

Neso 佈景主題另有針對引言功能做兩項加強：

Neso 加強版：引言來源#

在 hugo.toml 啟用 Markdown 屬性解析：

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      [markup.goldmark.parser.attribute]
        block = true

然後在引言緊接著下一行使用 {author="Name" source="URL"}：

> 這是一段單層引言。
{author="Neso" source="https://example.com"}

即可附上來源署名與連結 (連結為 optional)：

這是一段單層引言。

Neso 加強版：GitHub Alert#

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!NOTE] 自訂標題
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

呈現效果：

補充

Useful information that users should know, even when skimming content.

自訂標題

Useful information that users should know, even when skimming content.

提示

Helpful advice for doing things better or more easily.

重要

Key information users need to know to achieve their goal.

注意

Urgent info that needs immediate user attention to avoid problems.

警告

Advises about risks or negative outcomes of certain actions.

清單#

以 -、* 或 + 建立無序清單；以數字加點建立有序清單。

Markdown 語法：

- 無序清單項目 A
- 無序清單項目 B
    + 子項目 B-1
    + 子項目 B-2

1. 有序清單項目一
2. 有序清單項目二
3. 有序清單項目三

呈現效果：

• 無序清單項目 A
• 無序清單項目 B
  • 子項目 B-1
  • 子項目 B-2

1. 有序清單項目一
2. 有序清單項目二
3. 有序清單項目三

程式碼展示：區塊#

Markdown 語法：用三個重音符號 ` 包圍住程式碼的頭尾 (各占據一行)：

```
package main

import "fmt"

func main() {
    for i := 0; i < 3; i++ {
        fmt.Println("Value of i:", i)
    }
}
```

呈現效果：

package main

import "fmt"

func main() {
    for i := 0; i < 3; i++ {
        fmt.Println("Value of i:", i)
    }
}

使用「Chroma」進行語法上色：

 2
 3
 4
 5
 6
 7
 8
 9
10

package main

import "fmt"

func main() {
    for i := 0; i < 3; i++ {
        fmt.Println("Value of i:", i)
    }
}

終端機 prompt 符號：

$

hugo server

程式碼展示：行內#

用一對重音符號 ` 包圍文字來展示行內程式碼：

const number = 42;

使用語法上色 Shortcode：

分隔線#

連續三個以上的 -、* 或 _ 會產生分隔線 (horizontal rule)。

Markdown 語法：

---
***
___

呈現效果 (以下會出現 3 條分隔線)：

超連結#

超連結使用 [文字](URL "可選的標題")。

Markdown 語法：

這是超連結：[Hugo 官方網站](https://gohugo.io "前往 Hugo 官方網站")。

呈現效果：

這是超連結：Hugo 官方網站。

圖片#

圖片語法為 ![替代文字](路徑 "可選的標題")；替代文字 (alt) 有助於無障礙瀏覽 (a11y)。

Markdown 語法：

![清水混凝土風格的住宅大樓立面](beton-brut.jpg "Photo by babeneso")

呈現效果：

註腳#

使用 [^id] 建立註腳參照，並在文末以 [^id]: 說明 定義內容。

Markdown 語法：

這是有註腳的句子[^1]。

[^1]: 這是註腳說明，可以包含 **粗體** 與 *斜體* 等格式。

呈現效果：

這是有註腳的句子¹。