撰寫正確的 Markdown
雖然 Markdown 是很寬鬆的標記語言但還是內藏玄機，本文分兩個重點介紹，一是好讀的 Markdown，二是正確的 Markdown。
好讀的 Markdown
TL;DR: 用 linter 幫你排版。
Linter 意指軟體開發時的檢測工具，使用 markdownlint 基本上就完全不需要對好讀這件事耗費功夫，筆者使用的 linter 是 rumdl1，使用 VS Code 編輯時可以用同作者寫的插件 rumdl-vscode，之後就再也不需要為 Markdown 排版浪費時間，保證你寫的格式永遠相同。
這裡是筆者的 rumdl 設定檔：
# rumdl configuration file
# Last updated: 0.1.82
# Global configuration options
[global]
# List of rules to disable
disable = [
# "MD002", # First header should be a h1 header
"MD003", # Heading style - conflict with mermaid syntax
"MD004", # List marker '+' does not match expected style, conflict LaTeX
"MD013", # Line length
"MD025", # Multiple top level headers
"MD026", # Trailing punctuation in header
"MD028", # Blank line inside blockquote
"MD029", # Ordered list item prefix
"MD031", # Code blocks should be surrounded by blank lines
"MD032", # List marker '+' does not match expected style, conflict LaTeX
"MD033", # Inline HTML
"MD034", # Bare URL used
"MD036", # Emphasis used instead of a header
"MD041", # First line in file should be a top level header
"MD046", # Code block style
"MD059", # Link text should be descriptive
"MD060", # Table column style
]
# Opt-in rules (disabled by default): MD060, MD063, MD070, MD072, MD073, MD074
# extend-enable = ["MD060", "MD063", "MD072", "MD073", "MD074"]
# Rules that survive CLI --disable overrides
# extend-disable = []
# List of file/directory patterns to exclude from linting
exclude = [
# Common directories to exclude
".git",
".github",
"node_modules",
"vendor",
"dist",
"build",
"themes",
# Specific files or patterns
"CHANGELOG.md",
"LICENSE.md",
]
# Markdown flavor/dialect
# Options: standard (default), gfm, commonmark, mkdocs, kramdown, jekyll, mdx, quarto
flavor = "gfm"
[MD004]
style = "dash" # Unordered list style
[MD024]
siblings-only = true # Multiple headers with the same content
[MD049]
style = "asterisk" # Emphasis style
[MD050]
style = "asterisk" # Strong style
[MD057]
absolute-links = "relative_to_roots"
roots = ["exampleSite/content/en", "exampleSite/content/zh-cn", "assets"]
連結小技巧
一般連結的語法是 [text](URL)，但是 Markdown 其實有類似 Tex footnote 的語法：
[text][ID]
[ID]: URL
這在當同一行需要多個連結時非常好用，否則整行都是連結難以編輯和閱讀2。
中英數字夾雜
拜託加上空白，求你了，沒加真的超醜。
- 但是 Markdown 其實有類似 Tex footnote 的語法
- 但是Markdown其實有類似Tex footnote的語法
你可以用盤古之白這種工具完成，不過筆者習慣手動加入。
正確的 Markdown
首先我們要知道 Markdown 其實是有規範的，規範他的組織是 CommonMark，大多數 Markdown 工具都會都會照規範實現，你可以到 CommonMark dingus 測試本段內容。
換行方式
以 Markdown 新手第一天一定會遇到的換行問題，Markdown 有兩種換行方式：雙空白和空行，你可能會發現以空行方式換行兩行之間的距離會更遠，但是又不是每個網站主題都會這樣，原因要用 CommonMark 來解釋，CommonMark 規範他們應該被渲染成這樣的 HTML：
-
以雙空白換行
line1
line2<p>line1<br />
line2</p> -
以空行換行
line1
line2<p>line3</p>
<p>line4</p>
發現了嗎？差別在於使用 <br> 和 <p> 標籤，這在 HTML 上是不同語意：p 標籤代表一個獨立段落，br 則變成在一個段落之中換行。即使你對於 HTML 語意 don't give it a fuck，但這影響最大的是排版，一般來說 CSS 都會設定 p 標籤帶有上下間距 (padding)，因此空行的換行距離通常更遠。
用字選「一般來說」和「通常更遠」代表不是所有人都這樣設定 CSS，所有 CSS 框架全部都有 padding，但是 Hugo 最知名的主題 PaperMod 就沒有，這會讓作者和讀者都誤解語意，因為你的換行和換段落沒有任何差別。
帶有多行的列表項目
換行是非常基本的範例，而列表就比較少人知道了。有了前面的基礎知識這邊就不再慢慢介紹，直接說結論：如果你的列表「其中一項需要多行」，而你沒有幫他加上四個空白，或是多了空行，渲染出的 HTML 就和你預期的不一樣。
-
情況一：沒有加上四個空白
比如說
1. A
2. B
```sh
echo 123
```
3. C這樣寫的人心理預期他是「一個有序列表，第二項包含一個 code block」，然而實際上會渲染出「兩個有序列表，第二個列表從 3 開始」。正確寫法應該是：
1. A
2. B
```sh
echo 123
```
3. C -
情況二：多了空行
MD031 規則會幫你在 code block 前後加上空行，照他的建議你的 code block 會被自動修正成
1. A
2. B
```sh
echo 123
```
3. C這會讓每個 list item 從
<li>A</li>變成<li><p>A</p></li>，多了 p 標籤導致距離變寬。