程式區塊的使用

在 Zensical 中，你可以使用 code blocks（程式區塊） 來顯示程式碼，並且支援 行號、語法高亮、標題 等功能。寫法與 Material for MkDocs 相同。

基本用法

Markdown 本身就有基本的 syntax highlighting。

原始程式

```python
print("Hello, Zensical!")
```

輸出結果

print("Hello, Zensical!")

✅ Zensical 會根據語言自動加上語法高亮！

進階功能

顯示行號（Line Numbers）

原始程式

```python linenums="1"
print("這是第一行")
print("這是第二行")
print("這是第三行")
```

輸出結果

1
2
3

print("這是第一行")
print("這是第二行")
print("這是第三行")

✅ 使用 linenums 來顯示行號！

高亮特定行數（Highlight Lines）

原始程式

```python hl_lines="1-2"
print("這行會被高亮")
print("這行也會被高亮")
print("這行不會")
```

輸出結果

print("這行會被高亮")
print("這行也會被高亮")
print("這行不會")

✅ 使用 hl_lines="1-2" 來高亮 1-2 行！

添加標題（Title）

原始程式

```python title="example.py"
print("這是 example.py 的內容")
```

輸出結果

print("這是 example.py 的內容")

✅ 使用 title="example.py" 來顯示標題！

隱藏複製按鈕

請先在 zensical.toml 啟用複製按鈕：

[project.theme]
features = [
  "content.code.copy",
]

原始程式

``` {.python .no-copy}
print("這是 example.py 的內容")
print("這行會被高亮")
```

輸出結果

print("這是 example.py 的內容")
print("這行會被高亮")

✅ 使用 {.no-copy} 來隱藏「複製」按鈕！

📌 反過來，如果沒有全域啟用 content.code.copy，也可以只在特定區塊使用 { .yaml .copy } 顯示複製按鈕。注意語言簡碼一定要放在最前面，而且要加上 .。若不想語法高亮，可以用 .text 當語言簡碼。

行內程式碼

如果只要在行內顯示程式碼，可以使用：

原始程式

內嵌 `print("Hello, Zensical!")` 在文字裡面！

輸出結果

內嵌 print("Hello, Zensical!") 在文字裡面！

📌 如果要 highlight 內嵌的程式，則使用 #! 加上程式語言的簡碼。請先啟用 pymdownx.inlinehilite。

原始程式

內嵌 `#!python print("Hello, Zensical!")` 在文字裡面！

輸出結果

內嵌 print("Hello, Zensical!") 在文字裡面！

選取行範圍按鈕

讓讀者可以自己選取一段行範圍，動態套用行高亮，適合拿來連結到程式區塊的某一小段。在 zensical.toml 啟用：

[project.theme]
features = [
  "content.code.select",
]

只想對特定區塊啟用（或停用）的話：

``` { .yaml .select }
# 程式區塊內容
```

``` { .yaml .no-select }
# 程式區塊內容
```

程式碼註解（Code annotations）

程式碼註解可以在程式區塊的特定位置加上編號標記，讀者點開後會浮出說明，說明內容可以是任意 Markdown（程式碼、格式化文字、圖片……）。先啟用：

[project.theme]
features = [
  "content.code.annotate",
]

在語言允許註解的地方（例如 JavaScript 的 //、/* */，YAML 或 TOML 的 #）放上 (1)，再在程式區塊後面用有序清單寫說明：

原始程式

``` toml
[project.theme]
features = [
  "content.code.annotate", # (1)!
]
```

1.  我是程式碼註解！可以放 `程式碼`、__格式化文字__，任何 Markdown 都可以。

輸出結果

[project.theme]
features = [
  "content.code.annotate", # (1)!
]

1. 我是程式碼註解！可以放 程式碼、格式化文字，任何 Markdown 都可以。

📌 只想對單一區塊啟用時，用 { .yaml .annotate }。

移除註解符號：在 (1) 後面加上 !，就會把外圍的註解符號（如 #）一起隱藏（每個註解只能放一個標記）。上面的範例 # (1)! 就使用了這個寫法。

自訂選擇器：預設只能把註解放在「註解」裡。如果需要放在字串中（例如 JSON），可以依語言額外指定 Pygments 的詞法選擇器：

[project.extra.annotate]
json = [".s2"]

.s2 是 Pygments 替雙引號字串產生的詞法名稱。

嵌入外部檔案

啟用 pymdownx.snippets 之後，可以在程式區塊裡用 --8<-- 直接嵌入其他檔案的內容（包含原始碼檔案）：

``` title=".browserslistrc"
--8<-- ".browserslistrc"
```

這樣程式範例就能直接引用實際會被執行的檔案，不必手動複製貼上，避免文件與程式碼不同步。

自訂語法高亮顏色

程式區塊的顏色是用 CSS 變數定義的，在 extra.css 覆寫就可以了：

:root > * {
  --md-code-hl-string-color: #0FF1CE;
}

可用的變數：

如果只想改特定種類的字串（例如反引號字串），可以查出 Pygments 產生的 CSS class（例如 .highlight .sb）再覆寫。

註解提示框的寬度：註解內容很多時，可以加寬提示框：

:root {
  --md-tooltip-width: 600px;
}

總結

參考資料

• Code blocks - Zensical