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 文件匹配的全域性模式對映到影像目標。影像目標還可以使用一些簡單的變數。有關可用變數的資訊，請參閱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 文字

您可以使用 AI 為 Markdown 檔案中的影像生成或更新 alt 文字。要生成 alt 文字

1. 確保您已在 VS Code 環境中設定 Copilot。您可以免費開始使用 Copilot。

2. 開啟 Markdown 檔案。

3. 將游標放在影像連結上。

4. 選擇程式碼操作（燈泡）圖示並選擇 生成 alt 文字。

   

5. 如果您已有 alt 文字，請選擇程式碼操作，然後選擇 最佳化 alt 文字。

智慧選擇

智慧選擇允許您快速擴充套件和收縮 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 - 連結全域性模式列表，跳過驗證。如果您連結到磁碟上不存在但釋出 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

您還可以使用 "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: 更改預覽安全設定 命令來更改 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 針對使用 markdown-it 庫的 CommonMark Markdown 規範。GitHub 正在轉向 CommonMark 規範，您可以在此更新中閱讀。