開始挑戰鐵人賽之前，我在使用 Notion時有稍微接觸過 Markdown 語法，但實際在 iThome 編輯器撰寫技術文章時，偶爾還是會遇到「內容呈現出來跟我想的不一樣」的狀況。例如程式碼範圍不對、表格跑版等。
因此，我決定在賽程中稍微停下腳步，好好認識 Markdown 語法並整理這份筆記，希望幫助自己在之後的技術寫作能更順暢，也分享給遇到相同困擾的朋友。
(不知道大家有沒有看過markdown的logo？也是十分簡潔呢（笑）)
Markdown是一種 輕量級標記式語言（Lightweight Markup Language）。
簡單來說，它是一種可以用純文字快速排版的格式，並且能直接轉換成 HTML 網頁呈現。
它的好處是讓你在寫文章時，雙手不需要離開鍵盤去用滑鼠點擊調整字體大小或顏色，就能產出結構清晰、閱讀體驗極佳的文件。
以下是撰寫技術文章時常使用的基本語法：
#的數量代表標題 H1 ~ H6，#後面必須空一格。
aria_carrot
# 標題H1
## 標題H2
### 標題H3
#### 標題H4
##### 標題H5
###### 標題H6
渲染效果：
*斜體文字*
**粗體文字**
***斜體兼粗體***
~~刪除線~~
渲染效果：
斜體文字
粗體文字
斜體兼粗體刪除線
適合用在補充說明、作筆記、或是引用資料時，在段落開頭加上 > 符號：
> 這是一段引用文字。
> 可以連續多行使用。
>> 甚至還可以做嵌套引用！
渲染效果：
這是一段引用文字。
可以連續多行使用。甚至還可以做嵌套引用！
建立一條水平分隔線，可以使用三個以上的 -、* 或短線加空格：
---
***
- - -
* * *
- 無序清單項目 A
- 無序清單項目 B
* 也可以用星號作為無序清單
1. 有序清單第一步
2. 有序清單第二步
渲染效果：
行內程式碼： 使用單個反引號 ` 包住內容，例如：let x = 10;
程式碼區塊： 使用三個反引號 ``` 包裹，並可指定程式語言：
渲染效果：
```javascript
function greet() {
console.log("Hello, iThome!");
}
```
[iThome 官網](https://www.ithome.com.tw/)
渲染效果：
iThome 官網
在實際使用時，有些眉眉角角是我第一時間沒有發現的，所以特別記錄下來。如果大家有遇到相同的問題可以參考；之後如果還有發現新問題，我也會持續更新補充。
之前發現有些段落明明我沒有寫反引號，呈現出來卻突然變成了灰色背景的程式碼區塊。
檢查了很多次都找不到哪裡多寫了符號，後來查了資料才發現：在 Markdown 的標準語法中，段落開頭只要縮排 4 個空格（或按一個 Tab），解析器就會自動判定為「縮排程式碼區塊（Indented Code Block）」。
問題： 想做段落縮排，結果文字全變成了程式碼樣式。
解決方式： Markdown 通常不需要特別做首行縮排；撰寫時請直接開頭寫字，注意開頭不要空 4 個空格。
有一次想用表格呈現資訊，因為不想要顯示表頭，就把範例裡的標題與分隔線刪掉，結果發現渲染出來後只剩下混在一起的純文字。
原生 Markdown 的表格結構非常嚴格，如果需要更複雜、無表頭的設計，原生 Markdown 比較難達成，建議維持標準範例格式撰寫。
範例：
姓名 | 住址
------------- | -------------
李大華 | 桃園
張小明 | 高雄
渲染效果：
| 姓名 | 住址 |
|---|---|
| 李大華 | 桃園 |
| 張小明 | 高雄 |
有時候文章會用到星號 *、井號 # 或反引號 ` 等符號，但我們只是想當作一般的純文字顯示，不想觸發 Markdown 的排版功能。
這種時候，只要在該符號前方加上反斜線 \ 進行轉義即可：
\`這是一段帶有反引號的文字\`
渲染效果：
`這是一段帶有反引號的文字`
在撰寫這篇語法整理筆記時，我遇到了「要在程式碼區塊內展示 ``` 語法」的問題。一開始外層用三個反引號包住時會跑版。
後來發現：只要在外層使用「4 個反引號（````）」包裹，內層就能正常展示「3 個反引號」的程式碼區塊了。
```
示範整段程式碼的markdown語法
```
建立文章目錄可以讓讀者（以及自己查閱時）快速點擊跳轉，產生目錄有以下兩種方法：
(1) 手動建立頁內跳轉（錨點連結）
語法格式為 [顯示文字](#標題id)。標題 ID 的規則通常是：轉為小寫、移除特殊符號，並將空格改為連字號 -。
* [一、什麼是 Markdown？](#一什麼是-markdown)
* [二、常用的語法](#二常用的語法)
* [標題 H1~H6 (Headings)](#標題-h1h6-headings)
渲染效果：
(2) 自動產生目錄標籤（平台擴充語法）
在部分支援擴充語法的平台（如 HackMD、GitHub 等），可以直接在想插入目錄的地方輸入以下[TOC]，解析器就會自動根據文章內的所有標題（H1~H6）生成完整目錄：
注意：iThome 目前不支援自動解析 [TOC]。
Notion：支援 Markdown 快捷鍵（如輸入 # 自動變標題）。
Discord / Slack：聊天時可用 // 做粗體或以 ` 標示程式碼。
HackMD：台灣技術圈非常熱門的實時協作 Markdown 文件平台。
GitHub / GitLab：專案的核心說明文件 README.md 全採用 Markdown 撰寫。
iThome 編輯器：撰寫與發布技術文章的最佳利器。
iThome鐵人賽
看影片追技術