Vitepress的文档渲染基础教程

更新时间：2022年10月27日 15:57:27 作者：小鑫同学

这篇文章主要为大家介绍了Vitepress的文档渲染基础教程，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪

1.引言

Vitepress的文档渲染目的就是将程序员日常所写的Markdown文件编译为Html文件，并添加了更多的插件来丰富MD文件的功能，就比如说Vuejs组件在MD文件中渲染等等，为了我们可以在使用Vitepress的时候可以更随心所欲的定制一些功能，我们要先搞一搞明白Vitepress是如何将MD文档渲染成HTML的~

看完可以明白这3点？

MD文档转HTML文档流程；
如何支持代码块高亮；
如何实现自定义容器；

2. 实现MD文档转HTML文档

2.1 请按如下项目结构准备我们的实验环境~

├─markdown-it-demo
│  ├─src
│  │  ├─index.ts
│  │  ├─temp.md
│  ├─index.html
└─ └─package.json

2.2 利用markdown-it模块实现文档转换：

markdown-it 是目前比较通用的MD语法解析模块，快速且易于扩展，遵循COmmonMark规范，且有大量的社区插件~

执行安装模块命令：pnpm i markdown-it @types/markdown-it -D；
导入markdown-it模块并实例化md对象；

import markdownIt from "markdown-it";
// 实例化md-it对象
const md = new markdownIt();

通过fs-extra模块读取放置在src下的temp.md文件，读取后的Buffer数组通过toString()转为字符串；

const rawMd = fs.readFileSync(path.resolve(__dirname, "temp.md")).toString();

利用md对象的render函数来讲rawMd进行转换；

const output = md.render(rawMd);

转换完成后将output内容输出到index.html文件中；

fs.writeFileSync(path.resolve(__dirname, "../index.html"), `
${output}
`);

在转换完成后可以利用child_process.exec(root-path)自动在浏览器打开index.html文档；

3. 实现MD支持代码块高亮

代码块高亮所使用的模块时highlight.js，该模块同时内置了很多常见的代码块样式文件可供选择~

3.1 第一步改造markdownIt对象的构造函数：

highlight属性配置的函数传入code片段和代码方言两部分，通过在hljs库中查找对应的方言来利用hljs库实现代码的快速高亮，当无法查找到对应的方言时将返回仅仅转义后的html片段~

const md = new markdownIt({
    highlight: (str: string, lang: string) => {
        const defaultCode: string = `<pre class="hljs"><code>${md.utils.escapeHtml(str)}</code></pre>`;
        if (lang && hljs.getLanguage(lang)) {
            try {
                return `<pre class="hljs"><code>${hljs.highlight(str, { language: lang, ignoreIllegals: true }).value}</code></pre>`
            } catch (__) {
                return defaultCode;
            }
        }
        return defaultCode;
    }
});

3.2 第二部整合output内容和高亮样式文本：

第一步的操作仅仅完成了由code片段到html结构的转换，但是完成高亮还需要样式配合渲染，我们这里可以通过在输出output内容到index.html时将hljs中喜欢的样式文档路径传入到html文件来加载~

const output = md.render(rawMd);
const styles = `
<link rel="stylesheet" href="./node_modules/highlight.js/styles/a11y-dark.css" rel="external nofollow"  rel="external nofollow" >
`;
// 输出html文本
fs.writeFileSync(path.resolve(__dirname, "../index.html"), `
${styles}
${output}
`);

更多的样式文档可以在./node_modules/highlight.js/styles选择~

4. 实现MD支持自定义容器

自定义容器是MD文档默认并不支持的一种语法，在Vuejs的文档有很多的应用，实现自定义容易需要用到markdown-it-container模块~

markdownIt通过插件的形式利用markdown-it-container来实现自定义容器，通过配置validate来做渲染前的语法校验，通过render函数来组中容器部分的HTML结构~

::: warning
*here be dragons*
:::
↓↓↓↓↓↓↓↓↓↓转换为↓↓↓↓↓↓↓↓↓↓
<div class="warning">
<em>here be dragons</em>
</div>

md.use(require("markdown-it-container"), "warning", {
    validate: (params: string) => {
        return params.trim().match(/^warning+(.*)$/m);
    },
    render: (tokens: Array<Token>, idx: number) => {
        const m = tokens[idx].info.trim().match(/^warning+(.*)$/m);
        if (tokens[idx].nesting === 1) {
            return `<div class="warning">${md.utils.escapeHtml(m ? m[1] : '')}`
        } else {
            return '</div>\n';
        }
    }
})

提示：通过tokens[idx]取到的数据如下图所示~

上面的处理依旧是MD到HTML结构的转换，在自定义容器的时候我们预留的css名称，我们还是需要在输出index.html文件的时候自定义样式文档~

const output = md.render(rawMd);
const styles = `
<link rel="stylesheet" href="./node_modules/highlight.js/styles/a11y-dark.css" rel="external nofollow"  rel="external nofollow" >
<style>
    .warning{
        margin: 28px 0;
        padding: 10px 14px 4px 22px;
        border-radius: 8px;
        overflow-x: auto;
        transition: color .5s,background-color .5s;
        position: relative;
        font-size: 14px;
        line-height: 1.6;
        font-weight: 500;
        color: #0000008c;
        background-color: #f9f9f9;
        border: 1px solid #ffc517;
    }
    .hljs {
        padding: 5px 8px;
        border-radius: 5px;
    }
</style>
`;
// 输出html文本
fs.writeFileSync(path.resolve(__dirname, "../index.html"), `
${styles}
${output}
`);

5. 总结

通过使用markdown-it、highlight.js、markdown-it-container模块实现了Markdown到HTML的文档转换，代码块高亮和自定义容器，VItepress搭建的组件库文档中的组件渲染和源码展示功能就需要用到自定义容器的解析和组装自定义的Vue组件实现高级功能~

本文项目已推送至GitHub，欢迎克隆演示：git clone

https://github.com/OSpoon/awesome-examples.git

以上就是Vitepress的文档渲染基础教程的详细内容，更多关于Vitepress 文档渲染基础的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

vue3 座位选座矩阵布局的实现方法(可点击选中拖拽调换位置)
由于公司项目需求需要做一个线上设置考场相关的座位布局用于给学生考机排号考试,实现教室考场座位布局的矩阵布局,可点击选中标记是否有座无座拖拽调换位置横向纵向排列,本文给大家分享实现代码,一起看看吧
2023-11-11
js 实现拖拽排序详情
这篇文章主要介绍了js 实现拖拽排序，拖拽排序对于小伙伴们来说应该不陌生，平时工作的时候，可能会选择使用类似Sortable.js这样的开源库来实现需求。但在完成需求后，大家有没有没想过拖拽排序是如何实现的呢？感兴趣得话一起来看看下面文章得小心内容吧
2021-11-11
Vue中$router.push()路由切换及如何传参和获取参数
这篇文章主要给大家介绍了关于Vue中$router.push()路由切换及如何传参和获取参数的相关资料,文中通过实例代码介绍的非常详细,对大家学习或者使用vue具有一定的参考学习价值,需要的朋友可以参考下
2023-03-03
vue的$http的get请求要加上params操作
这篇文章主要介绍了vue的$http的get请求要加上params操作，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧
2020-11-11
vuex中的四个map方法的使用小结
vuex里面有四个map方法，他们分别可以针对不同的元素进行不同的代码生成，本文就来详细的介绍一下vuex中的四个map方法，具有一定的参考价值，感兴趣的可以了解一下
2023-05-05
Vue element商品列表的增删改功能实现
这篇文章主要介绍了Vue+element 商品列表、新增、编辑、删除业务实现，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2022-08-08
Vue子组件向父组件传值示范方法
这篇文章主要介绍了Vue子组件向父组件传值方法，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习吧
2023-03-03
vue 项目引入echarts 添加点击事件操作
这篇文章主要介绍了vue 项目引入echarts 添加点击事件操作，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧
2020-09-09
el-menu如何根据多层树形结构递归遍历展示菜单栏
这篇文章主要介绍了el-menu根据多层树形结构递归遍历展示菜单栏,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友参考下吧
2024-07-07
vue2 router 动态传参,多个参数的实例
下面小编就为大家带来一篇vue2 router 动态传参,多个参数的实例。小编觉得挺不错的，现在就分享给大家，也给大家做个参考。一起跟随小编过来看看吧
2017-11-11