vscode配置及插件markdown篇

继vim后,vscode已经成为了大多数人的主力文本编辑器,甚至是通过插件自定义后的轻量开发环境,毕竟有绕不开的性能瓶颈在。

那么本篇主要介绍本人在使用vscode书写markdown文本是的常用插件以及配置情况。若您目前对vscode编辑器没有丝毫了解,可以先看下2019-05-11的《vscode配置及插件基础篇》文章。

说得markdown, 我们需要的无非是书写体验以及预览体验两方面, 本文会根据这两方面展开。

首先说明一点, 本文重点针对喜欢编辑预览分开情况下书写markdown的用户,如果您是此类用户,可直接跳至此处开始正文的阅读。

如果您对于markdown的要求是单屏实时预览, 目前的vscode不合适(仅供参考,自行判断),理由如下:

虽然目前vscode中确实有提供此功能的插件 Office Viewer(Markdown Editor) , 可此插件的实际情况是完全脱离了vscode的操作,自成一派, 不兼容vscode快捷键与其他插件(比如此插件内vim就用不了),并且目前使用起来也不是太流畅,不知后续是否会优化, 对了,这个插件还带了俩不好看的主题风格哈哈。不过对vim不感冒,不介意损失vscode自定义配置的朋友,还是可以尝试下的。

点击图片进入插件官方地址:

插件效果如图所示:\

vscode自带的markdown功能及配置

VS Code 具有开箱即用的基本 Markdown 支持（例如， Markdown 预览、目录大纲等),以及一些其他通用配置, 如vscode代码插入片段功能就很好用,它不只可以用来编辑自定义的代码片段,同时像我们markdown的表格以及带有复选框的列表等,也可以用此功能自定义后插入使用。

md预览,vscode自身也提供了几种最基础的简单解析的风格,过于简陋,就不进行配置与介绍了,后面介绍的预览增强插件会代替它。
目录大纲,vscode自身提供了大纲功能, 常用于vscode中写博文时的预览方便,非常实用。可按下面操作图中的一、二、三步打开
- 操作图
- 效果展示
md表格片段, 本文章后面提供操作步骤,提前阅读请点击跳转<自定义markdown的表格插入片段>。

插件:增强预览效果

`markdown Preview Github Styling`

点击图片进入插件官方地址:

由于认为github的风格比较经典, 此插件刚好满足, 没有多余的杂乱功能, 加载速度快, 因此使用此插件来增强vscode自带的md预览。

`markdown preview enhanced` 不推荐

点击图片进入插件官方地址:

为啥要莫名奇妙的写一个不推荐的呢?

因为这个插件的下载量比较高, 有些人很容易下载使用它, 而我真心不希望大家使用。而如果你像我一样对应编辑器的响应速度有需求, 答应我, 尽量避免使用这个插件; 因为此插件的加载速度高达1000+ms,非常缓慢, 而vscode打开后会等待插件加载完后才可以使用, 因此,安装此插件会使你打开vscode后,需等待很久才能编辑文本。会有很不好的体验。

此插件所提供的的功能,如:大纲,表格插入,预览增强等一些功能, 完全可以由其他更好的方法实现,且其他方法实现后还不损失加载速度

插件功能	代替方案
大纲	使用vscode自带的大纲,不损失性能的情况下提升书写及预览体验
表格插入	使用vscode片段功能,不损失性能的情况下,还支持自定义,然后配合markdown table插件极大的提升书写体验
增强预览	使用markdown Preview Github Styling插件代替,不损失性能的情况下,提升预览体验
单独调整预览页面的大小	实用价值不强的功能,不过功能挺有意思,但相对于因此遭到性能的损失,有些不值。本人工作环境屏幕较大,目前很少有对此项功能的需求,并没有为其寻找代替方案

插件:优化书写体验

`markdown All in One`

点击图片进入插件官方地址:

安装此插件后,你会发现,你在书写列表时会舒服很多,当然,这功能就是此插件带来的

至于缩进配置,插件默认动态缩进规则的已经很好用了。若喜欢用固定的缩进大小,可自行更改list.indentationSize设置。
给markdwon加粗绑定快捷键也是此插件的一个很好用的功能,默认快捷键为Ctrl+B,看过基础篇的都知道,此快捷键与vscode隐藏/打开侧边栏快捷键冲突,因此需要自行合理安排重新配置快捷键,本人将此项功能键绑定变更为Alt+B

此功能可以很好的与vim插件的v可视模式配合使用,可以很高效的对已有文本加粗。

其他诸如在所选文本上粘贴链接、创建目录以及与之对应的标题编号功能、转html、数学公式、自动链接图片,自定义位置、表格相关等功能,本人不喜欢用

其他功能	不喜欢的原因
在所选文本上粘贴链接	不如vscode自定义片段方便。
创建目录	太鸡肋,不是针对插件功能。只是本人不喜欢让自己的markdown文章在书写以及博文阅读中有两个目录存在。而且我很少会给文章加编号,但偶尔会加一下,不过需求不大,对此功能也不感冒。
转html	没有单独的这方面需求,如果是博客方案,一般都集成至框架中自动实现了。
数学公式	单纯的没有需求。
自动链接图片、自定义锚点链接	不如图床图片方案、与直接html通用位置锚点方案好用。比如:图片我喜欢用图床,在图床端自定义链接的生成方案后,在文章中一键粘贴即可,更方便可维护性更强^{图床方案用的picgo+腾讯云COS}。锚点位置跳转方案,我认为用vscode代码片段功能来自定义html片段来实现锚点跳转最为方便且更多样化(^{由于本人自定义markdown用的html片段的小节,造成了部分非程序员的读者迷路,考虑到此小节属于个人小众行为,似乎偏离文章主题,现已删除此小节,链接已重定向为代码片段功能的官方文档,有需求的朋友可参考官文自行配置})。
表格相关	使用了另一个更好用功能更全的插件来满足此项需求<插件:Markdown Table>。

`markdown table`

点击图片进入插件官方地址:

想必大家都有对表格的需求,markdown中的表格结构简单易用,但完全手动的话,书写起来相对繁琐。因此对于结构简单的表格的使用,应尽量让繁琐的事情由编辑器自动完成,我们只关心内容就好了,此插件就是解决的这个问题。
下面是我对此插件的配置, 同时使用vim插件的朋友, 可以参考我的配置, 在右下角管理->键盘快捷方式中,根据下表命令搜索相关键绑定进行更改:
注意:
- 修改的快捷键后, 记得更改此项后面的when表达式为editorTextFocus && markdowntable.contextkey.selection.InMarkdownTable && !editorReadonly && !editorTabMovesFocus && !inSnippetMode && !suggestWidgetMultipleSuggestions && !suggestWidgetVisible && editorLangId == 'markdown' && vim.mode == 'Normal',以免影响其他情况下+、-、=符号的正常使用,以及避免其他的快捷键冲突现场
- 非vim插件用户, 按此快捷键配置,在用表格内无法通过输入+、-、=,完成相应的右、左、中对齐。此种风格的快捷键配置,是于vim插件在命令模式时生效使用的。
- 另外,由于多个插件存在格式化表格功能,建议在管理->键盘快捷方式中搜索Shift+Alt+F快捷键,删除其他markdown插件功能下的此快捷键配置。(不需要删除此快捷键绑定的与markdown插件无关的配置防止影响其他不相干插件或vscode本身的格式化功能)
配置完成后,配合上vscode自带的插入片段功能->点击跳转<自定义markdown的表格插入片段>阅读。插入一个 2×2 的基础表格, 在此基础上使用本插件的自定义快捷键,随意扩展书写表格。可以极大地提升markdown中书写表格的效率。
最后我想分享一点,本插件没有删除列这一功能,考虑是规则比较复杂难实现且不是很关键的功能,因为此种情况遇到的几率不大,手动删除也不怎么影响效率;而且使用vim插件地朋友都知道, vim命令行模式下ctrl+v可视模式,可以相对容易地按列删除表格。因此很多时候我们做开发,不要为了开发而开发,面对需求,先多问下自己所要开发的功能是否有必要, 不要做码农, 要做个有创造力的程序员。

`markdownlint`

点击图片进入插件官方地址:

此插件提供的主要功能就是语法检测, 可以辅助我们规范markdown书写时的格式规范。当然,此插件提供的是作者认为的通用规范,我们可以自定义这些规范的检测机制,以及是否开启/关闭已有的检测机制(默认全部开启),还有是否需要忽略一些特殊的文件在此插件的检测范围之外等等一系列配置, 下面绍下本人对该插件的使用习惯,以及一些常用的配置项。

可以提前打开你的用户配置文件(快捷键 ctrl+shift+p 后打开命令面板,输入用户,点击首选项:打开用户设置(JSON)开启你的用户配置文件)。然后一起浏览下,日常用能到的到的功能及其配置,仅供参考

打对勾的是本人对此插件常用的功能,没打对勾的是不常用的功能;插件的需求因人而异,可以自行前往插件官方地址查看可使用功能; 那么接下来介绍下我的配置和使用:

被动功能: 实时监测功能,此功能默认打开,只要您安装了此插件, 就会默认启用插件规则集,实时的检测您当前正在编辑的md文档是否有书写格式是否违反这些规则集,并对违反规则集的给出warning级别的橙黄色提示
主动功能:基于本插件定义的规则集,检查当前整个工作区的所有md文件,是否符合要求,并对违反规则集的给出error级别的红色提示
说明下,此功能手动检测后,默认违反书写规则的问题,问题以error的级别提示红色提示; 不过由于本插件的被动功能,在你点击这些error问题进入查看时,会在被动功能的作用下,重新将该问题定位为warning级别(不过请放心,问题结果是一致的,只是变更了错误级别)
1. 点击管理->键盘快捷方式打开后,搜索Lint all Markdown files in the workspace with markdownlint项,并给其绑定一个快捷键(我设置的是ctrl+shift+F4+1,可以参考我的设置),之后您就可以通过所设置的快捷键(比如ctrl+shift+F4+1)使用此项功能。(或者使用时直接通过ctrl+shift+p打开命令面板输入Lint all Markdown files in the workspace with markdownlint搜索此功能点击使用)
2. 在问题面板查看检结果。(问题面板可通过快捷键ctrl+shift+M打开)
主动功能:暂时关闭/打开markdownlint对当前工作区的规则检测(即暂时关闭实时监测这一被动功能)
为何说是暂时呢, 因为这个关闭在您打开新的工作区,或是重启当前工作区,实时监测这一被动功能依旧是默认打开的;
此功能重复使用为相反结果:即关闭与打开
1. 点击管理->键盘快捷方式打开后,搜索Toggle linting by markdownlint on/off (temporarily)项,并给其绑定一个快捷键,之后您就可以通过所设置的快捷键使用此项功能。(或者使用时直接通过ctrl+shift+p打开命令面板输入Toggle linting by markdownlint on/off (temporarily)搜索此功能点击使用)
不经常使用的原因是, 禁用后才发现自己多需要不离不弃的辅助哈哈。于是删除此功能的快捷键绑定以弃用。
主动功能:使能插件对违反了规则集的内容进行修复。
1. 点击管理->键盘快捷方式打开后,搜索Fix all supported markdownlint violations in the document项,并给其绑定一个快捷键,之后您就可以通过所设置的快捷键使用此项功能。(或者使用时直接通过ctrl+shift+p打开命令面板输入Fix all supported markdownlint violations in the document搜索此功能点击使用)
2. 若是修复结果不符合自己的预期,可通过Ctrl+Z恢复如初后,自己手动修改。
不经常使用的原因是, 用了几次发现还不如直接手动修改,还能多在提示中借鉴学习下作者对于规范的理解。于是删除此功能的快捷键绑定以弃用。
自动化相关配置
- 在保存或粘贴到Markdown时自动格式化文档,降低违反规则集的概率(默认无配置,需手动配置)
  - 快捷键 ctrl+shift+p 后打开命令面板,输入用户,点击首选项:打开用户设置(JSON)开启你的用户配置文件,加入下面配置即可打开此功能:
    1
    2
    3
    4
    "[markdown]": {
    "editor.formatOnSave": true,
    "editor.formatOnPaste": true
    },
- 在保存 Markdown 文档时自动修复违规,等于配置此项后,每次做保存文档操作时都会触发此插件去自动修复违反了规则集的内容。
  - 快捷键 ctrl+shift+p 后打开命令面板,输入用户,点击首选项:打开用户设置(JSON)开启你的用户配置文件,加入下面配置即可打开此功能:
    1
    2
    3
    "editor.codeActionsOnSave": {
    "source.fixAll.markdownlint": true
    }
  当然若是修复结果不符合自己的预期,可通过Ctrl+Z恢复如初,自己手动修改后,重新保存。
不使用此处两配置的原因是, 个人认为配置后实际作用不大。觉得配置与否,实际体验下来对效率和方便维度来说,都没有太大区别。于是在用户设置中删除了此项配置以弃用。
对此插件默认规则集的一部分进行禁用
- 快捷键 ctrl+shift+p 后打开命令面板,输入用户,点击首选项:打开用户设置(JSON)开启你的用户配置文件,加入下面配置即可打开此功能:
- 插件还可对具体项目甚至具体文件有针对性的定制其单独的规则集, 需要自己创建自定义的json或yaml文件进行配置; 禁用同上,而自定义规则集配置篇幅过长,请直接移步源码地址阅读详情。
  配置时注意以下优先级(降序):
  1. .markdownlint-cli2.{jsonc,yaml,js}同一目录或父目录中的文件
  2. .markdownlint.{jsonc,json,yaml,yml,js}同一目录或父目录中的文件
  3. Visual Studio Code 用户/工作区设置
  4. 默认配置
  保存到任何位置的配置更改都会立即生效。
  未使用原因,自身目前也就用md做做通用性的笔记,暂时还没有用对这项高级定制规则的需求。
对被动的实时监测功能进行自定义配置
- 由于正在进行编辑的当前行书写时一定会经历违反规则集的时刻, 因此对当前行的的监测告警很没有必要,我们可以通过配置关闭它
  - 快捷键 ctrl+shift+p 后打开命令面板,输入用户,点击首选项:打开用户设置(JSON)开启你的用户配置文件,加入下面配置即可关闭对当前行的实时监测:
    1
    2
    3
    {
    "markdownlint.focusMode": true
    }
- 同时,我们也可以配置当前行前后区域是否触发警告(此配置仅在用户/工作区设置中可生效,不支持在之前说得高级定制规则中配置)
  - 快捷键 ctrl+shift+p 后打开命令面板,输入用户,点击首选项:打开用户设置(JSON)开启你的用户配置文件,加入下面配置即可关闭对配置行的实时监测:
    
    数字代表每个方向上要忽略的行数,请将其设置为一个正整数
    1
    2
    3
    {
    "markdownlint.focusMode": 2
    }

将被动的实时监测更改为被动的仅在保存时触发监测的配置

仅在保存时触发监测的效果是,由监测报告的问题列表将在编辑文档时不予展示，直到你保存文档时才更新问题的告警展示。

快捷键 ctrl+shift+p 后打开命令面板,输入用户,点击首选项:打开用户设置(JSON)开启你的用户配置文件,加入下面配置即可实现仅在保存时触发监测的功能:

    {
      "markdownlint.run": "onSave"
    }
    ```  

* [x] 配置被动实时监测需要跳过的文件
  > 多种配置方式的效果一致,任选其一
  1. 快捷键 `ctrl+shift+p` 后打开命令面板,输入`用户`,点击`首选项:打开用户设置(JSON)`开启你的用户配置文件,加入下面配置忽略具体文件,格式为:

      ```bash
      {
        "markdownlint.ignore": [
          "**/vscode插件markdown篇.md"
        ]
      }

即此项配置过后, “vscode插件markdown篇.md”这篇文章以及被跳过了,本插件不再对齐进行扫描监测

这里只是举例子,实际中若您的文件名有重复,还请使用通配符清楚秒述具体路径。

像git中的.gitnore一样,创建.markdownlintignore文件来跳过对具体文件的扫描监测,内容遵循.gitignore规则, 格式为:
1
2
test/*.md # 忽略该路径下所有md
!test/except/this/one.md # 但不忽略one.md
即此项配置过后,”one.md”这篇文章仍可以受到插件的被动监测扫描

此插件还支持添加自定义的规则集

由于篇幅因素,具体配置详情,请直接参考源码地址的叙述,以及此篇文档阅读使用。

可以通过md文件本身的注释,来抑制单个警告,如下:

1
2
3

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

比如在”deliberate space * in * emphasis”这一行禁用MD037还可以这样写:

1 2	<!-- markdownlint-disable-next-line MD037 --> deliberate space * in * emphasis

或

1	deliberate space * in * emphasis <!-- markdownlint-disable-line MD037 -->

效果一致

具体书写格式请直接阅读该插件源码主页的对应部分,简单易懂。

配置:自定义markdown的表格插入片段

本小节所涉及vscode的代码片段功能,功能详细信息可前往官方文档对应部分阅读。

我们本小节的配置分两步, 建表和启用

创建/打开一个片段文件并添加一个片段
1. 快捷键 ctrl+shift+p 后打开命令面板,输入片段,点击代码片段:配置用户代码片段
2. 在 新代码片段的下拉列表中找到markdown类型并点击,会得到一个markdown.json文件。(若已有markdown.json文件,请直接选择您在现有代码片段列表中的markdown.json文件)
3. 添加以下内容,并保存文件
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  {
  "插入一个表格": {
  "prefix": "table",
  "body": [
  "|${0:title} | |",
  "| - | - |",
  "| | |"
  ],
  "description": "插入一个表格"
  }
  }
  注意,如果您像我一样英语不好的话, 最好也像我这样设置为中文方便自己。如果您英文过关,请自行定义英文名称和英文描述
启用片段
1. 快捷键 ctrl+shift+p 后打开命令面板,输入用户,点击首选项:打开用户设置(JSON)开启你的用户配置文件后,加入下面配置,并保存文件:
1
2
3
4
5
6
7
"[markdown]"{
"editor.quickSuggestions":{
"other": "on",
"comments": "off",
"strings": "off"
}
}

这样配置后, 在书写markdown时您就可以在键入table的过程中,获得此片段的插入提示了,正确选择后即可插入表格。

插件:img图片插入优化

一般都有自己的图床, 但不免有些时候会涉及到一些临时的文章书写, 并不想使用图床。此时可以使用这款插件 Paste Image

这个插件最开始是由于作者使用hexo时的需求产生的, 因此有常用的相对路径的使用方法, 和使用hexo时的绝对路径使用方法, 具体可查看这个issues

因此, 当两者同时需求时, 可对于绝对路径法只在当前工作空间配置, 而全局的配置使用相对路径法

下面是我的配置:

全局

"pasteImage.path": "${currentFileDir}/img",
"pasteImage.basePath": "${currentFileDir}",
"pasteImage.prefix": "./",
"pasteImage.insertPattern": "<img src=\"${imageFilePath}\" alt=\"\" title=\"\" width = \"\" />",
"pasteImage.defaultName": "YMMDDHHmmss",
"pasteImage.showFilePathConfirmInputBox": true,

hexo工作区

"pasteImage.path": "${projectRoot}/source/customBlog1133/blog",
"pasteImage.basePath": "${projectRoot}/source/",
"pasteImage.prefix": "/",
"pasteImage.insertPattern": "<img src=\"${imageFilePath}\" alt=\"\" title=\"\" width = \"\" />",
"pasteImage.defaultName": "YMMDDHHmmss",
"pasteImage.showFilePathConfirmInputBox": true,

vscode配置及插件markdown篇

vscode自带的markdown功能及配置

插件:增强预览效果

markdown Preview Github Styling

markdown preview enhanced 不推荐

插件:优化书写体验

markdown All in One

markdown table

markdownlint

配置:自定义markdown的表格插入片段

插件:img图片插入优化

`markdown Preview Github Styling`

`markdown preview enhanced` 不推荐

`markdown All in One`

`markdown table`

`markdownlint`