Markdown 與 Visual Studio Code
在 Visual Studio Code 中處理 Markdown 檔案既簡單、直覺又有趣。除了 VS Code 的基本編輯功能外，還有幾個專為 Markdown 設計的功能可協助您大幅提升生產力。
注意：為了協助您開始編輯 Markdown 檔案，您可以使用文件撰寫者設定檔範本來安裝實用的擴充功能 (拼字檢查工具、Markdown linter) 並設定適當的設定值。
編輯 Markdown
文件大綱
「大綱」檢視是「檔案總管」底部的一個獨立區段。展開時，它會顯示目前使用中編輯器的符號樹狀結構。對於 Markdown 檔案而言，符號樹狀結構就是 Markdown 檔案的標題階層。
「大綱」檢視是檢閱文件標題結構與大綱的好方法。
Markdown 程式碼片段
VS Code 內含一些實用的程式碼片段，可加快編寫 Markdown 的速度。這包括程式碼區塊、圖片等的程式碼片段。在編輯時按下 ⌃Space (Windows, Linux Ctrl+Space) (觸發建議) 以查看建議的 Markdown 程式碼片段清單。您也可以在命令選擇區中選取插入程式碼片段來使用專屬的程式碼片段選擇器。
提示：您可以為 Markdown 新增自己的使用者定義程式碼片段。請參閱使用者定義程式碼片段以了解如何操作。
前往檔案中的標題
使用 ⇧⌘O (Windows, Linux Ctrl+Shift+O) 快速跳至目前檔案中的標題。
您可以瀏覽檔案中的所有標題，或開始輸入標題名稱來尋找您要的標題。一旦找到所需的標題，請按下 Enter 將游標移至該處。按下 Esc 即可取消跳至標題。
前往工作區中的標題
使用 ⌘T (Windows, Linux Ctrl+T) 搜尋目前工作區中所有 Markdown 檔案的標題。
開始輸入標題名稱以篩選清單並尋找您要的標題。
路徑自動完成
路徑自動完成有助於建立指向檔案和圖片的連結。當您輸入圖片或連結的路徑時，IntelliSense 會自動顯示這些路徑，您也可以使用 ⌃Space (Windows, Linux Ctrl+Space) 手動要求。
以 / 開頭的路徑會相對於目前的工作區根目錄解析，而以 ./ 開頭或沒有任何字首的路徑則會相對於目前的檔案解析。當您輸入 / 時，會自動顯示路徑建議，或者您可以透過使用 ⌃Space (Windows, Linux Ctrl+Space) 手動叫用。
Path IntelliSense 也可以協助您連結至目前檔案或其他 Markdown 檔案內的標題。以 # 開頭路徑即可看到該檔案中所有標題的自動完成 (根據您的設定，您可能需要使用 ⌃Space (Windows, Linux Ctrl+Space) 才能看到這些內容)
您可以使用 "markdown.suggest.paths.enabled": false 來停用路徑 IntelliSense。
建立指向另一個檔案中標題的連結
需要連結至另一份 Markdown 文件中的標題，但記不得或不想打出完整檔案路徑？試試看工作區標題自動完成！若要開始，只需在 Markdown 連結中輸入 ## 即可查看目前工作區中所有 Markdown 標題的清單
接受其中一個自動完成以插入該標題的完整連結，即使它在另一個檔案中也一樣
您可以使用 markdown.suggest.paths.includeWorkspaceHeaderCompletions 設定來設定是否/何時顯示工作區標題自動完成。有效的設定值為
onDoubleHash(預設值)——只有在您輸入##後才顯示工作區標題自動完成。onSingleOrDoubleHash——在您輸入#或##後顯示工作區標題自動完成。never——絕不顯示工作區標題自動完成。
請記住，尋找目前工作區中的所有標題可能會耗費較多資源，因此第一次要求時可能會有些許延遲，特別是包含大量 Markdown 檔案的工作區。
插入圖片與檔案連結
除了路徑自動完成外，VS Code 還支援其他幾種將圖片和檔案連結插入 Markdown 文件中的方法
您可以從 VS Code 的檔案總管或作業系統拖放檔案至 Markdown 編輯器中。首先從 VS Code 的檔案總管將檔案拖曳到您的 Markdown 程式碼上，然後按住 Shift 開始將其放置到檔案中。預覽游標會顯示放開時要插入的位置。
如果您偏好使用鍵盤，也可以將檔案或圖片資料複製並貼上至 Markdown 編輯器中。當您貼上檔案、檔案連結或 URL 時，您可以選擇插入 Markdown 連結或將連結包含為純文字。
或者您可以使用 Markdown: Insert Image from Workspace 命令來插入圖片，以及使用 Markdown: Insert Link to File in Workspace 來插入檔案連結。
插入的圖片會使用 Markdown 圖片語法 。連結則會插入一般的 Markdown 連結 [](path/to/file.md)。
根據預設，VS Code 會自動將工作區外部拖放或貼上的圖片複製到您的工作區中。 markdown.copyFiles.destination 設定可控制應在何處建立新的圖片檔案。此設定將符合目前 Markdown 文件的 glob 模式對應至圖片目的地。圖片目的地也可以使用一些簡單的變數。如需可用變數的相關資訊，請參閱 markdown.copyFiles.destination 設定描述。
例如，如果您希望工作區中 /docs 下的每個 Markdown 檔案都將新的媒體檔案放入該目前檔案專屬的 images 目錄中，您可以寫成
"markdown.copyFiles.destination": {
"/docs/**/*": "images/${documentBaseName}/"
}
現在，當新檔案貼到 /docs/api/readme.md 時，會在 /docs/api/images/readme/image.png 建立圖片檔案。
您甚至可以使用簡單的常規表示式，以類似程式碼片段的方式轉換變數。例如，此轉換在建立媒體檔案時僅使用文件檔名的第一個字母
"markdown.copyFiles.destination": {
"/docs/**/*": "images/${documentBaseName/(.).*/$1/}/"
}
當新檔案貼到 /docs/api/readme.md 中時，圖片現在會在 /docs/api/images/r/image.png 下建立。
為圖片產生替代文字 (alt text)
您可以使用 AI 為 Markdown 檔案中的圖片產生或更新替代文字。若要產生替代文字
-
請確定您已在 VS Code 環境中設定 Copilot。您可以免費開始使用 Copilot。
-
開啟 Markdown 檔案。
-
將游標放在圖片連結上。
-
選取「程式碼動作」(燈泡) 圖示，然後選取產生替代文字。
-
如果您已經有替代文字，請選取「程式碼動作」，然後選取精進替代文字。
智慧選取
智慧型選取可讓您在 Markdown 文件中快速擴充和縮小選取範圍。這可以用來快速選取整個區塊元素 (例如程式碼區塊或表格)，以及選取 Markdown 檔案中標題區段的完整內容。
智慧型選取使用以下命令
- 擴大選取：⌃⇧⌘→ (Windows, Linux Shift+Alt+Right)
- 縮小選取：⌃⇧⌘← (Windows, Linux Shift+Alt+Left)
選取範圍適用於下列項目，並遵循傳統的階層模式
- 標題
- 清單
- 區塊引文
- 包圍式程式碼區塊
- HTML 程式碼區塊
- 段落
連結驗證
連結驗證會檢查 Markdown 程式碼中的本機連結，以確保它們有效。這有助於攔截常見的錯誤，例如連結到已重新命名的標題，或磁碟上已不存在的檔案。
連結驗證預設為關閉。若要啟用它，請設定 "markdown.validate.enabled": true。接著，VS Code 會分析指向標題、圖片和其他本機檔案的 Markdown 連結。無效的連結會回報為警告或錯誤。所有連結驗證都在本機進行，且不會檢查外部的 http(s) 連結。
您可以使用下列幾種設定來客製化連結驗證：
- markdown.validate.fileLinks.enabled - 啟用/停用指向本機檔案之連結的驗證：
[link](/path/to/file.md) - markdown.validate.fragmentLinks.enabled - 啟用/停用指向目前檔案中標題之連結的驗證：
[link](#_some-header) - markdown.validate.fileLinks.markdownFragmentLinks - 啟用/停用指向其他 Markdown 檔案中標題之連結的驗證：
[link](other-file.md#some-header) - markdown.validate.referenceLinks.enabled - 啟用/停用參照連結的驗證：
[link][ref]。 - markdown.validate.ignoredLinks - 略過驗證的連結 glob 列表。如果您連結到磁碟上不存在但在發佈 Markdown 後存在的檔案，這會非常有用。
尋找標題和連結的所有參考
使用 Find All References (⇧⌥F12 (Windows, Linux Shift+Alt+F12)) 命令來尋找目前工作區中參考了 Markdown 標題或連結的所有位置
Find All References 支援下列項目：
- 標題：
# My Header。顯示指向#my-header的所有連結。 - 外部連結：
[text](http://example.com)。顯示指向http://example.com的所有連結。 - 內部連結：
[text](./path/to/file.md)。顯示指向./path/to/file.md的所有連結 - 連結中的片段：
[text](./path/to/file.md#my-header)。顯示./path/to/file.md中指向#my-header的所有連結
重新命名標題與連結
厭倦了變更 Markdown 標題時意外損毀連結嗎？請嘗試改用 Rename Symbol (F2)。輸入新的標題名稱並按下 Enter 後，VS Code 會更新標題並自動更新指向該標題的所有連結
您也可以在下列項目上使用 F2：
- 標題：
# My Header。這會更新指向#my-header的所有連結。 - 外部連結：
[text](http://example.com/page)。這會更新所有連結至http://example.com/page的地方 - 內部連結：
[text](./path/to/file.md)。這會重新命名檔案./path/to/file.md，同時也會更新所有指向它的連結。 - 連結中的片段：
[text](./path/to/file.md#my-header)。這會重新命名./path/to/file.md中的標題，同時也會更新所有指向它的連結。
移動或重新命名檔案時自動更新連結
透過自動 Markdown 連結更新功能，每當被連結的檔案被移動或重新命名時，VS Code 會自動更新 Markdown 連結。您可以使用 markdown.updateLinksOnFileMove.enabled 設定來啟用此功能。有效的設定值為
never(預設值) — 不嘗試自動更新連結。prompt— 更新連結前進行確認。always— 自動更新連結而不需確認。
自動連結更新會偵測 Markdown 檔案、圖片和目錄的重新命名。您可以使用 markdown.updateLinksOnFileMove.include 為其他檔案類型啟用此功能。
Markdown 預覽
VS Code 內建支援 Markdown 檔案。您只需開始撰寫 Markdown 文字，將檔案儲存為 .md 副檔名，然後就可以在程式碼與 Markdown 檔案的預覽之間切換編輯器的檢視畫面；當然，您也可以開啟現有的 Markdown 檔案並開始處理。若要在檢視畫面之間切換，請在編輯器中按下 ⇧⌘V (Windows, Linux Ctrl+Shift+V)。您可以並排檢視預覽畫面 (⌘K V (Windows, Linux Ctrl+K V)) 與您正在編輯的檔案，並在編輯時即時看到變更反映出來。
以下是簡單檔案的範例。
提示：您也可以在編輯器分頁上按一下滑鼠右鍵並選取開啟預覽 (⇧⌘V (Windows, Linux Ctrl+Shift+V))，或使用命令選擇區 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 來執行 Markdown: Open Preview to the Side 命令 (⌘K V (Windows, Linux Ctrl+K V))。
動態預覽與預覽鎖定
根據預設，Markdown 預覽會自動更新以預覽目前使用中的 Markdown 檔案
您可以使用 Markdown: Toggle Preview Locking 命令來鎖定 Markdown 預覽，使其保持鎖定在目前的 Markdown 文件。鎖定的預覽會在標題中以 [預覽] 表示
注意：只有在 Markdown 預覽為使用中的分頁時，Markdown: Toggle Preview Locking 命令才可用。
編輯器與預覽同步
VS Code 會自動同步 Markdown 編輯器與預覽窗格。捲動 Markdown 預覽時，編輯器也會跟著捲動以符合預覽的檢視區。捲動 Markdown 編輯器時，預覽也會跟著捲動以符合其檢視區
您可以使用 markdown.preview.scrollPreviewWithEditor 和 markdown.preview.scrollEditorWithPreview 設定來停用捲動同步。
編輯器中目前選取的行會在 Markdown 預覽中以左側邊界中的淺灰色橫條表示
此外，按兩下 Markdown 預覽中的元素將會自動開啟該檔案的編輯器，並捲動至最接近所按元素的行。
差異檢視中的 Markdown 預覽
Markdown 預覽也可以呈現差異，顯示已呈現且反白顯示變更的文件，而不是原始的 Markdown 原始程式碼。
此行為為選擇性啟用。您可以將單一差異切換至預覽，或變更用於 Markdown 差異的預設編輯器。
在 Markdown 預覽中開啟單一差異
若要將已開啟的 Markdown 差異 (例如從原始檔控制檢視開啟的檔案) 切換至呈現的預覽
- 在差異編輯器使用中的情況下，從命令選擇區 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 執行 View: Reopen Editor With...。
- 選取Markdown 預覽。
若要切換回來，請再次執行 View: Reopen Editor With... 並選取預設文字編輯器。
將 Markdown 預覽設定為預設編輯器
若要將 Markdown 預覽設定為所有 .md 檔案 (包括差異) 的預設編輯器，請設定 workbench.editorAssociations 設定
"workbench.editorAssociations": {
"*.md": "vscode.markdown.preview.editor"
}
透過此設定，從檔案總管開啟 Markdown 檔案或從原始檔控制開啟 Markdown 差異時，預設會開啟呈現的預覽。您仍然可以使用 View: Reopen Editor With... 將個別編輯器切換回文字檢視。
僅將 Markdown 預覽用於差異
若只要在預覽中呈現 Markdown 差異，同時保持在文字編輯器中開啟一般檔案，請使用 workbench.diffEditorAssociations 設定
"workbench.diffEditorAssociations": {
"*.md": "vscode.markdown.preview.editor"
}
對於差異檢視，workbench.diffEditorAssociations 的優先順序高於 workbench.editorAssociations。您可以結合這兩項設定，使預覽成為一般檔案開啟的預設值，同時將差異保持在文字編輯器中
"workbench.editorAssociations": {
"*.md": "vscode.markdown.preview.editor"
},
"workbench.diffEditorAssociations": {
"*.md": "default"
}
內嵌與並排版面配置
Markdown 差異預覽支援並排與內嵌版面配置，就像文字差異編輯器一樣。切換版面配置會更新您所開啟任何新 Markdown 差異編輯器的預設值。
在並排預覽中，兩個編輯器會保持捲動同步，以便在您捲動時讓相符的內容保持對齊。變更的行會反白顯示，而行內的變更則會更強烈地反白顯示，以突顯修改過的確切字詞或片語。
Mermaid 圖表呈現
VS Code 內建的 Markdown 預覽會在 mermaid 包圍式程式碼區塊中呈現 Mermaid 圖表。
```mermaid
flowchart LR
Sleep[Sleep] --> Wake{Awake?}
Wake -->|No| Sleep
Wake -->|Hungry| Snack[Get treat]
Wake -->|Not in sunbeam| Move[Move to sunbeam]
Wake -->|Human is typing| Keyboard[Sleep on keyboard]
Snack --> Sleep
Move --> Sleep
Keyboard --> Sleep
```
在呈現的預覽中，您可以平移和縮放較大的圖表以便在原處檢查它們。根據預設，滑鼠導覽會使用 Alt (macOS 上為 Option)：按住它並拖曳以平移、捲動以縮放，或按一下圖表以放大。按住 Alt+Shift 並按一下以縮小。您也可以使用雙指捏合手勢來縮放，而不需按住 Alt。
將滑鼠懸停或聚焦在圖表上以顯示控制項，可用於切換平移模式、放大、縮小以及重設平移與縮放。開啟已呈現圖表的內容功能表，然後選取複製圖表原始程式碼來複製其 Mermaid 原始程式碼。
數學公式呈現
VS Code 內建的 Markdown 預覽會使用 KaTeX 來呈現數學方程式。
內嵌數學方程式包在單一錢字號中
Inline math: $x^2$
您可以使用雙錢字號建立數學方程式區塊
Math block:
$$
\displaystyle
\left( \sum_{k=1}^n a_k b_k \right)^2
\leq
\left( \sum_{k=1}^n a_k^2 \right)
\left( \sum_{k=1}^n b_k^2 \right)
$$
您可以設定 "markdown.math.enabled": false 來停用 Markdown 檔案中數學公式的呈現。
擴充 Markdown 預覽
擴充功能可以為 Markdown 預覽提供自訂樣式和指令碼，以變更其外觀並新增功能。以下是一組自訂預覽的範例擴充功能
使用您自己的 CSS
您也可以透過 "markdown.styles": [] 設定在 Markdown 預覽中使用您自己的 CSS。這會列出要在 Markdown 預覽中載入的樣式表 URL。這些樣式表可以是 https URL，或是相對於目前工作區中本機檔案的路徑。
例如，若要在目前工作區的根目錄載入名為 Style.css 的樣式表，請使用 檔案 > 偏好設定 > 設定來叫出工作區的 settings.json 檔案並進行此更新
// Place your settings in this file to overwrite default and user settings.
{
"markdown.styles": ["Style.css"]
}
保留結尾空白以建立換行
若要建立強制換行，Markdown 需要在行尾加上兩個或更多空格。根據您的使用者或工作區設定，VS Code 可能設定為移除結尾空白。為了僅在 Markdown 檔案中保留結尾空白，您可以將這些行新增至您的 settings.json 中
{
"[markdown]": {
"files.trimTrailingWhitespace": false
}
}
Markdown 預覽安全性
基於安全性考量，VS Code 會限制 Markdown 預覽中顯示的內容。這包括停用指令碼執行，並僅允許透過 https 載入資源。
當 Markdown 預覽封鎖頁面上的內容時，預覽視窗的右上角會顯示警示快顯視窗
您可以按一下此快顯視窗或在任何 Markdown 檔案中執行 Markdown: Change preview security settings 命令，來變更 Markdown 預覽中允許的內容
Markdown 預覽安全性設定會套用至工作區中的所有檔案。
以下是每個安全性等級的詳細資料
嚴格
這是預設設定。僅載入受信任的內容並停用指令碼執行。封鎖 http 圖片。
建議您保持啟用 Strict 安全性，除非您有非常充分的理由變更它，且您信任工作區中的所有 Markdown 檔案。
允許不安全的內容
保持停用指令碼，但允許透過 http 載入內容。
停用
停用預覽視窗中的額外安全性。這允許執行指令碼，也允許透過 http 載入內容。
文件撰寫者設定檔範本
設定檔可讓您根據目前的專案或工作快速切換擴充功能、設定和 UI 版面配置。為了協助您開始編輯 Markdown，您可以使用文件撰寫者設定檔範本，這是一個精選的設定檔，內含實用的擴充功能和設定。您可以直接使用設定檔範本，或以此為起點進一步為您的工作流程進行自訂。
您可以透過「設定檔」(Profiles) > 「建立設定檔...」(Create Profile...) 下拉式選單來選擇設定檔範本
選取設定檔範本後，您可以檢閱設定和擴充功能，如果您不想將個別項目包含在您的新設定檔中，可以將其移除。根據範本建立新設定檔後，對設定、擴充功能或 UI 所做的變更會永久保留在您的設定檔中。
Markdown 擴充功能
除了 VS Code 內建的功能外，您還可以安裝擴充功能以獲得更多功能。
提示：選取擴充功能磚以閱讀描述和評論，以決定哪一個擴充功能最適合您。在 Marketplace 中查看更多資訊。
後續步驟
繼續閱讀以了解
- CSS、SCSS 與 Less - 想編輯您的 CSS 嗎？VS Code 對 CSS、SCSS 和 Less 編輯提供了絕佳的支援。
常見問題
有拼字檢查嗎？
VS Code 未預先安裝，但有提供拼字檢查擴充功能。請查看 VS Code Marketplace 以尋找有助於您工作流程的實用擴充功能。
VS Code 支援 GitHub 風格 Markdown 嗎？
不支援，VS Code 使用 markdown-it 程式庫針對 CommonMark Markdown 規格。GitHub 正朝著 CommonMark 規範邁進，您可以在此更新中閱讀相關內容。