Markdown 與 Visual Studio Code
在 Visual Studio Code 中使用 Markdown 檔案既簡單、直接又充滿樂趣。除了 VS Code 的基本編輯功能外，還有許多針對 Markdown 的特殊功能，能協助您提升生產力。
注意：為了幫助您開始編輯 Markdown 檔案，您可以使用 文件編寫者 (Doc Writer) 設定檔範本 來安裝實用的擴充功能（例如拼字檢查、Markdown 語法檢查器）並設定適當的數值。
編輯 Markdown
文件大綱
「大綱」(Outline) 檢視是位於檔案總管底部的一個獨立區塊。展開後，它會顯示目前作用中編輯器的符號樹狀結構。對於 Markdown 檔案而言，符號樹即是該 Markdown 檔案的標題階層。
「大綱」檢視是檢閱文件標題結構與架構的絕佳方式。
Markdown 程式碼片段 (Snippets)
VS Code 內建了一些實用的程式碼片段，可以加速 Markdown 的撰寫。這包括針對程式碼區塊、圖片等內容的片段。在編輯時按下 ⌃Space (Windows, Linux Ctrl+Space) (觸發建議) 即可查看建議的 Markdown 程式碼片段列表。您也可以從「命令選擇區」(Command Palette) 選取「插入程式碼片段」(Insert Snippet) 來使用專屬的片段選擇器。
提示：您可以為 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) 來啟用。
路徑 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 檔案。
-
將游標置於圖片連結上。
-
選取「程式碼動作」(Code Action，燈泡圖示) 並選擇 Generate alt text (產生替代文字)。
-
如果您已經有替代文字，同樣選取「程式碼動作」，並選擇 Refine alt text (優化替代文字)。
智慧選取
智慧選取功能讓您可以快速擴大或縮小 Markdown 文件中的選取範圍。這可用於快速選取整個區塊元素（例如程式碼區塊或表格），或是選取 Markdown 檔案中某個標題區段的所有內容。
智慧選取使用下列命令：
- 擴大選取：⌃⇧⌘→ (Windows, Linux Shift+Alt+Right)
- 縮小選取：⌃⇧⌘← (Windows, Linux Shift+Alt+Left)
選取適用於下列項目，並遵循傳統的階層模式：
- 標題
- 清單
- 引用區塊
- 程式碼區塊 (Fenced code blocks)
- 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 列表。這對於連結到磁碟上不存在，但發佈後會存在的檔案非常有用。
尋找標題與連結的所有參考
使用 Find All References (尋找所有參考) () 命令，可找出目前工作區中所有參考了特定 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 檔案並開始編輯。若要切換檢視，請在編輯器中按下 。您可以並排預覽 () 您正在編輯的檔案，並在編輯時即時看到變更。
以下是一個簡單檔案的範例。
提示：您也可以在編輯器分頁標籤上按右鍵並選擇 Open Preview (開啟預覽) ()，或是使用「命令選擇區」(⇧⌘P (Windows, Linux Ctrl+Shift+P)) 來執行 Markdown: Open Preview to the Side (Markdown: 並排開啟預覽) 命令 ()。
動態預覽與預覽鎖定
預設情況下，Markdown 預覽會自動更新以顯示目前作用中的 Markdown 檔案。
您可以使用 Markdown: Toggle Preview Locking (切換預覽鎖定) 命令來鎖定 Markdown 預覽，使其固定在目前的 Markdown 文件。鎖定的預覽會在標題中標註 [Preview]。
注意：Markdown: Toggle Preview Locking 命令僅在 Markdown 預覽為作用中分頁時才可使用。
編輯器與預覽同步
VS Code 會自動同步 Markdown 編輯器與預覽窗格。捲動 Markdown 預覽時，編輯器也會跟隨捲動以配合預覽的視埠；捲動 Markdown 編輯器時，預覽也會同步跟隨。
您可以使用 markdown.preview.scrollPreviewWithEditor 與 markdown.preview.scrollEditorWithPreview 設定 來停用捲動同步。
編輯器中目前選取的行會在 Markdown 預覽的左邊界以淺灰色條表示。
此外，在 Markdown 預覽中的元素上按兩下，會自動開啟該檔案的編輯器並捲動至最接近該元素的一行。
數學公式渲染
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 預覽中允許的內容。
Markdown 預覽安全性設定適用於工作區中的所有檔案。
以下是各個安全性層級的詳細資訊：
Strict (嚴格)
這是預設設定。僅載入受信任的內容並停用指令碼執行。封鎖 http 圖片。
我們建議您保持啟用 Strict 安全性，除非您有非常充分的理由需要變更它，且您信任工作區中的所有 Markdown 檔案。
Allow insecure content (允許不安全內容)
維持停用指令碼，但允許透過 http 載入內容。
Disable (停用)
停用預覽視窗中的額外安全性。這允許執行指令碼，並允許透過 http 載入內容。
文件編寫者 (Doc Writer) 設定檔範本
設定檔 (Profiles) 讓您可以根據目前專案或任務，快速切換擴充功能、設定與 UI 版面配置。為了協助您開始編輯 Markdown，您可以使用 文件編寫者 (Doc Writer) 設定檔範本，這是一個精選的設定檔，包含了實用的擴充功能與設定。您可以直接使用此範本，或將其作為基礎，進一步客製化以符合您的工作流程。
您可以透過「設定檔」(Profiles) > 「建立設定檔...」(Create Profile...) 下拉式選單來選擇設定檔範本
選取設定檔範本後，您可以檢閱其中的設定與擴充功能，並移除您不想包含在新建設定檔中的個別項目。根據範本建立新設定檔後，對設定、擴充功能或 UI 所做的變更都會儲存於該設定檔中。
Markdown 擴充功能
除了 VS Code 內建的功能外，您也可以安裝擴充功能以獲得更強大的功能。
提示：選取擴充功能磚以閱讀說明與評論，決定哪款擴充功能最適合您。詳情請參閱 市集 (Marketplace)。
後續步驟
繼續閱讀以了解
- CSS, SCSS 與 Less - 想要編輯 CSS？VS Code 對 CSS、SCSS 與 Less 的編輯提供了絕佳支援。
常見問題
有拼字檢查嗎？
VS Code 並未內建拼字檢查，但有相關的拼字檢查擴充功能。請查看 VS Code 市集，尋找有助於您工作流程的實用擴充功能。
VS Code 支援 GitHub Flavored Markdown (GFM) 嗎？
不支援。VS Code 使用 markdown-it 函式庫，目標為符合 CommonMark Markdown 規範。GitHub 正逐步向 CommonMark 規範靠攏，詳情可參考此更新公告。