Yusong

Appearance

在 VSCode 中编写 Markdown ​

文档用途

说明如何在 VSCode 中愉快地编写 Markdown (配置和编辑技巧).

写在前面 ​

为何选择使用 VSCode 来编写 markdown?

  • VSCode 编辑文本的功能挺好用 (毕竟是使用人数最多的代码编辑器).
  • 总有需要使用代码编辑器来编写 markdown 的情况, 例如工程中的 README.md.
  • 本身能做足够多的配置, 又有着丰富的第三方插件, 使其可高度自定义.
  • 能直接阅读并编辑 markdown 源码 (这点与各类在线文档以及 Obsidian 不同).

相关快捷键 ​

快捷键功能
Ctrl+Shift+V在当前窗口新增一个 Tab 来预览
Ctrl+K V在右侧新增一个窗口来分屏预览
Ctrl+Shift+O查看文档结构, 可以进一步搜索/跳转

查看目录 ​

临时查看目录可以使用前文所说的 Ctrl+Shift+O 快捷键:

如果希望让目录一直显示在界面侧边栏, 则可以打开 Outline 视图,
通过 Ctrl+Shift+P 进入命令栏, 输入 View: Focus on Outline View, 就能看到:

自动格式化 ​

建议在 VSCode 中开启 "保存时自动格式化".
按 Ctrl+, 打开设置界面, 搜索 format on save, 勾选下图中的设置:

本地链接 ​

剪切板 ​

如果剪切板中有一张图片, 能直接通过 Ctrl+V 在 markdown 中添加图片引用.
被引用的图片文件将会被添加至当前正在编辑的 .md 文件的同级目录.

TIP

Windows 中使用 Win+Shift+S 可以唤起截图工具, 截图完成后将会自动将截图存储于剪切板.
还可以连续截多张图, 然后通过 Win+V 从剪切板的历史记录中粘贴, 从而快速添加多个截图.

拖拽文件 ​

从 EXPLORER 窗口拖拽一个文件至当前正在编辑的窗口 (开始拖拽后鼠标不要松开),
按住 Shift 键, 将鼠标移动至打算插入的位置, 此时先松开鼠标 (再释放 Shift 键).

md
<!-- 如果是图片/动图/视频/音频, 则会生成类似这种链接 -->
![Alt text](nice-image.png)
md
<!-- 如果不是图片, 则会生成类似这种链接 -->
[Title](nice-doc.md)

TIP

如果打算重命名所引用的本地文件, 建议使用快捷键 F2.
当光标位于括号内的链接上时, 按下 F2, 输入新的名称或路径.
被引用文件将会自动改名, 因此不会丢失引用.

图片尺寸 ​

HTML 标签 ​

Markdown 标准语法中并未对图片尺寸的设置做出规定,
并且各个风格的扩展语法对于图片尺寸的设置语法没有统一的标准,
这给图片的显示尺寸设置带来了困难.

好在 markdown 中可以直接插入 html 标签.

html
<!-- 将图片其等比缩放, 宽度为页面宽度的 30% -->
<img src="./path/image-name.png" width="30%" />

<!-- 同样的, 视频也可以通过这种方式插入, 使用 video 标签 -->
<video controls src="./path/video-name.mp4" width="50%"></video>

Code Snippets ​

为了能快速地书写 <img /> 标签, 建议配置 Code Snippets:
使用快捷键 Ctrl+Shift+P 打开命令所搜索框, 输入 Configure User Snippets 并回车.
输入 markdown 并回车, 开始编辑名为 markdown.json 的文件, 在此设置自己的 Code Snippets.

json
// 在 markdown.json 中添加以下内容
"<img /> html tag": {
    "body": [
        // $1 是光标默认的位置, $2 是按下 tab 键后光标的位置
        "<img src=\"${1:path}\" width=\"${2:50%}\" />",
    ],
    "description": "<img /> html tag",
    "prefix": "img"
},

使用方法: 在编辑 markdown 文件时, 输入 img 然后按下 Ctrl+Space 触发智能提示.

选择正确的智能提示后, 就能自动插入以下内容:

html
<img src="path" width="50%" />

WARNING

按下 Ctrl+Space 尝试触发智能提示时, 请确保输入法为 英文.

单行显示多张图片 ​

依然需要使用 html 标签.

html
<div style="display: flex;">
    <img src="image-name" style="object-fit: contain; max-width: 45%" />
    <p>&nbsp;&nbsp;</p>
    <img src="image-name" style="object-fit: contain; max-width: 45%" />
</div>
对应的 Code Snippets
json
"two images arranged horizontally": {
    "body": [
        "<div style=\"display: flex;\">",
        "\t<img src=\"\" style=\"object-fit: contain; max-width: 45%\" />",
        "\t<p>&nbsp;&nbsp;</p>",
        "\t<img src=\"\" style=\"object-fit: contain; max-width: 45%\"/>",
        "</div>",
    ],
    "description": "two images arranged horizontally",
    "prefix": "two images"
},

VSCode 插件 ​

markdownlint ​

markdownlint 是一个 markdown 语言服务器.
能够自动格式化原文, 并提醒我们遵守最佳实践.

有时我们希望对最佳实践的规则做调整, 此时可以在工程根目录新增 .markdownlint.json.
VSCode 能自动找到 .markdownlint.json 文件的 Json Schema, 因此配置起来比较方便.

json
{
    "no-inline-html": false,  // 允许内嵌 html 标签
    "line-length": false      // 不限制每行的长度
}

如果只希望在局部修改规则, 可以使用特殊的注释实现.
markdownlint 插件自带 Code Snippets, 可以输入 markdownlint 然后触发智能提示.

md
<!-- markdownlint-disable MD037 -->
deliberate space * in * emphasis
<!-- markdownlint-enable MD037 -->
md
<!-- markdownlint-disable-file MD037 -->
deliberate space * in * emphasis

Markdown Emoji ​

Markdown Emoji 插件能够方便我们预览 :EMOJICODE: 扩展语法的渲染结果.
:EMOJICODE: 扩展语法受到广泛支持, 例如 GitLab, GitHub, VitePress.
举例 :tada: 🎉 :100: 💯 :v: ✌️.

Mermaid Preview ​

Markdown Mermaid Preview 插件能够方便我们预览 Mermaid 扩展语法的渲染结果.
Mermaid 扩展语法同样被 GitLab, GitHub 默认支持.

mermaid
flowchart LR
    A --> B

其他技巧 ​

自定义预览效果 ​

vscode 支持通过 css 文件自定义 markdown 的预览效果.
在 vscode 的设置中找到 markdown.styles 即可添加 css 文件路径.

例如我们希望当前的工作空间中预览 markdown 时限制页面最大宽度,
则可以创建 css 文件, 例如这里的路径为 .vscode/markdown-preview.css:

css
.markdown-body {
    /* 预览页面的最大宽度设为 600px */
    max-width: 600px;
    margin: 0 auto;
}

然后在 .vscode/settings.json 中添加如下设置:

json
"markdown.styles": [
    ".vscode/markdown-preview.css"
],