查看“VuePress markdown”的源代码

== 语法扩展 ==

VuePress 会使用 [https://github.com/markdown-it/markdown-it markdown-it] 来解析 Markdown 内容，因此可以借助于 markdown-it 插件来实现 [https://github.com/markdown-it/markdown-it#syntax-extensions 语法扩展] 。

本章节将会介绍 VuePress 内置支持的 Markdown 语法扩展。


=== 内置 ===

由 markdown-it 内置支持：

* [https://help.github.com/articles/organizing-information-with-tables/ 表格] (GFM)
* [https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text 删除线] (GFM)

=== 标题锚点 ===

你可能已经注意到，当你把鼠标放在各个章节的标题上时，会显示出一个 <code>#</code> 锚点。点击这个 <code>#</code> 锚点，可以直接跳转到对应章节。

<div class="tip">

标题锚点扩展由 [https://github.com/valeriangalliat/markdown-it-anchor markdown-it-anchor] 支持。

配置参考： markdown.anchor


</div>
=== 链接 ===

在你使用 Markdown 的 [https://spec.commonmark.org/0.29/#link-reference-definitions 链接语法] 时， VuePress 会为你进行一些转换。

以我们文档的源文件为例：

<pre lang="bash">└─ docs
   └─ zh
      ├─ guide
      │  ├─ getting-started.md
      │  ├─ markdown.md    # <- 我们在这里
      │  └─ README.md
      ├─ reference
      │  └─ config.md
      └─ README.md</pre>
'''原始 Markdown'''

<pre class="md">&lt;!-- 相对路径 --&gt;
[首页](../README.md)  
[配置参考](../reference/config.md)  
[快速上手](./getting-started.md)  
&lt;!-- 绝对路径 --&gt;
[指南](/zh/guide/README.md)  
[配置参考 &gt; markdown.links](/zh/reference/config.md#links)  
&lt;!-- URL --&gt;
[GitHub](https://github.com) </pre>
'''转换为'''

<pre class="vue">&lt;template&gt;
  &lt;RouterLink to=&quot;/zh/&quot;&gt;首页&lt;/RouterLink&gt;
  &lt;RouterLink to=&quot;/zh/reference/config.html&quot;&gt;配置参考&lt;/RouterLink&gt;
  &lt;RouterLink to=&quot;/zh/guide/getting-started.html&quot;&gt;快速上手&lt;/RouterLink&gt;
  &lt;RouterLink to=&quot;/zh/guide/&quot;&gt;指南&lt;/RouterLink&gt;
  &lt;RouterLink to=&quot;/zh/reference/config.html#links&quot;&gt;配置参考 &amp;gt; markdown.links&lt;/RouterLink&gt;
  &lt;a href=&quot;https://github.com&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;GitHub&lt;/a&gt;
&lt;/template&gt;</pre>

'''解释'''

* 内部链接会被转换为 <code>&lt;RouterLink&gt;</code> 以便进行 SPA 导航。
* 指向 <code>.md</code> 文件的内部链接会被转换为目标页面的路由路径，并且支持绝对路径和相对路径。
* 外部链接会被添加 <code>target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;</code> 属性。

'''建议'''

对于指向内部 Markdown 文件的链接，尽可能使用相对路径而不是绝对路径。

* 相对路径是指向目标文件的有效链接，在你的编辑器或者代码仓库中浏览源文件时也可以正确跳转。
* 相对路径在不同 locales 下都是一致的，这样在翻译你的内容时就不需要修改 locale 路径了。

<div class="tip">

链接扩展是由我们的内置插件支持的。

配置参考： markdown.links


</div>
<span id="emoji-tada"></span>
=== Emoji :tada: ===

你可以在你的 Markdown 内容中输入 <code>:EMOJICODE:</code> 来添加 Emoji 表情。

前往 [https://github.com/ikatyang/emoji-cheat-sheet emoji-cheat-sheet] 来查看所有可用的 Emoji 表情和对应代码。


<div class="tip">

Emoji 扩展由 [https://github.com/markdown-it/markdown-it-emoji markdown-it-emoji] 支持。

配置参考： markdown.emoji


</div>
=== 目录 ===

如果你想要把当前页面的目录添加到 Markdown 内容中，你可以使用 <code>toc</code> 语法。


目录中的标题将会链接到对应的标题锚点，因此如果你禁用了标题锚点，可能会影响目录的功能。

<div class="tip">

目录扩展由 [https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc @mdit-vue/plugin-toc] 支持。

配置参考： markdown.toc


</div>

=== 代码块 ===

下列代码块扩展是在 Node 端进行 Markdown 解析的时候实现的。这意味着代码块并不会在客户端被处理。

==== 行高亮 ====

你可以在代码块添加行数范围标记，来为对应代码行进行高亮：

<pre class="md">```ts{1,6-8}
import { defaultTheme, defineUserConfig } from 'vuepress'

export default defineUserConfig({
  title: '你好， VuePress',

  theme: defaultTheme({
    logo: 'https://vuejs.org/images/logo.png',
  }),
})
```</pre>


行数范围标记的例子：

- 行数范围： `{5-8}`
- 多个单行： `{4,7,9}`
- 组合： `{4,7-13,16,23-27,40}`



==== 行号 ====

你肯定已经注意到在代码块的最左侧会展示行号。这个功能是默认启用的，你可以通过配置来禁用它。

你可以在代码块添加 `:line-numbers` / `:no-line-numbers` 标记来覆盖配置项中的设置。

<pre>

````md
```ts
// 行号默认是启用的
const line2 = 'This is line 2'
const line3 = 'This is line 3'</pre>
<pre class="ts:no-line-numbers">// 行号被禁用
const line2 = 'This is line 2'
const line3 = 'This is line 3'</pre>
<pre>
**输出**

```ts
// 行号默认是启用的
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts:no-line-numbers
// 行号被禁用
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

</pre>



==== 添加 v-pre ====

由于 [模板语法可以在 Markdown 中使用](#模板语法)，它也同样可以在代码块中生效。

为了避免你的代码块被 Vue 编译， VuePress 默认会在你的代码块添加 [v-pre](https://v3.vuejs.org/api/directives.html#v-pre) 指令。这一默认行为可以在配置中关闭。


你可以在代码块添加 `:v-pre` / `:no-v-pre` 标记来覆盖配置项中的设置。



<pre>

````md
```md
&lt;!-- 默认情况下，这里会被保持原样 --&gt;
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```

```md:no-v-pre
&lt;!-- 这里会被 Vue 编译 --&gt;
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```

```js:no-v-pre
// 由于 JS 代码高亮，这里不会被正确编译
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
```</pre>
'''输出'''

<pre class="md">&lt;!-- 默认情况下，这里会被保持原样 --&gt;
1 + 2 + 3 = {{ 1 + 2 + 3 }}</pre>
<pre class="md:no-v-pre">&lt;!-- 这里会被 Vue 编译 --&gt;
1 + 2 + 3 = {{ 1 + 2 + 3 }}</pre>
<!--
在 JS 代码块上使用 :no-v-pre 的话，会在使用 shiki 时遇到一些潜在的问题，所以这里
我们实际上没有使用 :no-v-pre ，只是作为一个错误用法的示例。
-->
<pre lang="js">// 由于 JS 代码高亮，这里不会被正确编译
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}</pre>
<div class="tip">



v-pre 扩展是由我们的内置插件支持的。

配置参考： markdown.code.vPre.block


</div>

=== 导入代码块 ===

你可以使用下面的语法，从文件中导入代码块：

<pre class="md">&lt;!-- 最简单的语法 --&gt;
@[code](../foo.js)</pre>
如果你只想导入这个文件的一部分：

<pre class="md">&lt;!-- 仅导入第 1 行至第 10 行 --&gt;
@[code{1-10}](../foo.js)</pre>
代码语言会根据文件扩展名进行推断，但我们建议你显式指定：

<pre class="md">&lt;!-- 指定代码语言 --&gt;
@[code js](../foo.js)</pre>
实际上，<code>[]</code> 内的第二部分会被作为代码块标记来处理，因此在上面代码块章节中提到的语法在这里都可以支持：

<pre class="md">&lt;!-- 行高亮 --&gt;
@[code js{2,4-5}](../foo.js)</pre>
下面是一个复杂的例子：

* 导入 <code>'../foo.js'</code> 文件的第 3 行至第 10 行
* 指定语言为 <code>'js'</code>
* 对导入代码的第 3 行进行高亮，即 <code>'../foo.js'</code> 文件的第 5 行
* 禁用行号

<pre class="md">@[code{3-10} js{3}:no-line-numbers](../foo.js)</pre>
需要注意的是，路径别名在导入代码语法中不会生效。你可以通过下面的配置来自行处理路径别名：

<pre lang="ts">import { getDirname, path } from '@vuepress/utils'

const __dirname = getDirname(import.meta.url)

export default {
  markdown: {
    importCode: {
      handleImportPath: (str) =>
        str.replace(/^@src/, path.resolve(__dirname, 'path/to/src')),
    },
  },
}</pre>
<pre class="md">&lt;!-- 会被解析至 'path/to/src/foo.js' --&gt;
@[code](@src/foo.js)</pre>
<div class="tip">

导入代码扩展是由我们的内置插件支持的。

配置参考： markdown.importCode


</div>
<span id="在-markdown-中使用-vue"></span>
== 在 Markdown 中使用 Vue ==

这一章节会介绍 Vue 在 Markdown 中一些基本用法。

=== 模板语法 ===

我们知道：

* Markdown 中允许使用 HTML。
* Vue 模板语法是和 HTML 兼容的。

这意味着， Markdown 中允许直接使用 [https://v3.vuejs.org/guide/template-syntax.html Vue 模板语法]。


<span v-for="i in 3"> span: {{ i }} </span>

=== 组件 ===

你可以在 Markdown 中直接使用 Vue 组件。


== 注意事项 ==

<span id="非标准的-html-标签"></span>
=== 非标准的 HTML 标签 ===

非标准的 HTML 标签不会被 Vue 模板编译器识别成原生 HTML 标签。相反，Vue 会尝试将这些标签解析为 Vue 组件，而显然这些组件通常是不存在的。 例如：

* 已废弃的 HTML 标签，比如 [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/center &lt;center&gt;] 和 [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/font &lt;font&gt;] 等。
* [https://developer.mozilla.org/zh-CN/docs/Web/MathML MathML 标签]，它们可能会被一些 markdown-it 的 LaTeX 插件用到。

如果你无论如何都要使用这些标签的话，可以尝试下面两种方法之一：

* 添加一个 [https://v3.cn.vuejs.org/api/directives.html#v-pre v-pre] 指令来跳过这个元素和它的子元素的编译过程。注意所有的模板语法也都会失效。
* 设置 [https://v3.vuejs.org/api/application-config.html#compileroptions compilerOptions.isCustomElement] 来告诉 Vue 模板编译器不要尝试作为组件来解析它们。
** 对于 <code>@bundler-webpack</code> ，设置 vue.compilerOptions
** 对于 <code>@bundler-vite</code> ，设置 vuePluginOptions.template.compilerOptions