Markdown 與 Visual Studio Code

在 Visual Studio Code 中使用 Markdown 檔案既簡單、直接又有趣。除了 VS Code 的基本編輯功能外，還有一些 Markdown 專用功能可協助您提高生產力。

注意：為了協助您開始編輯 Markdown 檔案，您可以使用文件撰寫器設定檔範本來安裝實用的擴充功能 (拼字檢查器、Markdown 程式碼檢查器) 並設定適當的設定值。

編輯 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) 手動叫用。

路徑 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: 從工作區插入影像 命令來插入影像，以及 Markdown: 插入工作區中檔案的連結 來插入檔案連結。

插入的影像使用 Markdown 影像語法 ![](path/to/image.png)。連結會插入一般的 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 下建立。

智慧選取

智慧選取可讓您在 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 發佈後存在的檔案，這會很有用。

尋找標題和連結的所有參考

使用 尋找所有參考 (⇧⌥F12 (Windows、Linux Shift+Alt+F12)) 命令，以尋找目前工作區中參考 Markdown 標題或連結的所有位置

尋找所有參考 支援

• 標題：# 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 標題時意外中斷連結？試試看改用 重新命名符號 (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: 並排開啟預覽 命令 (⌘K V (Windows、Linux Ctrl+K V))。

動態預覽和預覽鎖定

依預設，Markdown 預覽會自動更新以預覽目前使用中的 Markdown 檔案

您可以使用 Markdown: 切換預覽鎖定 命令鎖定 Markdown 預覽，以將其鎖定到目前的 Markdown 文件。鎖定的預覽會在標題中以 [預覽] 表示

注意： 只有在 Markdown 預覽是使用中的索引標籤時，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

您也可以使用您自己的 CSS 在 Markdown 預覽中，搭配 "markdown.styles": [] 設定。這會列出要在 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: 變更預覽安全性設定 命令，來變更允許在 Markdown 預覽中顯示的內容

Markdown 預覽安全性設定適用於工作區中的所有檔案。

以下是有關每個安全性層級的詳細資訊

嚴格

這是預設設定。僅載入信任的內容並停用指令碼執行。封鎖 http 影像。

我們建議您保持啟用 嚴格 安全性，除非您有非常好的理由變更它，而且您信任工作區中的所有 Markdown 檔案。

允許不安全的內容

保持停用指令碼，但允許透過 http 載入內容。

停用

停用預覽視窗中的其他安全性。這允許指令碼執行，也允許透過 http 載入內容。

文件撰寫器設定檔範本

設定檔可讓您根據目前專案或工作快速切換您的擴充功能、設定和 UI 版面配置。為了協助您開始編輯 Markdown，您可以使用文件撰寫器設定檔範本，這是一個精選的設定檔，其中包含實用的擴充功能和設定。您可以直接使用設定檔範本，或將其用作起點，以進一步自訂您自己的工作流程。

您可以透過 設定檔 > 建立設定檔... 下拉式清單選取設定檔範本

選取設定檔範本後，您可以檢閱設定和擴充功能，並移除您不想包含在新設定檔中的個別項目。根據範本建立新的設定檔後，對設定、擴充功能或 UI 所做的變更會保留在您的設定檔中。

Markdown 擴充功能

除了 VS Code 開箱即用的功能之外，您還可以安裝擴充功能以獲得更強大的功能。

提示：選取擴充功能圖格以閱讀描述和評論，以決定哪個擴充功能最適合您。請在 市集 中查看更多資訊。

後續步驟

請繼續閱讀以了解

• CSS、SCSS 和 Less - 想要編輯您的 CSS 嗎？VS Code 對 CSS、SCSS 和 Less 編輯提供絕佳的支援。

常見問題

是否有拼字檢查？

未與 VS Code 一起安裝，但有拼字檢查擴充功能。請查看 VS Code 市集 以尋找有助於您的工作流程的實用擴充功能。

VS Code 是否支援 GitHub Flavored Markdown？

否，VS Code 以 CommonMark Markdown 規格為目標，使用 markdown-it 程式庫。GitHub 正朝向 CommonMark 規格發展，您可以在此更新中閱讀相關資訊。