feat(markdown): support import code blocks (close #15)

Author: meteorlxy

Diff for: docs/guide/markdown.md

@@ -299,6 +299,71 @@ This v-pre extension is supported by our built-in plugin.
 Config reference: [markdown.code.vPre](../reference/config.md#markdown-vpre)
 :::
 
+### Import Code Blocks
+
+You can import code blocks from files with following syntax:
+
+```md
+<!-- minimal syntax -->
+@[code](../foo.js)
+```
+
+If you want to partially import the file:
+
+```md
+<!-- partial import, from line 1 to line 10 -->
+@[code{1-10}](../foo.js)
+```
+
+The code language is inferred from the file extension, while it is recommended to specify it explicitly:
+
+```md
+<!-- specify the code language -->
+@[code js](../foo.js)
+```
+
+In fact, the second part inside the `[]` will be treated as the mark of the code fence, so it supports all the syntax mentioned in the above [Code Blocks](#code-blocks) section:
+
+```md
+<!-- line highlighting -->
+@[code js{2,4-5}](../foo.js)
+```
+
+Here is a complex example:
+
+- import line 3 to line 10 of the `'../foo.js'` file
+- specify the language as `'js'`
+- highlight line 3 of the imported code, i.e. line 5 of the `'../foo.js'` file
+- disable line numbers
+
+```md
+@[code{3-10} js{3}:no-line-numbers](../foo.js)
+```
+
+Notice that path aliases are not available in import code syntax. You can use following config to handle path alias yourself:
+
+```js
+module.exports = {
+  markdown: {
+    importCode: {
+      handleImportPath: (str) =>
+        str.replace(/^@src/, path.resolve(__dirname, 'path/to/src')),
+    },
+  },
+}
+```
+
+```md
+<!-- it will be resolved to 'path/to/src/foo.js' -->
+@[code](@src/foo.js)
+```
+
+::: tip
+This import code extension is supported by our built-in plugin.
+
+Config reference: [markdown.importCode](../reference/config.md#markdown-importcode)
+:::
+
 ## Using Vue in Markdown
 
 This section will introduce some basic usage of Vue in Markdown.

Diff for: docs/reference/config.md

@@ -427,6 +427,29 @@ You should not configure it unless you understand what it is for.
 - Also see:
   - [Cookbook > Markdown and Vue SFC](../advanced/cookbook/markdown-and-vue-sfc.md)
 
+### markdown.importCode
+
+- Type: `ImportCodePluginOptions | false`
+
+- Details:
+
+  Options for VuePress built-in markdown-it import-code plugin.
+
+  Set to `false` to disable this plugin.
+
+- Also see:
+  - [Guide > Markdown > Syntax Extensions > Import Code Blocks](../guide/markdown.md#import-code-blocks)
+
+#### markdown.importCode.handleImportPath
+
+- Type: `(str: string) => string`
+
+- Default: `(str) => str`
+
+- Details:
+
+  A function to handle the import path of the import code syntax.
+
 ### markdown.links
 
 - Type: `LinksPluginOptions | false`
@@ -442,7 +465,7 @@ You should not configure it unless you understand what it is for.
 - Also see:
   - [Guide > Markdown > Syntax Extensions > Links](../guide/markdown.md#links)
 
-### markdown.links.internalTag
+#### markdown.links.internalTag
 
 - Type: `'a' | 'RouterLink'`
 
@@ -454,7 +477,7 @@ You should not configure it unless you understand what it is for.
 
   By default, this plugin will transform internal links to `<RouterLink>`. You can set this option to `'a'` to disable this feature.
 
-### markdown.links.externalAttrs
+#### markdown.links.externalAttrs
 
 - Type: `Record<string, string>`
 
@@ -464,7 +487,7 @@ You should not configure it unless you understand what it is for.
 
   Additional attributes for external links.
 
-### markdown.links.externalIcon
+#### markdown.links.externalIcon
 
 - Type: `boolean`
 

Diff for: docs/zh/guide/markdown.md

@@ -302,6 +302,71 @@ v-pre 扩展是由我们的内置插件支持的。
 配置参考： [markdown.code.vPre](../reference/config.md#markdown-vpre)
 :::
 
+### 导入代码块
+
+你可以使用下面的语法，从文件中导入代码块：
+
+```md
+<!-- 最简单的语法 -->
+@[code](../foo.js)
+```
+
+如果你只想导入这个文件的一部分：
+
+```md
+<!-- 仅导入第 1 行至第 10 行 -->
+@[code{1-10}](../foo.js)
+```
+
+代码语言会根据文件扩展名进行推断，但我们建议你显式指定：
+
+```md
+<!-- 指定代码语言 -->
+@[code js](../foo.js)
+```
+
+实际上，`[]` 内的第二部分会被作为代码块标记来处理，因此在上面 [代码块](#代码块) 章节中提到的语法在这里都可以支持：
+
+```md
+<!-- 行高亮 -->
+@[code js{2,4-5}](../foo.js)
+```
+
+下面是一个复杂的例子：
+
+- 导入 `'../foo.js'` 文件的第 3 行至第 10 行
+- 指定语言为 `'js'`
+- 对导入代码的第 3 行进行高亮，即 `'../foo.js'` 文件的第 5 行
+- 禁用行号
+
+```md
+@[code{3-10} js{3}:no-line-numbers](../foo.js)
+```
+
+需要注意的是，路径别名在导入代码语法中不会生效。你可以通过下面的配置来自行处理路径别名：
+
+```js
+module.exports = {
+  markdown: {
+    importCode: {
+      handleImportPath: (str) =>
+        str.replace(/^@src/, path.resolve(__dirname, 'path/to/src')),
+    },
+  },
+}
+```
+
+```md
+<!-- 会被解析至 'path/to/src/foo.js' -->
+@[code](@src/foo.js)
+```
+
+::: tip
+导入代码扩展是由我们的内置插件支持的。
+
+配置参考： [markdown.importCode](../reference/config.md#markdown-importcode)
+:::
+
 ## 在 Markdown 中使用 Vue
 
 这一章节会介绍 Vue 在 Markdown 中一些基本用法。

Diff for: docs/zh/reference/config.md

@@ -426,6 +426,29 @@ module.exports = {
 - 参考：
   - [Cookbook > Markdown 与 Vue SFC](../advanced/cookbook/markdown-and-vue-sfc.md)
 
+### markdown.importCode
+
+- 类型： `ImportCodePluginOptions | false`
+
+- 详情：
+
+  VuePress 内置的 markdown-it 导入代码插件的配置项。
+
+  设置为 `false` 可以禁用该插件。
+
+- 参考：
+  - [指南 > Markdown > 语法扩展 > 导入代码块](../guide/markdown.md#导入代码块)
+
+#### markdown.importCode.handleImportPath
+
+- 类型： `(str: string) => string`
+
+- 默认值： `(str) => str`
+
+- 详情：
+
+  一个函数，用于处理导入代码语法中的文件导入路径。
+
 ### markdown.links
 
 - 类型： `LinkPluginOptions | false`
@@ -441,7 +464,7 @@ module.exports = {
 - 参考：
   - [指南 > Markdown > 语法扩展 > 链接](../guide/markdown.md#链接)
 
-### markdown.links.internalTag
+#### markdown.links.internalTag
 
 - 类型： `string`
 
@@ -453,7 +476,7 @@ module.exports = {
 
   默认情况下，该插件会把内部链接转换为 `<RouterLink>` 。你可以把该选项设置为 `'a'` 来禁用这个功能。
 
-### markdown.links.externalAttrs
+#### markdown.links.externalAttrs
 
 - 类型： `Record<string, string>`
 
@@ -463,7 +486,7 @@ module.exports = {
 
   为外部链接添加额外的属性。
 
-### markdown.links.externalIcon
+#### markdown.links.externalIcon
 
 - 类型： `boolean`
 

Diff for: packages/@vuepress/markdown/__tests__/__fixtures__/importCode.js

@@ -0,0 +1,5 @@
+const msg = 'hello from js'
+
+console.log(msg)
+
+console.log('foo bar')

Diff for: packages/@vuepress/markdown/__tests__/__fixtures__/importCode.md

@@ -0,0 +1,5 @@
+# msg
+
+hello from md
+
+## foo bar

Diff for: packages/@vuepress/markdown/__tests__/plugins/__snapshots__/importCodePlugin.spec.ts.snap

@@ -0,0 +1,24 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`@vuepress/markdown > plugins > importCodePlugin compatibility with codePlugin should terminate paragraph 1`] = `
+<div class="language-javascript ext-js line-numbers-mode"><pre v-pre class="language-javascript"><code>const msg = 'hello from js'
+
+console.log(msg)
+
+console.log('foo bar')
+</code></pre>
+  <div class="highlight-lines">
+    <div class="highlight-line">&nbsp;</div><br>
+    <div class="highlight-line">&nbsp;</div>
+    <div class="highlight-line">&nbsp;</div><br>
+  </div>
+  <div class="line-numbers"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br><span class="line-number">5</span><br></div>
+</div>
+<div class="language-markdown ext-md"><pre v-pre class="language-markdown"><code># msg
+
+hello from md
+
+## foo bar
+</code></pre>
+</div>
+`;