在 Vue 2 与 Vue 3 中使用 markdown-it-vue 渲染 Markdown 和数学公式

markdown-it-vue 是一个功能强大的 Markdown 渲染 Vue 组件，它基于 markdown-it 解析引擎，集成了多种插件，开箱即用地支持GitHub风格的Markdown、代码高亮、图表（Mermaid, ECharts）、表情符号（emoji）以及数学公式（LaTeX, AsciiMath）等高级功能。

🎯 核心优势一览

markdown-it-vue 的强大之处在于其丰富的内置功能，能让开发者快速构建功能全面的文档系统。下表整理了它的主要特性：

功能分类	具体支持	适用场景
核心语法	CommonMark和GitHub Flavored Markdown (GFM) 规范，包括表格、任务列表等	基本文档编写，与GitHub风格保持一致的场景
内容增强	Emoji表情、上下标、脚注、缩写、定义列表等	提升文本的可读性和表现力
高级组件	Mermaid图表、ECharts、Flowchart.js流程图	需要嵌入数据可视化图表的场景，如报表、教程
学术支持	数学公式（LaTeX & AsciiMath）、代码高亮	学术论文、技术文档、在线教育平台的核心需求
开发体验	图片预览、TOC目录生成、自定义错误提示	增强用户体验的实用功能

现在，我们以 Vue 2 和 Vue 3 为例，介绍如何快速集成和使用。

🚀 Vue 2 集成：开箱即用

markdown-it-vue 原生支持 Vue 2，集成起来非常方便。

安装和引入

通过 npm 安装，并在入口文件或组件中全局注册。

bash 复制代码

npm install markdown-it-vue

javascript 复制代码

// main.js
import Vue from 'vue'
import MarkdownItVue from 'markdown-it-vue'
import 'markdown-it-vue/dist/markdown-it-vue.css'

Vue.use(MarkdownItVue)

基础使用

在任意 Vue 组件中，通过 <markdown-it-vue> 组件和 :content 属性传入 Markdown 文本即可。

html 复制代码

<template>
  <div>
    <markdown-it-vue class="markdown-body" :content="markdownContent" />
  </div>
</template>

<script>
export default {
  data() {
    return {
      markdownContent: `
# 爱因斯坦质能方程
这是行内公式: $E = mc^2$。

下面是块级公式：
$$\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}$$
      `
    }
  }
}
</script>

在这个示例中，组件会自动识别 $...$ 和 $$...$$ 包裹的 LaTeX 公式，并将其渲染为精美的数学表达式。

扩展你的工具

如果内置功能不满足需求，可以通过 use 方法手动添加 markdown-it 插件。

html 复制代码

<template>
  <markdown-it-vue ref="mdComponent" :content="markdownContent" />
</template>
<script>
export default {
  mounted() {
    // 假设要添加自定义插件 MyMarkdownItPlugin
    this.$refs.mdComponent.use(MyMarkdownItPlugin)
  }
}
</script>

⚡️ Vue 3 集成：两个便捷方案

由于 markdown-it-vue 主要为 Vue 2 设计，在 Vue 3 中直接使用可能会遇到兼容性问题。这里推荐两种更合适的方案。

方案一：推荐！使用 Vue 3 专属组件
@f3ve/vue-markdown-it 是一个为 Vue 3 全新设计的封装组件，语法和使用习惯与 markdown-it-vue 一脉相承。

bash 复制代码

npm install @f3ve/vue-markdown-it

html 复制代码

<template>
  <VueMarkdownIt :source="markdownContent" :options="options" />
</template>

<script setup>
import { ref } from 'vue'
import VueMarkdownIt from '@f3ve/vue-markdown-it'
import 'katex/dist/katex.min.css' // 引入KaTeX样式

const markdownContent = ref(`
# Vue 3 中的质能方程
行内公式: $E = mc^2$

块级公式:
$$\\int_{a}^{b} f(x) \\, dx$$
`)
// 配置 markdown-it 和 KaTeX
const options = {
  markdownIt: {
    html: true,
    linkify: true,
  },
  // 启动 markdown-it-katex 插件
  use: [
    'markdown-it-katex'
  ]
}
</script>

方案二：自己动手，使用 markdown-it

这提供了最大的灵活性，适合对渲染过程有精细化控制需求的场景。

bash 复制代码

npm install markdown-it @iktakahiro/markdown-it-katex katex

html 复制代码

<template>
  <div class="markdown-body" v-html="renderedMarkdown"></div>
</template>

<script setup>
import { computed, ref } from 'vue'
import MarkdownIt from 'markdown-it'
import markdownItKatex from '@iktakahiro/markdown-it-katex'
import 'katex/dist/katex.min.css'

const md = new MarkdownIt({ html: true, linkify: true })
md.use(markdownItKatex)

const content = ref(`
使用 $\\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}$ 来求根。
`)

const renderedMarkdown = computed(() => md.render(content.value))
</script>

⚙️ 高级配置：深度定制

通过 options 属性可以对 markdown-it 及其插件进行细致配置，以适应不同场景。

配置项	说明	示例
`markdownIt`	直接配置 `markdown-it` 内核，例如启用自动链接识别。	`{ linkify: true }`
`linkAttributes`	为所有生成的 `<a>` 标签统一添加属性，如在新窗口打开。	`{ target: '_blank', rel: 'noopener' }`
`katex`	配置 KaTeX 公式渲染引擎，如设置错误时的颜色。	`{ throwOnError: false, errorColor: '#cc0000' }`
`githubToc`	自定义生成的目录 (TOC) 结构，如起始标题级别。	`{ tocFirstLevel: 2, tocLastLevel: 3 }`
`image`	控制图片行为，如开启点击预览和默认对齐方式。	`{ viewer: true, hAlign: 'center' }`

💎 总结与资源

总的来说，在 Vue 项目中使用 markdown-it-vue 来展示 Markdown 和数学公式，是一个高效且优雅的选择。

Vue 2 项目 ：推荐直接使用 markdown-it-vue，开箱即用，配置简单。
Vue 3 项目 ：更推荐使用 @f3ve/vue-markdown-it 方案，它专为 Vue 3 设计，兼容性更好，集成体验更顺畅。