若要完整顯示一行很長的 Markdown 程式碼，請保留程式碼原樣並調整其呈現方式。本指南協助 Mac 使用者診斷範例遭截斷的情況、在 Obsidian 閱讀檢視中啟用自動換行，並了解這些設定對 GitHub 的影響。
哪些因素會決定程式碼行是否換行？
圍欄式程式碼區塊會將程式碼保留為字面內容。CommonMark 定義了圍欄的起始與結束方式，以及如何剖析其內容；它沒有提供可攜式的長行換行開關。其目前規格為 0.31.2 版。CommonMark 規格，圍欄式程式碼區塊。
GitHub Flavored Markdown 遵循相同的基本圍欄式區塊規則。其規格同樣未要求在圍欄的資訊字串中加入換行指示。因此，在語言名稱後加上 wrap，並不能確立可攜式的換行行為。已發布的 GFM 規格標示為 0.29-gfm 版；請勿將此版本號與目前的 CommonMark 版本混淆。GitHub Flavored Markdown 規格。
在此任務中，請區分以下三種結果：
| 結果 | 讀者看到的內容 | 是否需要修改範例原始碼？ |
|---|---|---|
| 視覺換行 | 一行原始碼分成多個顯示行 | 否 |
| 水平捲動 | 該行延伸至可視範圍之外，但仍可檢視 | 否 |
| 手動換行 | 範例包含額外的原始碼行 | 是 |
若想在窗格中完整看到整行，實用的選擇是自動換行；若要保留視覺對齊，則可使用捲動。手動換行則需要另外確認範例的意義是否仍然相同。
CSS 明確區分了原始碼與呈現方式：空白處理會影響畫面呈現，但不會改變底層文件資料。因此，若範例必須維持為一行以便複製，視覺換行是很好的起點。CSS 文字模組第 3 級。
先確認範例是缺漏，還是僅在可視範圍之外
在編輯長命令或運算式之前，先檢查原始碼。在 Obsidian 中，使用編輯模式控制項選取 Source mode。若要在 Mac 上與呈現結果比較，可按 Cmd+E 在編輯模式與 Reading view 之間切換。Obsidian 將這些檢視模式與編輯模式 Live Preview 區分開來。檢視模式與編輯模式。
請在另一則筆記中使用這個合成測試。複製其中的 Markdown 內容，包含開頭與結尾的三個反引號行。此內容刻意使用一般文字，並非要執行的命令。
```text
BEGIN sample=amber notebook=desktop layout=wide description=This synthetic example contains a deliberately long line so you can check whether the final marker remains visible when the note pane becomes narrow END
```
縮窄筆記窗格，並尋找 END。若它出現在接續的下一行，代表自動換行正常運作。若在區塊內水平移動後能看到它，則表示可透過捲動檢視該內容。若仍無法找到，請先比較呈現後的區塊與原始碼，再判斷文字是否遭到刪除。
此測試可區分兩種需要不同修正方式的問題：原始碼內容缺漏時，需要還原範例；內容存在但無法檢視時，則需要調整顯示方式。嘗試設定時請保持測試內容不變，這樣才能確認改善是由哪項設定變更造成的。
也請檢查圍欄。結尾圍欄必須使用與起始圍欄相同的字元，且字元數不得少於起始圍欄。範例內若有相符的圍欄，可能會提早關閉區塊。CommonMark 規格，圍欄式程式碼區塊。教學說明 Markdown 語法時，可用四個反引號的外層圍欄顯示內含三個反引號的區塊，如上所示。建立及醒目標示程式碼區塊。
先擴大 Obsidian 筆記的可用空間，再新增 CSS
開啟 Settings → Editor，找到 Readable line length。Obsidian 說明此設定會限制行長上限。暫時將其關閉，再於相同視窗大小下比較同一則測試筆記。這是調整寬度的設定；文件並未將其描述為程式碼區塊的換行開關。設定。
若現在能完整看到範例，調整寬度或許足以符合你的桌面版面需求。確定採用之前，請先測試較窄的窗格：某種視窗配置有更多空間，並不能說明在其他配置下該行是否仍易於閱讀。
請勿將 Strict line breaks 當作修正程式碼溢出的方法。Obsidian 說明此設定與 Markdown 換行有關，而圍欄式程式碼會被視為字面內容。它處理的是不同的格式問題。設定、CommonMark 規格，圍欄式程式碼區塊。
在 Obsidian 閱讀檢視中換行顯示長程式碼行
若要套用於指定筆記，請使用 Obsidian 說明的 CSS 片段機制及其 cssclasses 屬性。以下是根據該機制與標準 CSS 行為編寫的自訂設定，適用於 Reading view 中一般呈現的圍欄式區塊；它不是 Obsidian 提供的換行預設，也不是編輯模式的設定。CSS 片段。
建立並啟用片段
- 開啟
Settings→Appearance→CSS snippets。 - 選取
Open snippets folder。 - 在純文字編輯器中，於該資料夾建立
wrap-code.css，並儲存以下 CSS。 - 返回
CSS snippets，選取Reload snippets，然後啟用wrap-code。
這些是 Obsidian 說明的桌面版安裝步驟。啟用後，通常會自動套用已儲存的片段變更。CSS 片段。
.wrap-code pre,
.wrap-code pre code {
white-space: pre-wrap;
overflow-wrap: anywhere;
word-break: normal;
}
在測試筆記開頭加入這個屬性區塊。若筆記已有屬性，請將 wrap-code 加入現有的 cssclasses 值中，不要再插入第二個屬性區塊。
---
cssclasses:
- wrap-code
---
Obsidian 說明 cssclasses 可用來將自訂 CSS 套用至指定筆記。在此設定中，.wrap-code 將規則限制於這些筆記；其餘選擇器則以呈現後的預先格式化區塊及其中的程式碼內容為目標。此規則不會設定編輯介面。CSS 片段。
了解 CSS 的變更內容
white-space: pre-wrap 宣告會保留空白與原始碼換行，同時允許視覺換行。overflow-wrap: anywhere 宣告也允許原本無法斷開的字串在必要時換行，而且不會插入連字號。兩者合用，可處理含空格的長行及沒有空格的長字串。CSS 文字模組第 3 級、overflow-wrap CSS 屬性。
請勿以 white-space: normal 取代：這個值會合併空白，可能改變你想保留的視覺縮排。此外，單獨使用 overflow-wrap 無法克服禁止換行的空白規則。white-space CSS 屬性、CSS 文字模組第 3 級。
返回 Reading view，縮窄窗格，並再次檢查 END。接著將測試內容複製到純文字編輯器，與原文比較。預期結果是：同一行原始碼分成多個顯示行。此複製檢查可確認目前安裝的呈現器與佈景主題實際如何運作。
注意呈現器之間的差異
Obsidian 的外觀自訂設定不會成為圍欄式區塊可攜式 Markdown 語法的一部分。將範例移至其他地方時，請獨立測試目的地。請依照以下比較，判斷需要檢查的項目：
| 目的地 | 可依據的內容 | 需另行確認的內容 |
|---|---|---|
| CommonMark 實作 | 文件說明的圍欄式區塊剖析方式 | 換行、捲動及可用顯示寬度 |
| GitHub 呈現的 Markdown | GitHub 文件說明的圍欄與語言識別碼 | 目的地實際的程式碼區塊呈現方式 |
Obsidian Reading view |
呈現後的筆記與已啟用的本機樣式 | 片段是否適用於目前的佈景主題 |
Obsidian Live Preview 或 Source mode |
所選的編輯模式 | 編輯器的呈現方式；上述片段不會設定此模式 |
語法的適用範圍依據CommonMark 規格、GitHub 的程式碼區塊文件及 Obsidian 的檢視模式文件。
GitHub 說明，開頭圍欄後的語言識別碼可啟用語法醒目標示。因此，將 text 改成其他語言識別碼，並不是文件記載的換行要求方式。請為範例保留正確的識別碼，並在負責呈現的工具中處理顯示方式。建立及醒目標示程式碼區塊。
若無法控制目的地的呈現方式，請在保留完整行並使用目的地提供的導覽方式，以及將範例改寫成有效的較短原始碼行之間做選擇。改寫必須遵循範例使用的語言或格式；Markdown 圍欄無法讓任意插入的換行變得有效。
排解問題時，別刪掉必要內容來縮短範例
如果 Obsidian 規則看起來沒有作用，請依序檢查：
- 確認目前使用的是
Reading view。 - 確認
wrap-code.css出現在CSS snippets中，且已啟用。 - 確認筆記的
cssclasses恰好包含wrap-code。 - 在檢視內容未變更的測試筆記時，關閉再重新啟用片段。
- 如有需要，暫時停用其他片段，並與 Obsidian 預設佈景主題比較，以找出樣式衝突。
- 在判定任務完成前，使用實際範例重做測試。
請將此選擇器規則視為需要在你的安裝環境中驗證的自訂設定。佈景主題或專用區塊呈現器可能採用不同的樣式或結構。若一般圍欄測試有效，但實際區塊無效，這項差異就是有用的線索：請調查實際區塊使用的呈現器，而不是貿然加入換行。
最後檢查時，請確認可檢視最後一個字元、縮排仍清楚易懂、複製的文字符合預期原始碼，且範例在預定閱讀的檢視模式中可正常使用。保留完整原始碼，審慎選擇自動換行或捲動，並測試所有重要的目的地。
資料來源
- CommonMark 規格 — CommonMark
- GitHub Flavored Markdown 規格 — GitHub
- 建立及醒目標示程式碼區塊 — GitHub 文件
- 檢視模式與編輯模式 — Obsidian
- 設定 — Obsidian
- CSS 片段 — Obsidian
- CSS 文字模組第 3 級 — W3C
- white-space CSS 屬性 — MDN Web 文件
- overflow-wrap CSS 屬性 — MDN Web 文件