VSCode搭建最强Markdown编辑环境

• 1. 本文目标
• 2. 准备工作
• 3. 安装插件
• 4. 插件的用法
  • 4.1. Markdown All in One
    • 4.1.1. 快捷键
    • 4.1.2. 创建/更新目录
    • 4.1.3. 给标题增加序号
  • 4.2. markdownlint
    • 4.2.1. 格式检查
    • 4.2.2. 文档格式化
  • 4.3. Markdown Table
    • 4.3.1. 格式化表格
    • 4.3.2. 插入表格列
  • 4.4. Markdown PDF
  • 4.5. Write Timestamp
  • 4.6. Paste Image
    • 4.6.1. WSL环境下无法粘贴Windows剪贴板的图片

VSCode是笔者用过的最好用的开发工具，没有之一。笔者14年的码龄生涯中，先后用过Eclipse、 IntelliJ IDEA、 WebStorm、 PyCharm、 Visual Studio(2010/2013/2015)、 NetBeans、 Sublime Text等，但自从用VSCode之后，就再没换过其他工具，一直用到现在有5年多的时间。

1. 本文目标

这篇文章主要介绍如何使用VSCode来进行Markdown的写作，用VSCode来搭建一套markdown的文档写作环境。

什么是markdown？

Markdown是一种轻量级的标记语言，旨在简化文本格式化的过程。它允许用户使用纯文本格式编写文档，并通过简单的标记语法来添加格式，如标题、列表、粗体、斜体、链接和图片等。Markdown文件通常以.md或.markdown为扩展名。具体语法参见以下文档，这里不再赘述。

• Markdown语法中文文档
• Markdown语法英文文档

先展示一下最终的效果图：

2. 准备工作

官网下载VSCode并安装： https://code.visualstudio.com/

3. 安装插件

vscode默认是支持Markdown的，基本的语法、编辑功能、预览功能都可以用，但如果需要更高级的功能，可以安装一些插件来提升效率。使我们的markdown文档编辑起来更加丝滑、高效。

插件名称	发布者	功能介绍
Markdown All in One	Yu Zhang	支持快捷键（如粗体/斜体）、创建目录、表格自动格式化、LaTeX 数学公式支持等功能
markdownlint	David Anson	Markdown语法检查器，可识别和快速修复常见的Markdown语法错误。
Markdown Table	Takumi Ishii	Markdown表格编辑的神器，可对表格进格式化、插入行、行/列等。
Markdown PDF	yzane	支持将Markdown文件转换成pdf, html, png, jpeg等格式。
Markdown Preview Github Styling	Matt Bierner	Github使用的Markdown渲染样式，整体样式：朴素、简洁。
Markdown Preview Enhanced	Yiyi Wang	Markdown预览插件，支持目录树，提供更丰富的功能和更强的定制化能力。 与Markdown Preview Github Styling是同类型的插件，可以根据自己的喜好选择其中一个安装。
Write Timestamp	michael gieson	插入系统当前时间戳，可以自定义格式。
Paste Image	mushan	粘贴图片，支持将剪切板里的图片直接保存到文档中。支持自定义保存路径。

4. 插件的用法

4.1. Markdown All in One

4.1.1. 快捷键

快捷键	功能
Ctrl + B	加粗
Ctrl + I	斜体
Ctrl / Cmd + Shift + V	切换预览模式和编辑模式

4.1.2. 创建/更新目录

1. 打开命令面板（Ctrl + Shift + P）。
2. 输入“Markdown All in One: Create Table of Contents”创建目录，输入“Markdown All in One: Update Table of Contents”更新目录。
3. 点击/或按下回车确认。

4.1.3. 给标题增加序号

1. 打开命令面板（Ctrl + Shift + P）
2. 输入“Markdown All in One: Add/Update section Number”
3. 点击/或按下回车确认

4.2. markdownlint

4.2.1. 格式检查

markdownlint安装后，默认会开启格式检查的功能。当markdown文档格式错误时，编辑器内对应的错误行会有（黄色波浪线的）提示信息。

4.2.2. 文档格式化

可以通过markdownlint对整个markdown文档进行格式化，并自动修复错误。

快捷键：

MacOS: Option + Shift + F Windows: Ctrl + Shift + F

鼠标右键：

1. 编辑器内右键鼠标 -> 选择“Format Document With” -> 选择“markdownlint” -> 点击/或按下回车确认。
2. 编辑器内右键鼠标 -> 选择“Format Document With” -> 选择“Configure Default Formatter...” -> 配置默认的格式化器。

保持时自动格式化：

settings.json文件中添加以下内容：

"editor.formatOnSave": true,
"editor.formatOnSaveMode": "modificationsIfAvailable"

4.3. Markdown Table

4.3.1. 格式化表格

1. 打开命令面板（Ctrl + Shift + P），或者鼠标右键点击表格区域。
2. 选择“Markdown Table: format table”。
3. 点击/或按下回车确认。

4.3.2. 插入表格列

1. 打开命令面板（Ctrl + Shift + P），或者鼠标右键点击表格区域。
2. 选择“Markdown Table: insert column left/right”。
3. 点击/或按下回车确认。

4.4. Markdown PDF

1. 打开命令面板（Ctrl + Shift + P）。
2. 输入“Markdown PDF:”。
3. 选择需要导出的文件格式。
4. 点击/或按下回车确认。

注意： Markdown PDF导出的PDF文件没有目录，如果需要目录，可以使用prince工具。prince的安装和使用可以参考《将Markdown转换为PDF文件(支持目录大纲)》。

4.5. Write Timestamp

1. 快捷键

PC: ctrl-shift-t

MAC: cmd-shift-t

2. 自定义时间格式

在settings.json文件中添加以下配置：

"writeTimestamp.bCustomFormat": "yyyy-mm-dd  HH:MM:SS"

4.6. Paste Image

默认快捷键:

Windows/Linux: Ctrl+Alt+V

MacOS: Cmd+Alt+V

自定义保存路径:

在settings.json文件中添加以下配置：

// 设置图片保存路径：与文件同级的目录创建一个与文件同名的文件夹，在此文件夹下存放图片。
"pasteImage.path": "${currentFileNameWithoutExt}/",
// 设置图片默认名称, 默认为当前文件名
"pasteImage.defaultName": "${currentFileNameWithoutExt}",

4.6.1. WSL环境下无法粘贴Windows剪贴板的图片

问题现象：

在Windows上用VSCode通过WSL Remote连接到WSL中编辑Markdown时，按Ctrl+Alt+V粘贴在Windows主机上复制的图片会失败，通常报错：There is not an image in clipboard.。

原因：

Paste Image插件运行在WSL（Linux）端的vscode-server里，读取剪贴板时调用的是Linux下的xclip，而xclip无法访问Windows主机的剪贴板（即使开启了WSLg，图片这种二进制剪贴板格式也无法跨过去）。所以本质不是插件Bug，而是Remote架构限制。

解决方案：

推荐二选一，按需要选择。

方案A（推荐）：使用 VSCode 内置的 Markdown 图片粘贴功能

VSCode 1.79+ 已经原生支持往Markdown里粘贴剪贴板里的图片，并且走的是VSCode自己的Remote协议，可以正确地把Windows主机剪贴板里的图片传到WSL再落盘，无需任何额外插件。

在settings.json里加入以下配置：

// 启用粘贴图片时自动复制为文件
"editor.experimental.pasteActions.enabled": true,
// 设置图片保存路径：与当前文件同级、与文件同名的目录下
"markdown.copyFiles.destination": {
    "**/*.md": "${documentBaseName}/"
},
// 粘贴时直接生成 Markdown 链接
"markdown.editor.filePaste.copyIntoWorkspace": "mediaFiles"

之后在Markdown文件中直接按 Ctrl+V（注意不是 Ctrl+Alt+V）即可粘贴图片，VSCode会自动保存图片到指定目录并插入![](xxx.png)链接。

方案B：改用 Markdown Image Paste for Remote 插件

mushan发布的Paste Image插件已多年未更新，对Remote场景没做适配。社区有专门面向Remote/WSL环境的替代插件 Markdown Image Paste for Remote（发布者 watahani），它通过WebView的clipboard API绕开了Linux端拿不到Windows剪贴板图片的问题。

安装后，使用方式与Paste Image基本一致，路径模板配置项为markdownImagePaste.path，例如：

"markdownImagePaste.path": "${currentFileNameWithoutExt}/",
"markdownImagePaste.defaultName": "Y-MM-DD-HH-mm-ss"