使用 VSCode 搭建一个惊人的 Markdown Editor

  VSCodean hour read (About 8372 words)

本文使用 Visual Studio Code 构建了一个出色的，不逊色于其它任何一款的 Markdown 编辑器 环境。

本环境中实现了最基本的实时 Markdown 效果预览（所见即所得），语法规范（Markdown linting）以及基于 Md 原文档快速生成 Html、Docx 和 PDF 文档的能力，并具有生成许多其他格式文档（jpeg、png）的潜力。当然你也可以基于此环境，并且结合个人需要进行适当的功能或插件扩展。

博主在安装配置使用过程中查阅了网络上很多的相关博文，也遇到过很多的问题，为了感谢学习过程中各位大佬的帮助以及分享给更多的新手使用，以作此文。文中如有表述不正确的地方，望各位大佬不吝指正~~~

话不多说，下面正式开始基于 VS Code 的 MarkDown 编译器环境搭建 >>>

Pre-installed Preparation

开始本博文学习之前，你需要有 必要的 VS Code && MarkDown 基础概念储备。其中，

更多 VS Code 相关内容，请关注博主 Visual Studio Code 博文系列 ↓↓↓↓↓↓↓↓

之一 >>> Visual Studio Code (VS Code) 你们都在用吗 ?

之二 >>> 玩转 VSCode 之配置远程开发环境

之三 >>> 玩转 VSCode 之配置 C/C++ 语言开发环境

之四 >>> 玩转 VSCode 之配置 Python 语言开发环境

更多 MarkDown 相关内容，请关注博主 Hexo 博文系列 ↓↓↓↓↓↓↓↓

>>> 打造沉浸式写作体验，你需要试试-Markdown-Editor

相信通过对上述内容的学习：你已经拥有了一个 VS Code 编辑器，并且已经掌握了基础的 MarkDown 语法规范。

熟悉 VS Code 开箱即用的 MarkDown 功能

VS Code 系统中内置了许多基本的，开箱即用的 MarkDown 功能，你无需安装任何插件就可以使用。

下面，让我们来探索一下这些作为你成为 MarkDown 专家的第一步。

编辑 MarkDown 项目

我们知道：VScode 中所有操作都是基于文件和文件夹的，但我们更多强调的是 VSCode 以文件夹的形式来组织管理工程项目（当然，你可以仅仅操作一个 md 文件）。

故，首先你可以创建一个单独用来存储所有 Markdown 文档的文件夹，这里我的为：MarkDownWSC。你可以将其看作是 Markdown 文档的一个存储仓库，不只是单个文件的编辑，这对于一次性创建和编辑给定的许多文档都非常方便。

接下来，在 VS Code 中以打开文件夹（Ctrl + K + O）的方式，打开 MarkDownWSC 文件夹。

然后创建一个 HelloWorld.md 的 Markdown 文件，并依据 Markdown 语法规范编辑以下内容：

1
2
3
4
5
6
7
# Head 1
## Head 2
### Head 2

Hello, welcome to markdown world!

We will learn how to operate MarkDown in vscode.

也就是说，和普通文本编辑器一样，VS Code 也支持 Markdown 文档的编辑。

同时，你可以借鉴前面我们在 VSCode 项目管理机制 中提到过的 单项目管理和配置，VS Code 也允许我们 创建 几个 跟当前文件夹或者跟 Markdown 项目有关的配置文件。在这些配置文件中，你可以进行和 Markdown 编辑、渲染、插件使用等有关的所有配置（使用文件夹设置 .vscode\settings.json）。

尝试 Markdown 预览器

和普通文本编辑器不同的是，VS Code 系统还内置了一个 Markdown 的预览器，这可以帮助我们一边编辑 Markdown 文档内容，一边实时地预览效果。

VS Code 中，提供了两种预览方式：

[1] >>>> 通过快捷键 [Ctrl + Shift + V]，单独打开一个 HTML 风格的 MarkDown 代码预览窗口，进行效果查看。

[2] >>>> 通过快捷键 [Ctrl + K V]，来打开一个位于右侧的，侧边预览窗口。额外的，你可以在左侧窗格的 Markdown 文档中添加文本，并在右侧的 HTML 预览窗格中查看这些更改（推荐）。

Config User Snippets For MarkDown

对于编辑 Markdown 文档而言，User Snippets（代码片段）的使用可以极大的提高你的创作效率。

VS Code 中，你可以通过 >>>> 打开命令面板 [Ctrl + Shift + P] >>>> 选择 [Snippets: Configure User Snippets] >>>> 选择打开 [markdown.json (Markdown)] 文件，默认配置文件内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    // Place your snippets for markdown here. Each snippet is defined under a snippet name and has a prefix, body and 
    // description. The prefix is what is used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
    // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. Placeholders with the 
    // same ids are connected.
    // Example:
    // "Print to console": {
    // "prefix": "log",
    // "body": [
    //     "console.log('$1');",
    //     "$2"
    // ],
    // "description": "Log output to console"
    // }
}

同时，你需要在项目组织目录 MarkDownWSC/.vscode 下的配置文件 settings.json 中开启 User Snippets 开关：

1
2
3
4
5
6
7
8
9
{
"[markdown]": {
    "editor.quickSuggestions": {
        "comments": "off",
        "strings": "off",
        "other": "on"
    }
}
}

配置完成之后，如何自定义我们需要的 Snippets 呢？！！！事实上，在 markdown.json 上面有一大段注释的代码，提供了一个 Example 例子：

1
2
3
4
# "Print to console" >>>> 快捷语句的标题
# "prefix" >>>> 快捷语句触发的关键字
# "body" >>>> 快捷语句触发后的代码，使用 `$1`，`$2` 等指定光标位置。这些数字指定了光标跳转的顺序。特别地，`$0` 表示最终光标位置
# "description" >>>> 快捷语句的功能描述

你可以取消掉 Example 注释，通过 log 触发一下。

这里，我自己写了一些比较常用的 Markdown 片段供你参考：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
"Print to ```shell```":{
    "prefix": "```shell",
    "body": [
        "```shell",
        "$1",
        "```"
    ],
    "description": "build code snippets of [shell]"
},
"Print to ```bash```":{
    "prefix": "```bash",
    "body": [
        "```bash",
        "$1",
        "```"
    ],
    "description": "build code snippets of [bash]"
},
"Print to ```javascript```":{
    "prefix": "```javascript",
    "body": [
        "```javascript",
        "$1",
        "```"
    ],
    "description": "build code snippets of [javascript]"
},
"Print to ```css```":{
    "prefix": "```css",
    "body": [
        "```css",
        "$1",
        "```"
    ],
    "description": "build code snippets of [css]"
},
"Print to ```html```":{
    "prefix": "```html",
    "body": [
        "```html",
        "$1",
        "```"
    ],
    "description": "build code snippets of [html]"
},
"Print to ```python```":{
    "prefix": "```python",
    "body": [
        "```python",
        "$1",
        "```"
    ],
    "description": "build code snippets of [python]"
},
"Print to ```java```":{
    "prefix": "```java",
    "body": [
        "```java",
        "$1",
        "```"
    ],
    "description": "build code snippets of [java]"
},
"Print to ```yaml```":{
    "prefix": "```yaml",
    "body": [
        "```yaml",
        "$1",
        "```"
    ],
    "description": "build code snippets of [yaml]"
},
"Print to ```text```":{
    "prefix": "```text",
    "body": [
        "```text",
        "$1",
        "```"
    ],
    "description": "build code snippets of [text]"
},
"Print to ```json```":{
    "prefix": "```json",
    "body": [
        "```json",
        "$1",
        "```"
    ],
    "description": "build code snippets of [json]"
}

除了 VSCode 开箱即用的功能外，为了创建更好的 MarkDown 编辑环境，我们需要借助其它插件来为 VSCode 添加额外的 MarkDown 功能。

事实上，这和基于 VSCode 搭建各种语言（Python、C、C++）开发环境类似，配置 MarkDown 编辑环境就是 >>>> 组合安装、配置多种 MarkDown 相关插件的过程。

Description Of Optional Extensions

你在查阅资料的过程中，可能了解到很多的插件推荐安装博文。

这里，首先我会对网络上主流的 MarkDown 插件功能进行简单介绍，然后通过完成对不同插件的主要功能测试，结合使用效果，给出本文所采用的插件搭配推荐方案。

希望这一小节学习后，你可以自主决定 >>>> 你个人的 MarkDown（In VSCode）环境插件搭配方案 <<<< （这里更重要的是为你提供一种插件选择搭配的参考思路）

需要说明的，下文关于【插件评价】仅代表我个人的观点，是根据我个人的认知以及使用习惯来进行推荐的，不代表所有！！！

目前，网络上推荐安装的主流的 Markdown 插件有：

Markdown All in One

Extensions search >>>> Markdown All in One [Yu Zhang] >>>> 该插件功能如其名，集成了编辑 Markdown 文档时所需要的大部分功能（All in One）。

其主要功能包括：

  1. Markdown 样式快捷键支持
  2. 目录支持
  3. 列表自动化处理和表格的自动格式化
  4. 数学公式支持（KaTeX）
  5. 自动补全

可以看出，日常使用已经足够了，这也是伴随无数人在 VS Code 中最早体验的 Markdown 扩展了。

插件评价 >>>> 可作为 Markdown 环境基础插件（可选，功能较多，效果一般），搭配其它提供额外功能的 专用功能插件 使用。

Markdown Lint

Extensions search >>>> markdownlint [David Anson] >>>> Markdown 代码检查工具，用于规范编辑时的 Markdown 语法。

Markdown 默认的语法格式相当的宽泛，你可以下载并遵循这个插件的规范，极大程度上可以帮助你编辑出具有统一规范格式的 Markdown 文档。为 Markdown 开发提供便利，同时又大幅节省了自己制定语法规范的成本。

这里，我们给出 Markdown Lint 语法规范的 >>>> 警告信息表 <<<< 以便查询解决 ↓↓↓↓↓

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
# MD001 - Heading levels should only increment by one level at a time
Description >>>> 标题级数只能依次创建，不能隔级创建，必须 h1-h2-h3... 这样

# MD002 - First heading should be a top level heading
Description >>>> 文档的第一个标题必须是最高级的标题，也就是 h1

# MD003 - Heading style
Description >>>> 整篇文档的标题格式要采取统一的，例如保持：`### XXX ###`

# MD004 - Unordered list style
Description >>>> 整篇文档的无序列表的格式要一致

# MD005 - Inconsistent indentation for list items at the same level
Description >>>> 同一个等级的列表的缩进要一致

# MD006 - Consider starting bulleted lists at the beginning of the line
Description >>>> 一级标题不能够缩进

# MD007 - Unordered list indentation
Description >>>> 无序列表嵌套的时，默认采取两个空格的缩进方式

# MD009 - Trailing spaces [Expected: 0 or 2; Actual: 1]
Description >>>> 行尾空格数为 0 或 2，为 1 或超出 2 之后会有警告，其中两个空格表示换行

# MD010 - Hard tabs
Description >>>> 不能使用 tab 来进行缩进，要使用空格

# MD011 - Reversed link syntax
Description >>>> 内联形式的链接和创建方式是否错误，中括号和圆括号是否使用正确

# MD012 - Multiple consecutive blank lines
Description >>>> 文档中不能有连续的空行，在代码块中这个规则不会生效

# MD013 - Line length
Description >>>> 默认行的最大长度是 80，对表格代码块标题都起效果

# MD014 - Dollar signs used before commands without showing output
Description >>>> 在代码块中，终端命令前面不需要有美元符号，如果如果代码块中既有终端命令，也有命令的输出，则终端命令前可以有美元符号($)

# MD018 - No space after hash on atx style heading
Description >>>> 标题格式如果是 "atx" 的话，在 # 号和文字之间需要一个空格隔开

# MD019 - Multiple spaces after hash on atx style heading
Description >>>> 标题格式如果是 "atx" 的话，在 # 号和文字之间只需要一个空格隔开，不需要多个

# MD020 - No space inside hashes on closed atx style heading
Description >>>> 在 closed_atx 格式的标题中，文字和前后的 # 号之间都需要一个空格隔开

# MD021 - Multiple spaces inside hashes on closed atx style heading
Description >>>> 在 closed_atx 格式的标题中，文字和前后的 # 号之间只需要一个空格隔开，不能有多余的

# MD022 - Headings should be surrounded by blank lines
Description >>>> 标题的上下行必须都是空格

# MD023 - Headings must start at the beginning of the line
Description >>>> 标题行不能缩进

# MD024 - Multiple headings with the same content
Description >>>> 在文档中不能有重复性的标题

# MD025 - Multiple top level headings in the same document
Description >>>> 同一个文档中，只能有一个最高级的标题，即默认只能有一个一级标题 # XX #；文档开头处的 Front Matter 中的 title，可作为文档的最高级（一级）标题

# MD026 - Trailing punctuation in heading
Description >>>> 标题的末尾不能有 ". , ; : ! ?"  这些符号

# MD027 - Multiple spaces after blockquote symbol
Description >>>> 在创建引用块的时候，右尖号与文字之间必须有且只有一个空格

# MD028 - Blank line inside blockquote
Description >>>> 两个引用区块间不能仅用一个空行隔开，或者说同一引用区块中不能有空行；如果一行中没有内容，则这一行也要用 > 开头

# MD029 - Ordered list item prefix
Description >>>> 有序列表的前缀序号格式必须只用1或者从1开始的加1递增数字

# MD030 - Spaces after list markers
Description >>>> 列表（有序、无序）的前缀符号和文字之间用 1 个空格隔开；在列表嵌套或者同一列表项中有多个段落时，无序列表缩进两个空格，有序列表缩进 3 个空格

# MD031 - Fenced code blocks should be surrounded by blank lines
Description >>>> 单独的代码块前后需要用空行隔开（除非是在文档开头或末尾），否则有些解释器不会解释为代码块

# MD032 - Lists should be surrounded by blank lines
Description >>>> 列表（有序、无序）前后需要用空行隔开，否则有些解释器不会解释为列表；列表的缩进必须一致，否则会警告

# MD033 - Inline HTML
Description >>>> 文档中不允许使用 html 语句

# MD034 - Bare URL used
Description >>>> 单纯的链接地址需要用尖括号 <> 包裹，否则有些解释器不会解释为链接

# MD035 - Horizontal rule style
Description >>>> 创建水平线时整篇文档要统一，要和文档中第一次创建水平线使用的符号一致

# MD036 - Emphasis used instead of a heading
Description >>>> 不能用强调来代替标题 **xxx**

# MD037 - Spaces inside emphasis markers
Description >>>> 强调的符号和文字之间不能有空格

# MD038 - Spaces inside code span elements
Description >>>> 当用单反引号创建代码段的时候，单反引号和它们之间的代码不能有空格；如果要把单反引号嵌入到代码段的首尾，创建代码段的单反引号和嵌入的单反引号间要有一个空格隔开

# MD039 - Spaces inside link text
Description >>>> 链接名和包围它的中括号之间不能有空格，但链接名中间可以有空格

# MD040 - Fenced code blocks should have a language specified
Description >>>> 单独的代码块（此处是指上下用三个反引号包围的代码块）应该指定代码块的编程语言，这一点有助于解释器对代码进行代码高亮

# MD041 - First line in file should be a top level heading
Description >>>> 文档的第一个非空行应该是文档最高级的标题，默认是 1 级标题

# MD042 - No empty links
Description >>>> 链接的地址不能为空

# MD043 - Required heading structure
Description >>>> 要求标题遵循一定的结构，默认是没有规定的结构

# MD044 - Proper names should have the correct capitalization
Description >>>> 指定一些名称，会检查它是否有正确的大写，例如（names 参数）指定：JavaScript，写成 javaScript && javascript 会被检测

# MD045 - Images should have alternate text (alt text)
Description >>>> 图片链接必须包含描述文本 all text

# MD046 - Code block style
Description >>>> 整篇文档采用一致的代码格式

# MD047 - Files should end with a single newline character
Description >>>> 文档末尾需要一个空行结尾

事实上，有时候我们想要屏蔽 Markdown Lint 对某些警告信息的检测，你可以在用户配置文件（settings.json）中添加如下配置：

1
2
3
4
5
6
7
"markdownlint.config": {
    "default": true,
    "MD014": false, // 警用 代码内美元符号限制 警告
    "MD033": false, // 警用 HTML 标签使用 警告
    "MD036": false, // 警用 强调来代替标题 检测警告
    "MD045": false // 警用 图片链接必须包含描述文本 警告
}

| ================================== Split Line ===================================== |

插件评价 >>>> 必备插件（必选），以提供 Markdown 代码检查功能。

Markdown Shortcuts

Extensions search >>>> Markdown Shortcuts [Mdickin] >>>> 提供编写 Markdown 的高效快捷键支持，可以极大的帮助你提高 Markdown 编辑的效率。

通过特定的快捷键，你可以实现一键加粗、插入代码块、插入引用、添加不同等级标题等等 …….实现类似于 MarkdownPad、Typora、Aton 中的快捷操作，提高你的创作效率。

该功能和插件 Markdown All in One 子功能有重叠，其中少部分快捷键可能与 Markdown All in One 冲突，实际测试时以该插件为高优先级。当然了，你也可以自行修改快捷键设置来解决冲突。

但是需要考虑到的一个问题就是 >>>> 为了保证插件快捷键符合 “大众” 习惯，并且和 VS Code 系统自身快捷键兼容，快捷键设置成本增加 >>>> 快捷键记忆成本大幅度增加。

插件评价 >>>> 一般插件（可选），我个人更倾向于使用 Markdown 自身语法格式（可配合 User Snippets 使用）。

Markdown+Math

Extensions search >>>> Markdown+Math [Goessner] >>>> 使用 KaTeX 引擎，提供数学公式渲染（用于 Markdown 对公式进行正常显示）。

虽然和 Markdown All in One 子功能（Math）都是使用 KaTeX 引擎，但渲染效果更好。使用时需要将 Markdown All in One 的 math.enabled 取消掉。

插件评价 >>>> 一般插件（可选），更多的是在不支持数学公式的 Markdown 环境中作为补充插件或增强公式渲染使用。

Markdown Preview Github Styling

Extensions search >>>> Markdown Preview Github Styling [Matt Bierner] >>>> 提供 Github 样式的 Markdown 文档预览。

VS Code 开箱即用的 Markdown 预览器预览效果一般，该插件可以将其修改为 Github 风格的预览样式。

插件评价 >>>> 一般插件（可选），可在不支持更好预览模式的环境中提供 Github 样式的 Markdown 文档预览。

Markdown PDF && Pandoc

写好的 Markdown 文档是为了分享给其他人查看的，而其结果的展示需要使用专用编译器，或者安装特定的查看扩展。

那么，VS Code 中有没有相关的插件，可以将撰写好的 Markdown 文档转化为常见的 PDF、Docx 文件，甚至是可在浏览器查看的 HTML 文档？？？这就能够结合 Markdown 编译的简便性和 PDF 等文档的通用性，使得文档编写和修改过程效率更高。

当然是有的，这里提供两种方法，你可以根据个人需求选择适合自己的方法：

1. Markdown PDF
2. VSCode-Pandoc + Pandoc

事实上，任何可以将 Markdown 文档输出为 HTML 格式的插件（例如：Markdown All In One && Markdown+Math）均可以实现 PDF 的导出（浏览器打开 HTML 格式页面后，选择存储为 PDF 即可）。但考虑到转化效果以及其它格式的转化，需要更进一步了解上面的两种方法。

下面分别来看两种方法的介绍、安装以及配置过程：

Markdown PDF

Extensions search >>>> Markdown PDF [Yzane] >>>> Convert Markdown to PDF（HTML && PNG && JPEG）。

尽管好多人都说，Markdown PDF 插件不支持 LaTex，导出效果不好，要弃坑云云….之类的。

但我仍然将其列为一个一般（可选）插件，这是出于相对于其它插件复杂的安装、配置以及对 VS Code 的性能影响，通过简单配置的 Markdown PDF 插件对于 Markdown 文档构建一个表现较好的 PDF（HTML && PNG && JPEG）已足够满足日常需要了。

1] >>>> 安装问题

Markdown PDF 插件专门用来为 Markdown 文档导出其 PDF 格式，需要搭配 Chrome 浏览器（实际上基于 Chromium 内核的浏览器都可以）。插件安装成功后，等待 Chromium 自动安装（可在右下角消息中心关注其下载状态）。

若下载失败，可以通过项目配置文件夹 MarkDownWSC/.vscode 下创建 settings.json 配置文件，来指定 Chrome 程序路径：

1
2
3
{
"markdown-pdf.executablePath": "C:\\.....",
}

2] >>>> 导出 PDF

在 Md 文档中，点击右键，出现如下选项（根据需要选择）：

1
2
3
4
5
6
markdown-pdf: Export (settings.json)
markdown-pdf: Export (pdf)
markdown-pdf: Export (html)
markdown-pdf: Export (png)
markdown-pdf: Export (jpeg)
markdown-pdf: Export (all: pdf, html, png, jpeg)

3] >>>> 导出优化

针对 “导出 PDF 格式不好” && “不支持公式显示” 的问题，做如下配置：

| >>>> 3.1 自定义 CSS 文件，优化导出 PDF 样式

Markdown PDF 插件直接导出 PDF 格式并不够美观，中文字体显示有很大问题。可以采用自定义 CSS 样式来美化导出 PDF。

你不会自定义 CSS 样式也没关系，你可从网络上下载大佬们写好的、非常漂亮的 CSS 格式文件（或直接复制内容到本地） >>>> Markdown CSS Theme，你可以先从仓库里面的 markdownX.css 文档系列中随意 Copy 一份，在项目文件夹 MarkDownWSC 下创建 css/markdownX.css 作为你个人的 CSS 样式文件。

然后，通过项目配置文件夹 MarkDownWSC/.vscode 下的 settings.json 配置 CSS 样式文件，内容如下：

1
"markdown-pdf.styles": ["css/markdownX.css"]

配置好后，你可以和默认导出 PDF 格式对比一下设置自定义 CSS 样式后的效果（不满意还可以使用其它 CSS，或真正的自定义你的 CSS 样式表）。

| >>>> 3.2. 数学公式显示优化

仅仅通过在 Markdown 文档中任意位置，引入 MathJax 标签 就可以正常显示了。标签内容如下：

1
2
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config"> MathJax.Hub.Config({ tex2jax: {inlineMath: [['$', '$']]}, messageStyle: "none" });</script>

重新生成 PDF 文件，可以发现文档中公式已经可以正常显示了。

| =========================== Split Line =========================== |

插件评价 >>>> 可选插件，通过简单安装、配置以实现一个具有良好表现（取决于自定义 CSS 样式表）的日常 [Markdown >> PDF] 转换工具。

VSCode-Pandoc + Pandoc

Extensions search >>>> vscode-pandoc [DougFinke] >>>> Renders markdown through pandoc。

如上，插件 vscode-pandoc 的功能是，仅仅是使用 Pandoc 工具来渲染 Markdown 文档。因此你还需要在当前操作系统中下载以及安装 Pandoc 文档转换工具。

Pandoc 不依赖 VS Code 编辑器，适用于多款支持 Pandoc 的编辑器（如：Typora 等）。它可以将文档 Markdown、LaTeX、HTML、Word docx 等多种标记格式之间相互转换，并支持输出 PDF、EPUB、HTML 幻灯片等多种格式。

1] >>>> Pandoc 安装

首先，你需要按照 Pandoc 安装页面 上的说明安装 Pandoc，这里提供了不同平台下 Pandoc 安装方法。

事实上，如果条件允许的话，你还可以使用 conda 或者 pip 进行 Pandoc 进行安装。

安装完成之后，可以在 DOS || Bash 中，使用 pandoc --version 命令来检查 Pandoc 是否可用。如果输出如下信息表示已安装配置成功；否者你需要在添加 [环境变量] 之后再进行尝试：

1
2
3
4
5
6
7
pandoc.exe 2.12
Compiled with pandoc-types 1.22, texmath 0.12.1.1, skylighting 0.10.4,
citeproc 0.3.0.8, ipynb 0.1.0.1
User data directory: C:\Users\XXXXXXX\AppData\Roaming\pandoc
Copyright (C) 2006-2021 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

2] >>>> 导出 HTML && Docx && PDF

| >>>> 2.1. DOS（Bash） Demo

Pandoc 安装完成之后就可以在命令行下正常使用了（不考虑 VSCode），我们先来看如何导出 >>>> HTML && Docx ：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 1. Markdown >>>> HTML
$ pandoc -s -f gfm -t html5 --css=css/markdownPad-github.css test.md -o test.html

# 参数说明：
# -s >>>> 表示使用标准模板输出
# -f >>>> 显示指定输入格式；-t >>>> 显示指定输出格式
# -f gfm -t html5 >>>> 表示：用 GFM 引擎来解析，从 Github Flavored MarkDown 到 HTML5
# --css=xxx >>>> 表示：自定义 CSS 样式表，xxx 表示样式表路径
# test.md -o test.html >>>> 表示：把 `test.md` 这个 MarkDown 文件输出成同名的 `test.html` 文件


# 2. Markdown >>>> Docx
$ pandoc test.md -o test.docx

来看如何导出 >>>> PDF ：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 2. Markdown >>>> PDF
$ pandoc test.md -o test.pdf

# 报错了：
Error producing PDF.
! Package inputenc Error: Unicode character 安 (U+5B89)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...

l.94 ...��}\label{jorek-ux5b89ux88c5ux624bux518c}}

Try running pandoc with --pdf-engine=xelatex.

这是由于 Pandoc 生成 PDF 文件需要使用 PDF 排版工具或引擎（--pdf-engine=xelatex），网络上推荐安装什么 MikTex、TexLive、CTex，这有啥区别啊？！！事实上，他们都是 TeX 排版系统的发行版，都内置了常用的文档编译器（编译引擎）：xelatex、lualatex、pdflatex。我们需要确认的是：

  1. LaTeX 是安装在原生 Windows 里还是 WSL 里？
  2. 安装 TeXLive 还是 MiKTeX？
  3. 平时编译的时候使用哪个编译器？（XeLaTeX or LuaLaTeX or pdfLaTeX）

网络上一个大佬进行了相关的测试（传送门），可以作为我们选择的依据：

1
2
3
4
5
# LaTeX配置安装大对比：TeXLive/MiKTeX、Windows/WSL；xelatex/lualatex/pdflatex 编译器的速度性能详细对比

1. WSL > Windows 原生
2. TeXLive ≈ MiKTeX（个人推荐：MiKTeX For Windows；TeXLive For WSL）
3. pdfLaTeX > XeLaTeX > LuaLaTeX

TeXLive && MiKTeX 安装问题 >>>> 会涉及到宏包（.sty）安装 >>>> MikTex 支持在编译（文档渲染）过程中提示哪个 sty（宏包） 文件缺失，提示你下载，解决了所有宏包缺失后，才可以编译导出最终的 PDF 文档；而 TexLive 不支持在编译过程中下载缺失宏包，安装时就会把所有 sty 都下载下来。

MikTex 下载完成后，需要更新 MikTex Console（Win Search），更新后如果命令执行仍有错误信息，可以定位日志文件将其中错误的 log 都删除掉即可。安装成功后，你可以在 MiKTeX\miktex\bin\x64 目录下找到 xelatex、lualatex、pdflatex 渲染工具。

再来看如何导出 >>>> PDF ：

1
2
3
# 指定渲染引擎：--pdf-engine=xelatex
# 很多博客上仍使用的是 `--latex-engin` 参数（已被移除），使用会报错：`latex-engine has been removed. Use --pdf-engine instead.`
$ pandoc --pdf-engine=xelatex test.md -o test.pdf

如果 Markdown（test.md）文档中包含中文，虽然编译（渲染）过程中不再出现错误，但是会显示如下警告，并且编译好的 PDF 文件中并没有中文。

1
2
[WARNING] Missing character: There is no 安 (U+5B89) in font [lmroman12-bold]:mapping=tex-text;!
[WARNING] Missing character: There is no 装 (U+88C5) in font [lmroman12-bold]:mapping=tex-text;!

这是由于 xelatex 引擎默认字体不支持中文字符，添加字体设置参数：-V CJKmainfont=\"Microsoft YaHei\" -V geometry:margin=2.5cm，然后再次尝试编译文档就 OK 了！！！

1
2
# Markdown >>>> PDF
$ pandoc --pdf-engine=xelatex -V CJKmainfont=\"Microsoft YaHei\" -V geometry:margin=2.5cm test.md -o test.pdf

| >>>> 2.2. VSCode Demo

再来看，如何在 VS Code 中使用 vscode-pandoc 插件来管理 Pandoc 工具进行文档编译的。

我们整理【1. DOS（Bash） Demo】中进行过的配置，先在项目配置文件夹 MarkDownWSC/.vscode 下的 settings.json 中配置如下内容：

1
2
3
4
5
{
"pandoc.docxOptString": "",
"pandoc.pdfOptString": "--pdf-engine=lualatex -V CJKmainfont=\"Microsoft YaHei\" -V geometry:margin=2.5cm",
"pandoc.htmlOptString": "-s -f gfm -t html5 --css=css/mdPreviewPlus.css",
}

配置完成后，你可以通过在需要编译（渲染、或转换）的 Markdown 文档中的任意位置 >>>> 点击快捷键 [Ctrl + K P] >>>> 系统会提示如下：

1
2
3
pdf Render as pdf document
docx Render as word document
html Render as html document

你可以根据你的需要，选择想要导出的类型（PDF && Docx && HTML）。

3] >>>> 导出优化

针对 “导出 PDF 格式不好” && “导出 HTML 报警 nonempty <title>” 的问题，做如下说明：

| >>>> 3.1 空标题问题

标准输出时，你需要和标准文档一样正确设置一个标题，即 Markdown 文档中添加 YAML 格式的 front matter，如下：

1
2
3
---
title: "Pandoc"
---

设置后，再次生成就不再产生 stderr:[WARNING] This document format requires a nonempty <title>... 警告了！！！

| >>>> 3.2 导出 PDF 格式不好

有这个问题，是由于我在使用时没有深入了解 Pandoc 工具如何自定义 PDF 的样式（对我来说，Markdown PDF 就完全够了），只是测试的话我采取了曲线救国的方式 >>>> 导出 HTML，然后浏览器中 Print 成 PDF（没有使用到 Pandoc 的精髓）。

导出 HTML 公式无法显示的问题，你可以参考：【[1] >>>> Markdown PDF】 >>>> 【1.3.2. 数学公式显示优化】。

事实上，你甚至可以使用 Pandoc 工具导出一个符合论文要求格式的 PDF 文档，功能非常强大！！！

| =========================== Split Line =========================== |

插件评价 >>>> 可选插件，功能强大的格式转换工具，可以渲染出具有严格格式要求的文档（例如：论文…），可以满足你所有的转换需要，但安装、配置过程比较复杂，使用以及学习成本较高，日常简单使用的话不推荐。

Markdown Preview Enhanced（MPE）

Extensions search >>>> Markdown Preview Enhanced [Yiyi Wang] >>>> 是一款为 Atom 以及 Visual Studio Code 编辑器编写的 超级强大的 Markdown 插件。 这款插件意在让你拥有飘逸的 Markdown 写作体验。

相信你在查阅资料过程中，肯定被安利过 MPE（Markdown Preview Enhanced），它凭借其丰富的特性支持，提供了编辑 Markdown 文档时可能用到的几乎所有功能：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
自动编辑器及预览滑动同步
导入外部文件
Code Chunk
Pandoc
Prince
ebook（电子书）
幻灯片
可扩展性
LaTeX 数学
导出 PDF, PNG, 以及 JPEG 凭借 Puppeteer
导出漂亮的 HTML（移动端支持）
编译到 GitHub Flavored Markdown
自定义预览 CSS
TOC 生成
流程图 / 时序图 以及各种其他种类的图形
嵌入 LaTeX, 渲染 TikZ, Chemfig 等图形
Task List (Github Flavored)
Image Helper（图片助手）
脚注
Front Matter
以及更多。。。

关于 MPE 详细使用说明，你可以参考 >>>> Markdown Preview Enhanced 中文说明文档。

插件评价 >>>> 可选插件，功能丰富，支持编辑 Markdown 文档时可能用到的几乎所有功能。但灵活的定制带来使用复杂度的提升，某些功能（例如：Pandoc、ebook）的使用需要单独安装相应的工具，并且相对于其它专用插件需要消耗更多的性能。

插件选用方案

结合上一小节的插件说明以及评价，你可以综合考虑个人的使用需要，选择符合你个人使用习惯的插件搭配方案，以构建一个合理的 VSCode Markdown 创作环境。

这里有一些推荐方案：

[1] >>>> 方案：Markdown Lint && MPE

如果你想在安装 VS Code 之后快速开始 Markdown 的创作，避免令人烦躁的插件选择、下载、安装、配置过程，此时，你仅仅需要一个 MPE（Markdown Preview Enhanced） 插件就可以满足你的日常使用了。

例如：MPE 开箱即用的目录（TOC）生成、不同风格的预览主题（Atom && Github && Vue…）、快速导出 PDF（HTML && PNG && JPEG）等等。

同时，你可以配合下载 Markdown Lint 扩展，以支持 Markdown 语法规范。

[2] >>>> 推荐方案：Markdown Lint && Markdown Preview Github Styling && Markdown PDF（Pandoc）&& PicGo

对我个人而言，MPE 对于性能的影响我难以接受，并且 MPE 丰富的特性于我而言不是刚需。作为一个重度强迫症，我无法忍受 MPE 预览菜单中的无效操作条目（某些功能只有安装相应工具才可以使用）。

很多时候并不是功能越多越好，适合你自己的才是最好的！！！事实上，我个人日常使用的编辑要求仅仅如下：

  1. Markdown 代码检查（Markdown Lint）
  2. 良好的侧栏预览风格（Markdown Preview Github Styling）
  3. 支持导出 PDF && HTML && Word 等格式的文档（Markdown PDF（Pandoc））
  4. 图像上传工具（PicGo）

通过一些精简的、小型的、专用替代插件，就可以在 VS Code 中帮助我们实现一个高效、惊人、影响较小的 Markdown 编辑器了。

使用 VSCode 搭建一个惊人的 Markdown Editor

https://www.orangeshare.cn/2017/09/22/shi-yong-vscode-da-jian-yi-ge-liang-ren-de-markdown-editor/

Author

Waldeinsamkeit

Posted on

2017-09-22

Updated on

2022-12-02

Licensed under

#
You need to set install_url to use ShareThis. Please set it in _config.yml.

Like this article? Support the author with

Comments

You forgot to set the shortname for Disqus. Please set it in _config.yml.
×