Vue中markdown-it基础使用教程

Vue项目里怎么优雅地显示Markdown文本？其实最常用、最稳定的方案就是 markdown-it ------ 一个轻量、灵活，而且生态超全的Markdown渲染库。

今天就用最直白的方式，带大家从零上手 markdown-it，不用复杂配置，不用多余操作，3步就能在Vue里实现Markdown渲染，新手也能轻松拿捏！

一、先搞懂：markdown-it 到底是什么？

简单说，markdown-it 就是一个「转换工具」------ 它能把我们写的Markdown语法文本（比如 # 标题、加粗），转换成浏览器能识别的HTML标签，最终在页面上展示出美观的格式。

举个最直观的例子：

你写的Markdown文本：

md 复制代码

# 我的第一篇博客
这是**加粗**的文本，这是*斜体*的文本
[点击跳转到百度](https://baidu.com)

经过markdown-it转换后，会变成这样的HTML：

html 复制代码

<h1>我的第一篇博客</h1>
<p>这是<strong>加粗</strong>的文本，这是<em>斜体</em>的文本</p>
<p><a href="https://baidu.com">点击跳转到百度</a></p>

我们只需要把转换后的HTML在Vue中渲染出来，就能看到熟悉的Markdown样式啦～

二、第一步：安装 markdown-it

不管是Vue2还是Vue3，安装方式都一样，打开终端，在项目根目录执行以下命令即可：

bash 复制代码

npm install markdown-it

如果用yarn，就执行：

bash 复制代码

yarn add markdown-it

安装完成后，就可以在组件中引入使用了，非常简单。

三、第二步：最基础的使用（3行代码搞定渲染）

安装完成后，我们先做一个最极简的渲染演示，搞懂核心逻辑------「导入 → 实例化 → 渲染」。

1. 核心代码（Vue3示例）

vue 复制代码

<template>
  <!-- 用v-html渲染转换后的HTML -->
  <div v-html="renderedHtml"></div>
</template>

<script setup>
// 1. 导入markdown-it
import MarkdownIt from 'markdown-it'

// 2. 创建渲染器实例
const md = new MarkdownIt()

// 3. 定义要渲染的Markdown文本
const mdText = `# 标题1
## 标题2
这是**加粗**文本，这是*斜体*文本
- 无序列表1
- 无序列表2`

// 4. 转换Markdown为HTML
const renderedHtml = md.render(mdText)
</script>

2. 核心逻辑说明

import MarkdownIt from 'markdown-it'：导入markdown-it库，相当于把这个工具拿到手。
new MarkdownIt()：创建一个渲染器实例，后续所有的转换操作都靠这个实例。
md.render(mdText)：调用渲染方法，把Markdown文本（mdText）转换成HTML字符串。
v-html="renderedHtml"：Vue中用v-html指令，把转换后的HTML渲染到页面上。

运行项目，就能看到Markdown文本被成功渲染啦！这就是最基础、最核心的用法，没有多余的复杂配置。

四、第三步：常用配置项（必掌握，提升体验）

上面的基础用法虽然能用，但有时候会遇到一些小问题：比如换行不生效、网址不能自动变成链接、不能内嵌HTML标签。这时候就需要给markdown-it添加配置项，优化渲染效果。

修改实例化的代码，添加配置：

js 复制代码

const md = new MarkdownIt({
  html: true,        // 允许渲染Markdown中的HTML标签（如<div>、<span>）
  breaks: true,      // 自动把Markdown中的换行（\n）转换成<br>标签，换行生效
  linkify: true,     // 自动识别文本中的网址，转换成可点击的链接
  typographer: true  // 优化标点符号（比如把...变成省略号，把--变成破折号）
})

这4个配置项是最常用的，尤其是前3个，建议直接加上，能大幅提升渲染体验：

breaks: true：解决"Markdown中换行，渲染后不换行"的问题。
linkify: true：比如你写了 https://baidu.com，会自动变成可点击的链接，不用手动写 [百度](https://baidu.com)。
html: true：如果你的Markdown文本中包含HTML标签（比如自定义样式的<span class="red">红色文本</span>），会正常渲染。

五、Vue中完整封装（可直接复制使用）

实际开发中，我们不会每次渲染都写一遍重复代码，最好的方式是封装成一个通用的Markdown渲染组件，后续在任何页面都能直接引用。

下面是Vue3的完整封装组件（新手直接复制到项目中即可使用）：

vue 复制代码

<!-- components/MarkdownRenderer.vue -->
<template>
  <div class="markdown-container" v-html="renderedHtml"></div>
</template>

<script setup>
import { computed } from 'vue'
import MarkdownIt from 'markdown-it'

// 接收父组件传递的Markdown文本
const props = defineProps({
  content: {
    type: String,
    default: '' // 默认值为空，避免报错
  }
})

// 初始化markdown-it，添加常用配置
const md = new MarkdownIt({
  html: true,
  breaks: true,
  linkify: true,
  typographer: true
})

// 计算属性：自动监听content变化，重新渲染
const renderedHtml = computed(() => {
  return md.render(props.content)
})
</script>

<style scoped>
/* 基础样式，让渲染效果更美观（可自定义） */
.markdown-container {
  line-height: 1.8;
  font-size: 16px;
  padding: 20px;
}

/* 标题样式优化 */
.markdown-container h1 {
  font-size: 24px;
  margin: 20px 0;
  padding-bottom: 10px;
  border-bottom: 1px solid #eee;
}
.markdown-container h2 {
  font-size: 20px;
  margin: 18px 0;
}

/* 列表样式优化 */
.markdown-container ul,
.markdown-container ol {
  padding-left: 24px;
  margin: 10px 0;
}

/* 代码块样式优化 */
.markdown-container pre {
  background: #f5f5f5;
  padding: 15px;
  border-radius: 8px;
  overflow-x: auto;
  margin: 15px 0;
}
.markdown-container code {
  font-family: 'Consolas', monospace;
  font-size: 14px;
}
</style>

组件使用方法

在需要渲染Markdown的页面，引入这个组件，传递content属性即可：

vue 复制代码

<template>
  <div class="blog-page">
    <h1>我的博客文章</h1>
    <MarkdownRenderer :content="blogContent" />
  </div>
</template>

<script setup>
import MarkdownRenderer from '@/components/MarkdownRenderer.vue'

// 模拟博客内容（实际开发中可能从接口获取）
const blogContent = `# Vue中markdown-it使用教程
大家好，今天给大家分享markdown-it的基础使用方法。

## 什么是markdown-it？
它是一个轻量的Markdown渲染库，能把Markdown文本转换成HTML。

## 常用功能
- 支持标题、加粗、斜体
- 支持列表、链接、图片
- 支持自动识别链接
- 支持内嵌HTML

\`\`\`js
// 核心代码示例
import MarkdownIt from 'markdown-it'
const md = new MarkdownIt()
const html = md.render('# 标题')
\`\`\`

希望这篇教程能帮到大家！
`
</script>

六、新手必看：3个关键注意点

1. markdown-it 不自带样式！

很多新手会疑惑：为什么我渲染后，格式很简陋？因为 markdown-it 只负责「转换HTML结构」，不提供任何样式。上面封装组件中添加的CSS，只是基础样式，你可以根据自己的项目风格自定义，或者使用现成的主题（比如 github-markdown-css）。

2. 代码高亮需要额外配置

上面的示例中，代码块只是简单的灰色背景，没有语法高亮。如果需要代码高亮，需要额外引入 highlight.js 或 shiki 插件，后续我会专门写一篇教程讲这个。

3. 安全问题：防XSS攻击

如果你的Markdown文本是用户输入的（比如评论、博客投稿），直接用v-html渲染会有XSS风险。建议引入 dompurify 库，对转换后的HTML进行净化，后续教程也会详细讲解。

七、总结（极简版，方便记忆）

安装：npm install markdown-it
实例化：new MarkdownIt(配置项)
渲染：md.render(Markdown文本)
展示：用 v-html 渲染转换后的HTML
优化：封装成通用组件，添加基础样式

到这里，markdown-it的基础使用就讲完了，新手按照上面的步骤，就能轻松在Vue项目中实现Markdown渲染。如果想进一步学习代码高亮、添加GitHub样式、支持Mermaid图表等进阶功能，可以在评论区告诉我～