把vscode打造成markdown编辑器

2022年4月23日 504点热度 0人点赞 0条评论

前言

相信在寻找 Markdown 编辑器的时候, 你肯定会遇到有人推荐使用 VS Code, 但是实际上 VS Code 本身对于 Markdown 来说只是简单地支持了它的编辑操作, 并没有对于编辑体验做过多的优化, 特别是对于中文编辑来说体验甚至不如记事本🤯; 但是得益于 VS Code 强大的可拓展性和高度自由的自定义选项, 把它打造成一个舒适趁手的 MD 编辑器也是很轻松的.

对于大部分新手来说, 也许 Typora 更加适合初次使用, 但是 CX 我本人并不建议入门就使用这种 "所见既所得" 模式的 MD 编辑器, 虽然简洁方便但并不适合深入理解 MD 语法, 毕竟 MD 主要靠的是空格缩进和空行来确定行间关系以及区块语法之间的递进关系, 以及一些渲染器之间不同渲染结果都需要先保证语法的规范才能让 MD 的渲染结果最大化的一致. 所见即所得的 MD 编辑器为了防止区块语法造成的错误都会保留源码模式, 很多由此所引起的错误如果完全使用双窗口编辑器直接写的是源码那基本上是不可能出现的; 一些习惯也会由所见即所得养成从而忽视 Markdown 的规范, 比如:

  • 忘记为直接链接包裹 <> 也没有使用超链接语法.
  • 由于自动补全造成的段尾及空行出现无用空格.
  • 由于自动补全而忘记如何在源码模式表示不同区块间的层级关系.
  • MD 文档如果没有通过 frontmatter 或 HTML 指定 H1 标题, 则必须以一级标题开头.
  • ...

当用习惯这些所见即所得编辑器之后, 甚至会出现面对只能先输入源码再预览渲染结果的地方手足无措, 这对于学习 MD 来说无异于一种倒退, 在此 CX 还是建议尽量使用源码编辑 MD, 不要过分依赖于预览和渲染, 毕竟 MD 文档源码的易读性也是在众多标记语言中独有的特点, 不要忘了 MD 是为了便于格式化才使用的, 首要的不是渲染结果而是源码.

当然 CX 承认, 所见即所得在一些场景, 比如分屏摘抄的时候优势拉满, 对于一些显示面积有限的设备很明显所见即所得更具优势, 而且对于源码面积与渲染后面积差距较大的位置, 双窗口的同步滚动也会出现问题, 而所见即所得则根本没有这种问题. 在此并不是为了抵制所见即所得, 只是希望喜欢想深入了解 Markdown 的朋友更多地在意自己的语法规范, Typora 既没有语法检查也不可能有双窗口视图, 接下来要说到的 VS Code 本身作为代码编辑器理所应当的该有一切为规范和标准化而诞生插件, 即使只使用源码编辑 Markdown 也不会比所见即所得的体验差.

在 Typora 正式推出 1.0 版本的时候, 碍于他们的定价策略在大版本买断制和终生买断制之间举棋不定, 再加上我本来并不对所见即所得感到体验良好(下文会讲到), 所以我才开始真正地探索如何优化 VS Code 的 MD 编辑体验, 得益于自带的的配置同步功能, 使得配置编辑器的工作成了一劳永逸的事情, 何乐而不为呢?😉

软件安装

Visual Studio Code

Visual Studio Code

"VS Code" 全称 Visual Studio Code, 是一款微软开发并提供的免费跨平台源代码编辑器, 以其强大的可扩展性著称, 推荐通过官方站点下载页下载:

Download Visual Studio Code - Mac, Linux, Windows

当然如果通过官方下载遇到困难, 通过以下的第三方应用商店也是种较为安全保险的办法😂.

  • Visual Studio Code - 联想软件商店
  • Visual Studio Code - 腾讯软件中心官网

小心 "高速下载"🤣.

安装过程中强烈建议将图示两项 "通过 Code 打开集成到资源管理器上下文菜单" 都勾选上, 方便日后使用. 

集成到右键菜单

集成到右键菜单

右键菜单快速启动

右键菜单快速启动

安装打开后默认界面语言是英文, 一般情况下会在右下角提示你的系统显示语言所对应的语言包安装提醒, 建议点击安装语言包方便以后的使用;

安装语言包

安装语言包

如果没有弹出则需要手动点击扩展安装语言包, 输入 Chinese 即可搜索到对应的语言扩展:

手动安装语言包

手动安装语言包

在正式进入配置之前如果你真的没有使用过 VS Code 可以随意点击功能按钮, 提前熟悉一下软件功能.

扩展配置

依旧是点击侧边栏图标 "扩展" 或者按键盘快捷键 '{Ctrl}'+'{Shift}'+X 打开, 搜索并安装以下插件:

这里的插件主要是为了增强 MD 编辑体验, 建议跟随下方的配置一步一步安装; 当然也可以直接将下列插件一次性全部安装后再阅读以下各插件的详细配置.

  • GitHub Theme

    改善编辑器界面的中文正文颜色.

  • Markdown All in One

    MD 增强多合一插件.

  • Markdown Image

    MD 快捷粘贴引用本地图片.

  • Markdown Preview Enhanced

    额外的渲染预览视图, 比自带的预览视图更加强力.

  • Markdown Preview Github Styling

    将自带的 MD 渲染预览样式更改为 Github 的渲染样式.

  • markdownlint

    MD 语法检查提示.

  • Word Count CJK

    中文字数统计.

注意, 安装完扩展可以用通过点击插件旁的小齿轮图标或者右键 - "扩展设置" 即可进入对应扩展的配置界面. 

进入扩展配置

进入扩展配置

GitHub Theme

GitHub Theme

GitHub Theme

安装完这个扩展就会让你你选择一个主题颜色, 这里随意选择自己喜欢的颜色就好, 主要区别只是明暗的深度的不同: 

选择主题颜色

选择主题颜色

实际上, 这个主题只是为了改变默认主题的中文字体的显示颜色, 默认主题的中文字符显示都发灰, 不太适合用来中文编写文档, 如果有同样能改变编辑区中文字体颜色让它们和英文正文一样能够显示一样的颜色就好.

可能是因为作为代码编辑器使用中文写进代码的情况可能大部分都只存在于注释的情况, 所以很多主题都会这么设置配色😂.

比如同类的还可以试试 "ReUI" 这个主题扩展, 编辑区中文字符的显示也能得到改善: 

ReUI 主题扩展

ReUI 主题扩展

VS Code 有非常多的主题扩展, 可以搜索 "Theme" 查找主题扩展然后一个一个慢慢试🤣.

Markdown All in One

Markdown All in One 扩展

Markdown All in One 扩展

这是个强大的 MD 辅助插件, 能够赋予 VS Code 编辑 MD 的时候一系列有用的快捷键和自动补全, 更多功能可以参见这个插件的扩展页说明文档或者仓库说明文档:

  • Markdown All in One - Visual Studio Marketplace
  • vscode-markdown/README.md at master · yzhang-gh/vscode-markdown

这个插件无需过多配置就可以直接使用, 配置内容也大多是和一些语法习惯有关的内容, CX 本人在安装完也后没有过多设置.

当然你也可以进去修改一些配置, 比如使用有序列表的语法符号是使用 - 还是 + 或是 * 这样的细节, 以及一些导出为 HTML 的样式设置.

Markdown Image

Markdown Image 扩展

Markdown Image 扩展

这个插件是为了改善本地图片插入引用的体验, 可以做到 Typora 类似的直接复制本地图片之后粘贴进 MD 文档就能自动将图片名称和路径格式化之后插入文档中.

安装插件后进入配置界面, 这里主要配置的两个地方是:

  • 基础图片名格式

Base: File Name Format

  • Base: File Name Format

    如果不想深究这些变量, 直接在输入框中粘贴以下 CX 的配置即可:

mdname}/IMG\_mdname/IMG_{YY}{MM}MM{DD}-{HH}HH{mm}{ss}ss{mss

  • 图片文件夹 

Local: Path

  • Local: Path

\.assets_IMG

上面这些变量能够将使用这个插件插入的本地图片复制到 MD 文档所在的文件夹下的 .assets_IMG文件夹内, 并新建一个以当前 MD 文档名命名的文件夹存放图片, 图片文件名会被命名为 IMG_20211216-093507812 这样的基于当前时间的名称(便于排序);

类似于 Typora 中的 "复制图片到 /${filename}.assets 文件夹" 这个选项, 但为了便于管理还多了一层汇总图片的文件夹, 避免多个文档的时候图片文件夹一样多反而不利于管理. 

Typora 的图片引用方式之一

Typora 的图片引用方式之一

配置完成之后, 就能在 MD 文档内用快捷键 Shift+Alt+V直接将剪贴板里面复制好的图片以相对路径的方式粘贴进文档里.

或者在 MD 文档编辑区右键选择 "粘贴图片" 即可. 

右键菜单 "粘贴图片"

右键菜单 "粘贴图片"

当然你可以配置另一个 Local: Reference Path 选项, 可以实现绝对路径引用, 但是并不推荐.

Markdown Preview Enhanced

Markdown Preview Enhanced 扩展

Markdown Preview Enhanced 扩展

这个插件安装之后在 MD 文档打开后的右上角就会出现一个新的预览按钮, 第一个就是这个插件的功能, 能够用这个插件内置的渲染器来预览 MD 文档, 主要是为了弥补自带预览功能的一些不足(右键能很方便地换主题🤣).

另外这个插件的预览界面右键就会发现还自带一个 Image Helper, 能够上传图片或者以本地方式插入图片, 本地图片引用的话能够在设置页的 Image Folder Path 选项配置插入的文件夹, 如果要使用这个功能建议将这个选项配置为 /.assets

Image Helper 本地路径

Image Helper 本地路径

Markdown Preview Github Styling

Markdown Preview Github Styling 扩展

Markdown Preview Github Styling 扩展

这个插件主要是为了替换 VS Code 自带的预览主题为 Github 的渲染样式, 如果不喜欢的其实也可以不装, 毕竟只能白色主题还是不太完美, 自带的预览对于上面的 Preview Enhanced 各有千秋, 可以下面找到软件配置章节里对自带的预览页进行配置.

markdownlint

markdownlint 扩展

markdownlint 扩展

这个扩展是专门针对 Markdown 的语法风格检查, 但是由于为了要遵守 "最大兼容" 原则, 有一些规则实际上没有必要用, 可以在配置里面专门设置规则启用与关闭:

打开插件设置界面, 点击右上角的 "打开设置(json)". 

打开设置(json)

打开设置(json)

进入 json 编辑界面, 另起一行输入(如果已经有内容则需要在上一行末尾加半角逗号,):

"markdownlint.config": {  
"MD013": false,  
"MD033": false,  
"MD024": false,  
"MD028": false  
}

配置写入示例

上面的 "MD013", "MD033", "MD024" 分别表示 MD 的规范条目:

  • MD013: 单行长度限制.
  • MD033: 限制行内 HTML 插入.
  • MD024: 不能存在重复标题.
  • MD028: 区块语法内不能插入空行.

这些规则将会全局启用.

上面都是 CX 自己使用的时候按需配置的条目, 如果要自己配置可以参见规则文档:

markdownlint/Rules.md at v0.24.0 · DavidAnson/markdownlint

可以自由为单独的工作区及文件夹配置单独的规则, 只需要在当前 MD 文档的文件夹目录下新建一个 .markdownlint.json 文件, 里面写入规则语法即可, 具体的规则语法可以参照插件的介绍文档:

  • markdownlint - Visual Studio Marketplace
  • vscode-markdownlint/README.md at main · DavidAnson/vscode-markdownlint

Word Count CJK

Word Count CJK 扩展

这个扩展是为了中文字数统计而生的, 对于编辑 MD 和纯文本中文文档的时候很有用处, 安装后也无需过多配置, 打开 MD 文档或者纯文本文档就会直接在左下角最右边显示当前文档的中文字符数量:

字数统计效果

软件配置

这里主要涉及的是 VS Code 本身的配置文件, 区别于上面的插件配置, 这个配置文件可全局配置也可以单独针对 Markdown 配置.

由于 CX 本人不只是拿 VS Code 写 Markdown, 所以的部分选项会针对 MD 语言单独设置.
这样做不会影响其他语言的文件编辑.

字体显示

进入编辑器随意新建一个或者打开一个 MD 文档, 点击右上角的第一个按钮(如果安装了 Markdown Preview Enhanced 扩展就应该点击第二个预览按钮)进入 VS Code 自带的双窗口预览, 如果这时输入一点中文字符进去你就会发现问题所在:

打开预览

双窗口预览状态

有几个很严重的问题凸显出来:

  • 字号太小.
  • 字体不适于阅读.
  • 字体颜色发灰, 不适合阅读.

在写代码的时候大多数都使用了等宽字符来加强辨识度, 而这些字体根本没有考虑中文的显示而直接使用了默认的宋体, 实在是丑出天际, 要说辨识度的确是 Max, 但是要拿来让我长时间编辑文档的时候看, 无异于对眼睛的 "强奸", 甚至不如用记事本.

所以这里需要对 MD 的语言单独配置字体, 打开 VS Code 的设置: 

打开设置

点击右上角 "打开设置(json)" 进入配置文件编辑: 

打开设置(json)

打开 json 配置文件, 另起一行输入以下内容:

"markdownmarkdown": {  
"files.trimTrailingWhitespace": false,  
"editor.fontFamily": "微软雅黑, Ubuntu mono, Consolas, Courier New, monospace",  
"editor.fontSize": 16,  
"editor.lineNumbers": "interval"  
}

以上条目的具体作用:

  • files.trimTrailingWhitespace: 删除行尾空格.

    因为硬断行是 MD 规范中许可的行为, 但是 VS Code 会默认自动删除行尾的空格, 所以如果要使用硬断行则需要单独针对 MD 设置.

    可以参照 Typora 为硬断行行为的写的文档, 了解软硬断行之间的区别: Whitespace and Line Breaks

  • editor.fontFamily: 字体家族设置, 可以使用已安装的字体, 以先后顺序应用.
  • editor.fontSize: 字体大小.
  • editor.lineNumbers: 行号显示模式, 这里设置的是每十行主动显示一次, 如果需要不显示行号可以设置为 off, 其余可用的项目还有: on, 总是显示; relative, 除光标所在行都显示.

还有很多项目都可以针对 MD 单独启用, 上面只是列举了 CX 自己在使用的单独配置.

语言行为设置

这里指的是 VS Code 里面处理 Markdown 时候的默认行为设置, 因为 VS Code 自带了对 Markdown 的渲染预览支持所以这里还可以对 VS Code 自带的预览样式也一起设置:

Markdown 语言行为

设置中输入 "Markdown" 就可以检索到有关 Markdown 的所有设置, 位于扩展中的第一个 "Markdown" 就是 VS Code 自身处理 MD 的行为设置.

在这里主要配置的项目有

  • Preview: Font Family: 预览中使用的字体.

    这里可以使用自己安装的字体, 也可以不需要设置, 因为这里使用的就是系统默认的字体(终于不是宋体了.)

  • Preview: Font Size: 预览中使用的字体大小.

    建议设置为比编辑区小一号即可.

  • Preview: Linkify: 预览中对于链接的自动识别.

    建议取消勾选, 因为自动识别不是 MD 规范中的行为, 不要把识别交给渲染器解决, 应该手动使用 <> 自动链接语法.

因为 VS Code 新建文件不会默认选择一个语言, 与其手动选择语言不如把它新建文件默认的语言就设置为 MD:

默认新文件语言

打开设置, 搜索 "默认语言" 就能找到 VS Code 新建文件时使用的语言, 直接输入 markdown 即可, 下次使用 Ctrl+N 或者其他方式新建文件后就默认使用 MD 作为语言格式了.

其他建议

现在再重新打开一篇 Markdown 中文文档看一下效果, 是不是比起最初要好得多了呢?

修改配置后

上图使用的字体是 "思源黑体 CN Regular".

修改配置前

这时应该立刻登录 Github 或者微软账号来同步这些好不容易设置好的配置项目: 

登录账户

还可以打开资源管理器图标展开大纲视图: 

图 12

能够根据标题层次自动生成大纲.

建议打开自动跟随光标显示: 

自动跟随光标显示

再去看一看 VS Code 为 Markdown 写的使用提示(本文也参照了这篇使用提示):

Markdown editing with Visual Studio Code

如果要要将写好的 Markdown 文档转换成 PDF 或者其他格式, 可以试试用扩展 Markdown PDF 或者 Print

Markdown PDF

Markdown PDF

Print

Print

结语

除去 VS Code 专门为 Markdown 适配的编辑体验, 还有很多本身就有的软件功能能给编辑体验有很大改善, 比如能把不同的文件夹保存为一个工作区, 自带 Git 版本管理, 自动保存和意外丢失保护等等.

VS Code 是一个强大的编辑器, 本文也仅仅只是以 Markdown 编辑的角度去用 VS Code, 如果愿意完全可以使用其他扩展和自带的无数快捷键实现更加流畅的编辑体验.

本文禁止转载或摘编

无技

我系无计,精通孫子兵法,擅長紙上談兵