zzy / Blog

Back
9 min
中文
markdown /
寫作

Markdown 語法指南

從標題、清單、連結到程式碼、表格、數學式與註腳，一次整理寫部落格最常用的 Markdown 語法，順便確認這個部落格的排版。

這是這個部落格的第一篇文章。之後每一篇都會用 Markdown 寫，所以第一篇就先把常用語法整理起來：一方面當作自己的備忘錄，一方面也確認標題、清單、程式碼、表格和數學式在這個佈景主題底下都能正常顯示。

下面每個段落都先列出 Markdown 原始碼，接著是實際顯示的效果。

基本語法#

標題#

用 # 開頭表示標題，# 的數量代表層級，最多六層。# 和文字之間要留一個空格。

# 一級標題

## 二級標題

### 三級標題
markdown

一級標題通常保留給文章名稱，內文從二級標題開始用。這篇文章的目錄，就是從二、三級標題自動產生的。

段落與換行#

段落之間要空一行。只按一次 Enter 不會換行，前後兩行會接在一起顯示：

第一行
第二行，會接在第一行後面。

空一行之後，才是新的段落。
markdown

第一行 第二行，會接在第一行後面。

空一行之後，才是新的段落。

需要在段落裡強制換行時，可以在行尾加兩個空格，或直接寫 <br>。

強調#

**粗體**、*斜體*、***粗斜體***、~~刪除線~~
markdown

粗體、斜體、粗斜體、刪除線

中文字型大多沒有真正的斜體，瀏覽器只能把字形硬拉斜，所以中文段落比較建議用粗體來強調。

還有一個寫中文才會遇到的地雷：粗體符號緊貼全形標點時，可能會失效。

**「重點」**的寫法：星號會原樣顯示，不會變粗體。

「**重點**」的寫法：把標點移到星號外面就正常了。
markdown

「重點」的寫法：把標點移到星號外面就正常了。

原因是 Markdown 規格用「符號前後是不是標點或空白」來判斷粗體從哪裡開始、到哪裡結束，而中文句子裡沒有空格，標點一貼上去就判斷不出來。

清單#

無序清單用 - 開頭，有序清單用數字加句點。縮排兩個空格可以做出巢狀清單。

- 蘋果
- 香蕉
  - 芭蕉
  - 芝麻蕉
- 芭樂

1. 打開編輯器
2. 寫下標題
3. 開始寫內文
markdown
  • 蘋果
  • 香蕉
    • 芭蕉
    • 芝麻蕉
  • 芭樂
  1. 打開編輯器
  2. 寫下標題
  3. 開始寫內文

待辦清單#

在清單項目前面加上 [ ] 或 [x]，就變成待辦清單。

- [x] 架好部落格
- [x] 寫第一篇文章
- [ ] 持續寫下去
markdown
  • 架好部落格
  • 寫第一篇文章
  • 持續寫下去

連結#

[Astro 官方網站](https://astro.build)

<https://blog.zzy.tw>

這是[參考式連結][astro]，網址可以集中寫在文章最後。

[astro]: https://astro.build
markdown

Astro 官方網站

https://blog.zzy.tw

這是參考式連結，網址可以集中寫在文章最後。

圖片#

圖片的語法跟連結只差前面的驚嘆號：

![替代文字](./cover.jpg "滑鼠移上去時顯示的標題")
markdown

替代文字會在圖片載入失敗、或讀者使用螢幕閱讀器時派上用場，最好不要留空。圖片可以放在文章的同一個資料夾裡，用相對路徑引用，建置時 Astro 會自動幫你最佳化。

引用#

> 在文字前面加上 `>` 就是引用。
>
> > 引用裡面還可以再引用。
markdown

在文字前面加上 > 就是引用。

引用裡面還可以再引用。

分隔線#

單獨一行寫三個以上的 -，就會產生一條分隔線：

---
markdown

程式碼#

行內程式碼#

用一對反引號把程式碼包起來：

用 `npm run build` 建置網站。
markdown

用 npm run build 建置網站。

程式碼區塊#

用三個反引號包住整段程式碼，並在開頭標上語言名稱，就會有語法高亮：

```ts
const greet = (name: string) => `哈囉，${name}！`

console.log(greet('世界'))
```
markdown
const greet = (name: string) => `哈囉，${name}！`

console.log(greet('世界'))
ts

常用的語言名稱有 js、ts、python、bash、json、yaml。如果像上面一樣要展示「程式碼區塊本身」，外層改用四個反引號包起來就好。

表格#

用 | 分隔欄位，第二行的冒號決定對齊方式：冒號在左邊是靠左，兩邊都有是置中，在右邊是靠右。

| 符號 | 用途 | 寫在哪裡 |
| :--- | :---: | ---: |
| `#` | 標題 | 行首 |
| `-` | 清單 | 行首 |
| `>` | 引用 | 行首 |
| `**` | 粗體 | 文字兩側 |
markdown
符號用途寫在哪裡
#標題行首
-清單行首
>引用行首
**粗體文字兩側

數學式#

數學式不是標準 Markdown 的一部分，是這個部落格透過 remark-math 和 KaTeX 另外支援的。行內公式用一個 $ 包起來，獨立的公式區塊用兩個 $$。

質能等價公式是 $E = mc^2$。

$$
\sum_{k=1}^{n} k = \frac{n(n+1)}{2}
$$
markdown

質能等價公式是 E=mc2E = mc^2。

∑k=1nk=n(n+1)2\sum_{k=1}^{n} k = \frac{n(n+1)}{2}

註腳#

Markdown 是 John Gruber 在 2004 年發表的[^1]。

[^1]: 最初的語法說明至今仍放在他的網站 Daring Fireball 上。
markdown

Markdown 是 John Gruber 在 2004 年發表的1。

註腳的內容會自動集中到文章最後面。

跳脫字元#

想顯示 Markdown 符號本身，在符號前面加反斜線 \ 就好：

\*這段文字不會變成斜體\*

2026\. 這行不會被當成有序清單。

價格從 \$100 漲到 \$200。
markdown

*這段文字不會變成斜體*

2026. 這行不會被當成有序清單。

價格從 $100 漲到 $200。

最後一個例子是這個部落格特有的地雷：因為開了數學式，同一段裡出現兩個 $，中間的文字就會被當成公式。寫金額時記得加上反斜線。

行內 HTML#

Markdown 不夠用的時候，可以直接寫 HTML：

按 <kbd>Ctrl</kbd> + <kbd>C</kbd> 複製。

<details>
<summary>點我展開</summary>

摺疊起來的內容，裡面一樣可以寫 **Markdown**。

</details>
markdown

按 Ctrl + C 複製。

點我展開

摺疊起來的內容，裡面一樣可以寫 Markdown。

注意 <details> 裡的 Markdown 要和 HTML 標籤之間空一行，才會被正確解析。

結語#

以上是寫部落格最常用的語法，日常寫作大概都夠用了。想看完整規格，可以參考 CommonMark 和 GitHub Flavored Markdown。

接下來，就開始寫正式的內容吧。

Footnotes#

  1. 最初的語法說明至今仍放在他的網站 Daring Fireball 上。 ↩

Markdown 語法指南
https://blog.zzy.tw/blog/markdown-syntax
© zzy · October 24, 2026