vite+vue3项目渲染markdown爬坑回顾

前言

  近期接到一个页面重构的需求，很简单就是把原先文档说明的页面搬到新项目中。本身是一个CV工程，结果搞了一整天。
  老项目应该是一个python服务渲染html片段，新项目是vite+vue3的，因为想到后期如果在HTML上改文档实在是太麻烦了，容易出错不说，还不一定出效果。于是想到了用JSON维护，但是JSON渲染一些层级深的嵌套列表有些麻烦。最后还是决定搞一搞类似vuePress的功能：完全靠编辑MD文件渲染文档到html页面中。中间经曲折请听我娓娓道来：

步骤

HTML转MD文件

这个工作其实还算比较顺利，在线转就好了。

1. 复制现有的文档html片段
2. 访问http://www.jsons.cn/htmlmarkd... 把html片段粘贴进去，点击转md按钮

3. 生成结果

   这边遇到一个坑就是，有些在线转的工具不是很完善，可能转换以后遗留html标签名，或者丢文字，所以建议大家转换完成以后甚一下MD内容。

读取md并转换为html片段

1. 下载安装插件：vite-plugin-markdown
   npm i vite-plugin-markdown -S

2. 在vite.config.ts中配置插件

   import { defineConfig } from 'vite';
   import vue from '@vitejs/plugin-vue';
   const mdPlugin = require('vite-plugin-markdown') // 需要通过commenJs方式引用
   
   export default defineConfig({
    plugins: [
        vue(),
        mdPlugin.plugin({
          mode: ['html'],
        })
    ]
   })

3. 在需要渲染md内容的vue组件内引入md

4. 渲染到dom中

5. 添加样式，个根据实际情况自己调整，当然网上也有成套的css主题配色方案

   h2 {
     font-size: 18px;
     margin: 1em 0 15px;
     padding-top: 0.8em;
     padding-bottom: 0.8em;
   }
   h3 {
     font-size: 14px;
     margin: 22px 0 16px;
   }
   h4 {
     font-size: 13px;
     margin: 20px 0 16px;
   }
   h5 {
     font-size: 12px;
     margin: 16px 0 16px;
     font-weight: 700;
   }
   p {
     font-size: 12px;
     line-height: 24px;
     color: #666666;
     margin-top: 0px;
     margin: 8px 0;
     margin: 14px 0 14px;
   }
   pre {
     background-color: #eee;
     margin-bottom: 8px;
     margin-top: 8px;
     margin: 12px 0 12px;
   }
   blockquote {
     margin-bottom: 8px;
     margin-top: 8px;
     margin: 14px 0 14px;
     background-color: #eee;
     padding: 16px 16px;
   }
   tr {
     background-color: #f5f5f5;
   }
   code {
     background-color: #eee;
   }
   ul,
   ol,
   li {
     list-style: unset;
     font-size: 12px;
     line-height: 20px;
     color: #666666;
     margin-top: 0px;
     margin: 8px 0;
   }
   blockquote {
     border-color: #48b6e2;
   }
   table {
     display: table;
     width: 100%;
     max-width: 100%;
     margin-bottom: 20px;
   }

已经完成了？

当我得意洋洋的欣赏成果的时候，发现事情没有这么简单。渲染出来的页面没有解析code块内的语法样式，导致文档中的代码示例除了换行什么都没有。
一番科普，找到一个神奇的插件：vue-hljs

1. 在vue组件内，依照文档安装vue-hljs插件并使用

   import { ref } from 'vue';
   import { html } from '@/assets/help.md';
   import hljs from "highlight.js"; // 添加转换高亮标签插件
   import "vue-hljs/dist/style.css"; // 添加hljs默认样式
    
   const markdownhtml = ref(hljs.highlight(html).value);
   

2. 当看到页面后，会发现所有html片段都被渲染成了高亮的code文本。我希望只有code块内的结构变为高亮，这显然不是我想要的，于是乎

3. 条件渲染html块内的范围

   import { ref } from 'vue';
   import { html } from '@/assets/help.md';
   import hljs from "highlight.js"; // 添加转换高亮标签插件
   import "vue-hljs/dist/style.css"; // 添加hljs默认样式
   
   // 在vue3内，通过自定义指令来锁定高亮渲染标签的范围
   const vHighlight = {
     mounted(el: any) {
    const blocks = el.querySelectorAll('pre code'); // 匹配pre标签，code标签
    blocks.forEach((block: any) => {
      hljs.highlightBlock(block);
    });
     }
   };
    
   const markdownhtml = ref(html); // 先直接渲染整个html片段

4. 最后找一款喜欢的代码块主题风格，例如（dark style）：

   /*************highlightjs css*******************/
   /*
    * Visual Studio 2015 dark style
    * Author: Nicolas LLOBERA 
    */
   
   .hljs {
     display: block;
     overflow-x: auto;
     padding: 0.5em;
     background: #1e1e1e;
     color: #dcdcdc;
   }
   
   .hljs-keyword,
   .hljs-literal,
   .hljs-symbol,
   .hljs-name {
     color: #569cd6;
   }
   .hljs-link {
     color: #569cd6;
     text-decoration: underline;
   }
   
   .hljs-built_in,
   .hljs-type {
     color: #4ec9b0;
   }
   
   .hljs-number,
   .hljs-class {
     color: #b8d7a3;
   }
   
   .hljs-string,
   .hljs-meta-string {
     color: #d69d85;
   }
   
   .hljs-regexp,
   .hljs-template-tag {
     color: #9a5334;
   }
   
   .hljs-subst,
   .hljs-function,
   .hljs-title,
   .hljs-params,
   .hljs-formula {
     color: #dcdcdc;
   }
   
   .hljs-comment,
   .hljs-quote {
     color: #57a64a;
     font-style: italic;
   }
   
   .hljs-doctag {
     color: #608b4e;
   }
   
   .hljs-meta,
   .hljs-meta-keyword,
   .hljs-tag {
     color: #9b9b9b;
   }
   
   .hljs-variable,
   .hljs-template-variable {
     color: #bd63c5;
   }
   
   .hljs-attr,
   .hljs-attribute,
   .hljs-builtin-name {
     color: #9cdcfe;
   }
   
   .hljs-section {
     color: gold;
   }
   
   .hljs-emphasis {
     font-style: italic;
   }
   
   .hljs-strong {
     font-weight: bold;
   }
   
   /*.hljs-code {
     font-family:'Monospace';
   }*/
   
   .hljs-bullet,
   .hljs-selector-tag,
   .hljs-selector-id,
   .hljs-selector-class,
   .hljs-selector-attr,
   .hljs-selector-pseudo {
     color: #d7ba7d;
   }
   
   .hljs-addition {
     background-color: #144212;
     display: inline-block;
     width: 100%;
   }
   
   .hljs-deletion {
     background-color: #600;
     display: inline-block;
     width: 100%;
   }

结语

小小的一个页面迁移，扯出来了这么多的知识点。只要抽丝剥茧，一点点解决所有问题才能达到目标。最后感谢在解决问题的路上给我提供帮助和思路的同学。