Xavi的技术文档

切换主题

VitePress 进阶语法 ​

VitePress 使用 markdown-it 作为 md 语法解析器，md 基础语法可以参考基本撰写和格式语法，此外 vitepress 还提供了更多个性化语法

锚点 ​

md 文档中的标题会自动生成锚点链接，可以通过页面路径#锚点名称的形式跳转到文章的具体位置，还可以通过如下格式自定义锚点名称

md
# 标题 {#自定义锚点名称}

定义后便可以通过最新的锚点名称定位页面位置（此时原名称不可用），本节的标题就修改了锚点名称，可以点击标题查看效果

资源链接 ​

页面链接 ​

页面之间的链接可以使用相对路径或绝对路径，如果使用绝对路径是相对于文档主目录决定的

md
[Home](/) <!-- 跳转到根目录下 index.md -->
[foo](/foo/) <!-- 跳转到 /foo/index.md -->
[heading](./#heading) <!-- 跳转到当前页面的heading锚点 -->

<!-- 可以写扩展名，也可以省略扩展名 -->

[bar - three](../bar/three)
[bar - three](../bar/three.md)
[bar - three](../bar/three.html)

静态资源链接 ​

所有的 md 文件都会被编译成 Vue 文件，所以任何绝对路径或相对路径的静态资源引用都会交由 Vite 处理。小于 4kb 的图片会转为 Base64 内嵌在页面中，未被引用的资源也不会被复制到输出目录中

如果文档部署在非根 URL 上，需要在 config 中设置 base 路径，此时的绝对路径静态资源引用不需要额外增加基础路径，因为 vite 会识别并处理。但如果链接存放在一个动态变量中时，则不会被 vite 识别，这与 Vue 项目中的静态资源处理方式一致

此时建议使用 vitepress 提供的 withBase api 包装路径

vue
<script setup>
import { withBase, useData } from "vitepress";

const { theme } = useData();
</script>

<template>
  <img :src="withBase(theme.logoPath)" />
</template>

TIP

md语法插入的图片会保持比例拉伸填满宽度，如果需要自定义图片大小可以使用HTML标签

<img src="" alt="" width="" style="margin: 0 auto" />

公共目录 ​

如果有不希望 Vite 处理的静态资源，可以放在工作目录/public文件夹下， public 文件夹是 Vue 3 的静态资源文件夹，打包时会将内部的文件原封不动的放在打包后的根路径中（所以需要注意 public 内文件夹不要与文档文件夹重名），引用 public 下的文件时应始终使用 / 开头的绝对路径

有一个例外是：如果从 md 页面链接 public 下的 HTML 页面，路由器将默认产生 404，这时可以通过 pathname:// 协议正确链接页面，格式为<pathname:///xxx.html>

pathname 协议仅支持在 md 文件中链接，并且默认在新标签页打开，也可以使用如下的方式直接在本页面打开

md
<!-- 此时不再需要pathname协议 -->

[link](/xxx.html){target="\_self"}

Frontmatter ​

用于配置单个页面，会覆盖 config 中定义的全局级别配置；支持yaml、json等格式，必须定义在页面顶部

定义的字段还可以作为页面变量，通过{{$frontmatter}}形式引用，本页标题就是引用的变量

md
---
title: VitePress扩展md语法
---

# {{ $frontmatter.title }}
md
---
{ "title": "VitePress扩展md语法" }
---

# {{ $frontmatter.title }}

自定义容器 ​

支持的类型包括info、tip、warning、danger、details，标题可选，默认显示类型名称，语法为：

md
::: 类型 容器标题
内容，换行需要留空行
:::

INFO

消息框

TIP

提示框

WARNING

警告信息

DANGER

危险警告

Details

下拉展开信息

还提供了特殊容器 raw 与 v-pre：

  • raw 内部的元素不会与 vitepress 样式和路由产生冲突，也可以直接在 HTML 元素上添加 vp-raw class 类
  • v-pre 内部的文本不会识别处理 Vue 插值语法，例如想添加 {{$frontmatter}} 文本而不是引用$frontmatter变量时便可以使用 v-pre，也可以直接在 HTML 元素上添加 v-pre 指令
md
::: raw

<div class="vp-raw"></div>
:::

::: v-pre
<span v-pre>{{$frontmatter}}</span>
:::

TIP

想展示会被 vitepress 转换的字符时，都可以使用类似的替换思想，例如{{$frontmatter}}可以通过：

html
<code><span v-pre>{{$frontmatter}}</span></code>

代码功能 ​

vitepress 使用 Shiki 实现 MD 代码块高亮显示，支持的语言可以查看这份列表

行高亮显示 ​

通过在语言名后跟行号范围，可以突出显示指定的行

指定格式可以是单行{4}，范围{5-8}或组合{4,7-13,16}，也可以直接使用// [!code hl]注释实现单行高亮显示

md
```js{3}
let a = 1 // [!code  hl]
let b = 2
console.log(a, b)
```
js
let a = 1
let b = 2
console.log(a, b)

TIP

如果想在代码块中输入```，需要将外层的代码块语法修改为四个点````

行聚焦显示 ​

使用[!code focus]注释可以聚焦单行，其余部分模糊显示（hover 时恢复）

md
```js
let a = 1; // [!code  focus]
let b = 2;
console.log(a, b); // [!code  focus]
```
js
let a = 1; 
let b = 2;
console.log(a, b);

Diff 效果 ​

添加注释[!code --]或[!code ++]可以显示增删行效果

md
```js
let a = 1; // [!code  --]
let a = 2; // [!code  ++]
console.log(a);
```
js
let a = 1; 
let a = 2; 
console.log(a);

错误或警告效果 ​

添加注释[!code warning]或[!code error]可以对应增加黄色和红色的底色

md
```js
let a = 1; // [!code  warning]
let a = 2; // [!code  error]
console.log(a);
```
js
let a = 1; 
let a = 2; 
console.log(a);

显示行号 ​

在.vitepress/config中可以设置代码块是否默认显示行号：

ts
export default defineConfig({
  markdown: {
    lineNumbers: true,
  },
});

也可以在代码块语言名后添加 :line-numbers 与 :no-line-numbers设置行号开关

md
```js:line-numbers
let a = 1
```

```js:no-line-numbers
let a = 1
```
js
let a = 1
js
let a = 1

导入代码 ​

可以通过<<< @/filepath导入其他文件中的代码，支持相对路径定位或@定位，@ 相对于文档主目录（默认根目录，可以通过 srcDir 配置项修改）；被引入的代码同样支持上述的高亮、聚焦等规则

md
<!-- 指定第四行高亮，判断语言为js，显示行号 -->

<<< @/snippets/importDemo.js{1-3 ts:no-line-numbers}
ts
function foo(a, b) {
  return a + b
}

console.log(foo(1, 2)) 
console.log(foo(3, 4))

代码组 ​

通过::: code-group ::: 包裹多段代码可以展示代码组

代码组内同样支持导入文件，同时还增加了显示文件名的功能

md
::: code-group

```js [a.js]
console.log("a.js");
```

<<< @/snippets/importDemo.js{1-3 ts:no-line-numbers} [导入的片段]
:::
js
console.log("a.js");
ts
function foo(a, b) {
  return a + b
}

console.log(foo(1, 2)) 
console.log(foo(3, 4))

导入 Markdown ​

可以导入其他 md 文件（不存在不会报错），还可以在文件名后指定显示的行号 <!--@ include: @/snippets/importDemo.md{3,}--> ，表示显示第三行以及之后的内容，所选范围格式还可以是 {,10}、{2,8}

😀

😃

😂

使用 Vue ​

VitePress 的 md 文件通过 markdown-it 解析后，被渲染为 Vue 页面，所以可以直接在 md 文件中使用任何 Vue 功能（需要遵守 SSR 渲染相关规则），包括插值语法、HTML 标签、Vue 指令、script setup、css预处理器（需安装）等

md 文件的主体内容就相当于 <template> 标签，此外需要用到局部范围的样式时，应该使用<style module>代替<style scoped>

默认情况下```代码块都会被 v-pre 包裹，不会识别内部的插值语法，如果需要识别，则可以在语言名后添加-vue后缀

md
```js-vue
Hello {{ 1 + 1 }}
```
js
Hello 2

使用组件 ​

只需要添加<script setup>标签，并在标签中正常引入组件，即可在 md 中使用。如果一个组件要在大多数页面上使用，可以全局注册组件，例如 vitepress 默认主题中全局注册了 Badge 组件（源码位置：vitepress\dist\client\theme-default\without-fonts.js）

template
<Badge text="info" type="info" />
<Badge text="tip" type="tip" />
<Badge text="warning" type="warning" />
<Badge text="danger" type="danger" />
infotipwarningdanger

也可以自定义主题，并在.VitePress/theme/index.js中使用enhanceApp配置公共组件，更详细的介绍查看配置解析-主题配置

js
import DefaultTheme from "VitePress/theme";
import XXX from "xxx";

export default {
  ...DefaultTheme,
  enhanceApp(ctx) {
    DefaultTheme.enhanceApp(ctx);
    ctx.app.component("XXX", XXX);
  },
};

VitePress 全局注册了<ClientOnly />组件可以用于包裹非SSR友好的组件，被包裹的组件在渲染到客户端后才会开始执行，避免SSR过程中报错

如果需要使用 <Teleport>，默认只支持传送到 body，如需传送其他目标，可以包裹在 <ClientOnly> 组件中

template
<ClientOnly>
  <Teleport to="#modal">
    <div>
      // ...
    </div>
  </Teleport>
</ClientOnly>

其他 ​

可以通过 :code: 的形式使用 Emoji 表情 🎉 💯，这里列出了完整的表情编码

可以通过 [[toc]] 生成页面目录，形式为：