vitePress 插件

markdown扩展

Markdown 扩展 / VitePress

• 代码片段支持的语言类型

图片放大预览

安装依赖

npm i markdown-it-custom-attrs

插件配置

在vitePress的config.js中引入插件并且进行配置

import mdItCustomAttrs from 'markdown-it-custom-attrs';

export default {
  markdown: {
    config: (md) => {
      md.use(mdItCustomAttrs, 'image', {
        'data-fancybox': 'gallery'
      });
    }
  }
};

引入灯箱css和js资源

要么用 CDN 引入，要么在项目中安装

export default {
  head: [
    // ["link", {rel: "stylesheet", href: "https://cdn.jsdelivr.net/npm/@fancyapps/ui/dist/fancybox.css"}],
    // ["script", {src: "https://cdn.jsdelivr.net/npm/@fancyapps/ui@4.0/dist/fancybox.umd.js"}],
    ["link", {rel: "stylesheet", href: "./static-plugin/fancybox.css"}],
    ["script", {src: "./static-plugin/fancybox.umd.js"}],
  ],
}

直接使用

<image src="./image/add_glb_model.png" data-fancybox="gallery"/>

数学公式的使用

安装插件

npm install katex @iktakahiro/markdown-it-katex

使用插件及配置

import markdownItKatex from '@iktakahiro/markdown-it-katex';

export default {
  markdown: {
    config: (md) => {
      md.use(markdownItKatex);
    }
  },
  head: [
    // 引入 KaTeX 样式
    ['link', {
      rel: 'stylesheet',
      href: 'https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css',
      crossorigin: 'anonymous'
    }]
  ]
};

使用数学公式

行内公式： $F_x =\frac{z}{y} + 2x^y$

块级公式：
$$
F_x = \frac{\partial}{\partial x}(e^{-xy}) = e^{-xy} \cdot (-y) = -y e^{-xy}
$$

行内公式： $F_x =\frac{z}{y} + 2x^y$

块级公式：

$$F_x = \frac{\partial}{\partial x}(e^{-xy}) = e^{-xy} \cdot (-y) = -y e^{-xy}$$

数学符号

描述	KaTeX 代码	渲染效果（示例）
分数	\frac{z}{y}	$\frac{z}{y}$
指数	e^{-xy}	$e^{-xy}$
下标	a_b	$a_b$
加减	a + b - c	$a + b - c$
正负号	a \pm b \mp c	$a \pm b \mp c$
乘	a \times b	$a \times b$
点乘	a \cdot b	$a \cdot b$
开方	\sqrt{x}、\sqrt[n]{x}	$\sqrt{x}$ 、$\sqrt[n]{x}$
求和	\sum_{i=1}^{n}	$\sum_{i=1}^{n}$
极限	\lim_{x \to \infty}	$\lim_{x \to \infty}$
矢量	\vec{v}	$\vec{v}$
矩阵	\begin{matrix} a & b \\ c & d \end{matrix}	$\begin{matrix} a & b \\ c & d \end{matrix}$
括号	\left( \frac{a}{b} \right)	$\left( \frac{a}{b} \right)$
绝对值	|x|	$|x|$
积分	\int_{a}^{b}、\iint 、\iiint	$\int_{a}^{b}$、$\iint$ 、$\iiint$
环路积分	\oint、\oiint、\oiiint	$\oint$、$\oiint$、$\oiiint$
分段函数	f(x) = \begin{cases} x^2, & x < 0 \\ x , & x \geq 0\end{cases}	$f(x) = \begin{cases} x^2, & x < 0 \\ x , & x \geq 0\end{cases}$

希腊字母

字母	KaTeX 代码	渲染
α	\alpha	$\alpha$
β	\beta	$\beta$
γ	\gamma	$\gamma$
δ	\delta	$\delta$
δ	\Delta	$\Delta$
ε	\epsilon	$\epsilon$
ζ	\zeta	$\zeta$
η	\eta	$\eta$
θ	\theta	$\theta$
ι	\iota	$\iota$
κ	\kappa	$\kappa$
λ	\lambda	$\lambda$
μ	\mu	$\mu$
ν	\nu	$\nu$
ξ	\xi	$\xi$
ο	\omicron	$\omicron$
π	\pi	$\pi$
ρ	\rho	$\rho$
σ	\sigma	$\sigma$
τ	\tau	$\tau$
υ	\upsilon	$\upsilon$
φ	\phi	$\phi$
χ	\chi	$\chi$
ψ	\psi	$\psi$
ω	\omega	$\omega$
Ω	\Omega	$\Omega$

不等号

不等号	LaTeX 表达式	渲染效果
不等于	\neq 或 \ne	$a \neq b$
大于	>	$a > b$
小于	<	$a < b$
大于等于	\geq 或 \ge	$a \geq b$
小于等于	\leq 或 \le	$a \leq b$
远大于	\gg	$a \gg b$
远小于	\ll	$a \ll b$
不小于	\not\geq	$a \not\geq b$
不大于	\not\leq	$a \not\leq b$

逻辑符号

描述	表达式	渲染效果
等价于	A \leftrightarrow B、A \iff B、 A \Rightarrow B、A \Leftarrow B	$A \leftrightarrow B$、$A \iff B$、 $A \Rightarrow B$、$A \Leftarrow B$
蕴含	A \rightarrow B	$A \rightarrow B$
可推导出	B \vdash A	$B \vdash A$
语义蕴含	M \models A	$M \models A$
逻辑且	A \land B	$A \land B$
逻辑或	A \lor B	$A \lor B$
非	\neg A 或 \lnot A	$\neg A$、$\lnot A$

mermaid支持

安装

npm i mermaid

组件封装

封装了这个mermaid组件之后，在vitepress的index.js文件中进行全局注册

<template>
  <div ref="container" class="mermaid-diagram">
  </div>
</template>

<script lang="ts" setup>
  import {onMounted, ref, watch} from 'vue';
  import mermaid from 'mermaid';

  // 启用 mermaid
  mermaid.initialize({startOnLoad: false});

  const props = defineProps<{
    code: string
  }>();

  const container = ref<HTMLElement | null>(null);

  const renderDiagram = async () => {
    if (!container.value) return;

    try {
      // 清空容器内容
      container.value.innerHTML = '';

      // 使用 mermaid 将代码渲染为 SVG
      const {svg} = await mermaid.render('graphDiv', props.code);
      container.value.innerHTML = svg;
    } catch (error) {
      console.error('Mermaid 渲染失败:', error);
      container.value.innerText = '流程图渲染失败，请检查代码格式。';
    }
  };

  watch(() => props.code, renderDiagram);

  onMounted(() => {
    renderDiagram();
  });
</script>

<style scoped>
  .mermaid-diagram {
    width: 100%;
    overflow-x: auto;
  }

  .mermaid-diagram svg {
    max-width: 100%;
    height: auto;
  }
</style>

使用

<template>
  <MarkMermaid :code="mermaidCode"/>
</template>

<script setup>
  const mermaidCode = `graph LR
    A(求xy的一次偏导数) --> B(联立方程得解)
    B --> C(求二阶偏导数)
    C --> D(A=f_xx)
    C --> E(B=f_xy)
    C --> F(C=f_yy)
    D --> G(△=B^2-AC)
    E --> G
    F --> G
    G -- △>0 --> H(不是极值点)
    G -- △ = 0 --> I(无法确定)
    G -- △<0 --> J(存在极值点)
    J  -- A<0 --> K(极大值)
    J  -- A>0 --> L(极小值)`;
</script>

mermaid插件支持

找了一些插件用到项目当中都会报错，最后找到了这个插件vitepress-mermaid-renderer

安装与配置

先安装插件

npm install vitepress-mermaid-renderer

在theme/index.ts文件当中添加配置，之前的不变，这是这个插件要新增的

import {createMermaidRenderer} from 'vitepress-mermaid-renderer';
import 'vitepress-mermaid-renderer/dist/style.css';

export default {
  enhanceApp({app, router}) {
    const mermaidRenderer = createMermaidRenderer();
    mermaidRenderer.initialize();

    if (router) {
      router.onAfterRouteChange = () => {
        nextTick(() => mermaidRenderer.renderMermaidDiagrams());
      };
    }
  }
};

展示效果

mermaid

graph LR

A --> B

graph TB
    A --> B
    B --> C
    C --> A