vuepress2.0使用教程（5）- md文件的玩法

百家饭OpenAPI

已于 2022-09-30 17:00:19 修改

阅读量2.4k

点赞数 1

分类专栏： Vuepress2 文章标签： vue.js 前端 javascript

于 2022-08-06 17:00:00 首次发布

本文链接：https://blog.csdn.net/baijiafan/article/details/126176064

版权

Vuepress2 专栏收录该内容

11 篇文章 5 订阅

订阅专栏

百家饭团队开发的百家饭OpenAPI平台是用vuepress2.0搭建的，搭建的时候不知道2.0还处在beta状态，所以导致后来踩了一些坑，使用过程中vuepress2.0也从2.0.0-beta.18升到了2.0.0-beta.48，有很多的变化，所以想写一个教程介绍一下vuepress2.0的情况以及使用经验。

大致计划写这些内容吧：

这里先给搜索进来的同学提个醒：凡是网上搜索到需要修改clientAppEnhance.js 文件的教程都已经过时，最新版本已不再使用。另外说个题外话，我查了下，我为数不多的搜索关键词里面，vuepress的占了大部分，这里感谢大家的关注，这个教程肯定有不合理的地方，如果有任何需要帮助的，大家都可以留言，我尽力解答。

这两年写程序文档基本上都是写MD文件了，所以我假设大家都清楚基础的md语法，包括通常的分级标题等。另外我们要先讲一下vuepress解析Md文件的流程再开始详细介绍。

vuepress解析md文件，是将md文件解析成vue文件，再把vue文件作为整体代码的一部分参与编译，最终形成网站整体内容的。这个流程大家先有个印象，因为像markdown模板、markdown混编vue等都和这块有关系。

Markdown文件的基础用法

基础的md语法，这些vuepress都支持，vuepress使用的是markdown-it作为md文件解析器，官方文档介绍支持表格和删除线效果，类似如下

如果你一直在进行本文章相关内容的尝试工作，可以发现所有标题旁边都有个绿色的#，上图所示内容也有，这个在官方中文文档称为标题锚点，可以通过配置修改，讲到配置部分的时候我们再讲这块。

代码相关

代码这块vuepress支持各类语言的语法渲染（基于prismjs），使用md文件的代码块（```和```之间的行）进行

```ts{1,6-8}
import { defaultTheme, defineUserConfig } from 'vuepress'

export default defineUserConfig({
  title: '你好， VuePress',

  theme: defaultTheme({
    logo: 'https://vuejs.org/images/logo.png',
  }),
})
```

代码块标注后面跟语言名称，大括号里跟希望高亮现实的行，上面这个示例就希望高亮显示第1行和第6-8行，效果如下

行内代码块也是支持的，例如行内代码测试`const test= new Ojbect();`显示为

但是行内代码块设置语言等功能就没有了。

Markdown相关配置解析

然后我们讲一下vuepress和markdown相关的配置功能

anchor控制

anchor就是上述我们提到的在每一个标题旁边的绿色#符号。通过在config.js附加以下设置可以修改相关配置

    markdown: {
        anchor: {
            level: [1, 2, 3, 4, 5, 6],
            permalink: anchor.permalink.ariaHidden({
                class: 'header-anchor',
                placement: 'before', //可设置为after
                symbol: '#' //显示文字，可自行修改
            }),
        }
    },

配置的位置在.vuepress里面的config.js里面，这个配置里，level控制添加的级别，premalink控制主要的显示渲染功能，注意，permalink不是一个单纯的配置项，必须引用markdown-it-anchor才能进一步调用相关函数进行配置，也就是在config.js的头部添加

const anchor = require('markdown-it-anchor')

然后调用anchor.premalink.xxx来设置，总共有下面几种：

headerLink：标题本身作为链接
linkAfterHeader：标题后方插入html自动生成链接
linkInsideHeader：标题内部插入html自动生成链接
ariaHidden：和linkInsideHeader，但在aria幻境中隐藏

我觉得中文语境中，headerLink其实最简单实用。

code相关

其他主要的配置还有和code相关的一些配置，示例说明如下，这部分配置的放置位置在markdown里面，和上一段的anchor同级。

        code: {
            highlightLines: true, //是否启用高亮功能
            lineNumbers: false, //是否启用行号功能
            preWrapper: true, //是否启用外包装层，上面两个选项的依赖项，启用上面两项必须启用这一项
            vPre: {
                block: true， //代码块启用v-pre标签
                inline: true //行内代码启用v-pre标签
            }
        }

大家按上面的注释选择配置就可以了。

这里面的vPre段在文章最后一章里有详细说明，和是否支持vue的模板有关系。

Markdown高级标签功能

第一节我们提到了Markdown的一般编辑功能，这一段我们讲解一下vuepress的高级Markdown配置。

文章全局标签

在markdown文件的顶部，我们可以配置一个标签区域来控制vuepress的一些渲染行为，配置文章的标题等功能。vuepress把这部分成为frontmatter

这部分是由---包围起来的yaml格式的多行文本，例如

---
lang: zh-CN
title: 页面的标题
description: 页面的描述
---

通常，如果没有这段里的title信息，文章的title是由第一个一级标题指定的。通过这一段，我们就可以控制对应的行为。

这两段可配置的内容较多，详细可以参考官方文档的两块内容：

前往 Frontmatter 参考查看 VuePress 支持的 Frontmatter 配置。

前往默认主题 > Frontmatter 参考查看默认主题的 Frontmatter 配置。

Md中的容器

除了一般的Md语法之外，vuepress还支持容器功能，容器是以:::包围的多行md文本，例如

::: warning

注意，这是warning容器的内容

:::

这里的warning是容器的名称，vuepress默认主题引入了很多容器，包括上面这个例子使用的warning、tip、details、danger

其中details是一个默认折叠，点击打开的标签。

Markdown混合vue

代码中的模板

有时候我们会引用一些变量的内容，例如我们希望从远程获得一个当前版本号，并显示在一段文字中

```
data.query({{ version }})
```

因为里面有vue使用的{{和}}，这段文字默认会包含v-pre标签，使得vue忽略这个模板，如果要使其可以被vue控制，这时我们需要使用v-no-pre标签来让vuepress将这段代码作为vue代码使用（添加no-v-pre）标签

```:no-v-pre
data.query("{{data?.CallUrl}}/{{data?.Url}}",{查询参数1:值1,查询参数1:值1})
```

像写vue一样写md

前面我们讲过，md文件会被vuepress先解析成vue，再进一步编译，因此，我们完全可以像写vue一样写md文件

加入style

在md文件中加入style部分来改变样式。

<style>
    h2 {
        color:yellow
    }
</style>

加入setup script

同理，我们也可以加入setup部分，setup部分里就可以引用axios调用后端数据，或者引入新的控件

<script setup>
import UserConfigAdmin from "@theme/components/user-config-admin.vue"
import MpcConfigAdmin from "@theme/components/mpc-config-admin.vue"
import SiteConfigAdmin from "@theme/components/site-config-admin.vue"
import SecurityAdmin from "@theme/components/security-admin.vue"
</script>

然后就可以直接用html语法来使用他们

<user-config-admin></user-config-admin>

或者用{{ variable}}来调用某个数据。

或者像我们一样，通过引用useThemeData来调用主题的一些配置数据

当前版本号：{{themeData.client_version}}


<script setup>
import { useThemeData } from '@vuepress/plugin-theme-data/lib/client'
const themeData = useThemeData();

</script>