企业官网建设流程全解析

markdown-it-vue 实操指南：3分钟跑起来，4个高频坑一次说清

【免费下载链接】markdown-it-vueThe vue lib for markdown-it.项目地址: https://gitcode.com/gh_mirrors/ma/markdown-it-vue

markdown-it-vue 是一个面向 Vue 2 的 Markdown 组件，底层用 markdown-it 做解析引擎，GFM TOC、mermaid、Echarts、KaTeX 公式这些插件全部预先配好，你只管把内容传进去。这篇文章带你从装到跑通，再帮你避开几个上手后最容易卡住的地方。

3分钟把它跑起来

两条路，任选其一。

路线一：直接跑仓库自带的 Demo。

git clone https://gitcode.com/gh_mirrors/ma/markdown-it-vue cd markdown-it-vue yarn install && yarn dev

跑起来后浏览器打开 localhost:8080，你会看到左边编辑 Markdown、右边实时出效果的演示页。TOC 目录、流程图、数学公式、Echarts 饼图都渲染出来了，就说明成功了。

路线二：装进你自己的 Vue 2 项目当依赖用。

npm install markdown-it-vue

核心代码就这一段，content属性是字符串，把 Markdown 源文丢进去就行：

<template> <markdown-it-vue class="md-body" :content="content" /> </template> <script> import MarkdownItVue from 'markdown-it-vue' import 'markdown-it-vue/dist/markdown-it-vue.css' export default { components: { MarkdownItVue }, data() { return { content: '# hello markdown-it-vue' } } } </script>

上手后最容易卡住的几个地方

端口 8080 被占用，Demo 起不来

报错里带着 EADDRINUSE，八成是这个端口被别的进程占了。可以先lsof -i :8080找到凶手，或者直接换个端口，命令照搬 dev 脚本的写法：

npx vue-cli-service serve --port 8081 ./example/main.js

集成进项目，样式全乱了

文字能出来，但表格、标题、提示框全没了样式，看着像裸 HTML。九成是漏了引入样式表：

import 'markdown-it-vue/dist/markdown-it-vue.css'

这行不能省。GitHub 风格的排版和 info、warning、error 提示框的样式都在这份 CSS 里，少了它整个观感就没了。

传了 options，之前的默认行为悄悄失效

给组件加了几个配置之后，发现链接不再自动新窗口打开、公式报错也不标红了。原因是 options 里每个键（markdownIt、katex、linkAttributes）都是整体替换，不做属性级合并。你传了哪个键，那个键里没写的属性就丢了。所以改配置时把要保留的都补全：

options: { markdownIt: { linkify: true, html: true }, linkAttributes: { attrs: { target: '_blank', rel: 'noopener' } }, katex: { throwOnError: false, errorColor: '#cc0000' } }

只写"要改的"而不写"要留的"，是这块最常见的翻车姿势。

打包后体积一下涨了很多

库默认带上了 mermaid 和 Echarts，这俩都是大块头，产物里自然不小。如果你的文档不画 mermaid 图，直接换轻量版：

import MarkdownItVueLight from 'markdown-it-vue/dist/markdown-it-vue-light.umd.min.js' import 'markdown-it-vue/dist/markdown-it-vue-light.css'

light 版就是把 mermaid 摘掉了，组件名换成markdown-it-vue-light即可。另外提前说一句：这个库基于 Vue 2，Vue 3 的项目不能直接用。

几个值得知道的配置项

• options.markdownIt：markdown-it 本体配置，默认只开了linkify: true，想开 html 或改换行行为时改它
• linkAttributes：默认所有链接target: _blank+rel: noopener，想让链接在当前窗口打开就改这里
• katex.throwOnError：默认false，公式写错了显示红色占位而不是抛异常，想自己捕获报错时改
• githubToc：默认给 2~3 级标题生成锚点链接，文档标题层级不同就调tocFirstLevel/tocLastLevel
• image.viewer：默认true，点图片会弹出查看器放大，不需要就关掉
• mermaid.theme：默认default，可选forest、dark、neutral

写在后面

markdown-it-vue 的价值就一句话：十几个 markdown-it 插件不用你逐个装、逐个配，一行content传进去，TOC、图表、公式全给你渲好了。想再往下走，翻翻 README.md 里的 Options 和 Plugin list 两节，把内置插件的配置全貌过一遍就行。

【免费下载链接】markdown-it-vueThe vue lib for markdown-it.项目地址: https://gitcode.com/gh_mirrors/ma/markdown-it-vue