vitepress趣玩系列——文档样式优化

“我报名参加金石计划1期挑战——瓜分10万奖池，这是我的第1篇文章，点击查看活动详情”

前言

经过系列中前面两篇文章，我们得到了一个兼具效果和美观的vitepress首页，有小伙伴还没开始搭建vitepress系统的可以参考我的前两篇文章，或者直接看我的github仓库，我会把代码开放

• vitepress趣玩系列——首页样式优化
• vitepress趣玩系列——首页内容优化
• github代码

下面我们来开始着手对文档样式进行一些调整吧，并且尝试插入一些源码解析，让大家对里面的原理更深入了解

题外话，掘金icon

在首页中我们在右上角添加了github的小图标，这是vitepress默认支持的icon，如果我希望加入别的icon呢，（是的，就是想引流）

通过查看源码，我们可以看到内置了以下几种icon

发现最下面可以传入一个对象，来使用自定义的svg图标

这里我先贴出掘金svg的代码，是从阿里的iconfont中搜到的，链接在这里，你们能调整颜色

<svg t="1663660926462" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="2449" width="200" height="200"><path d="M465.189 161.792c-22.967 18.14-44.325 35.109-47.397 37.742l-5.851 4.68 10.971 8.632c5.998 4.827 11.85 9.508 13.02 10.532 1.17 1.024 17.993 14.336 37.156 29.696l34.962 27.795 5.267-3.95c2.925-2.194 23.259-18.432 45.348-35.986 21.943-17.555 41.253-32.768 42.716-33.646 1.609-1.024 2.779-2.194 2.779-2.78 0-0.438-9.655-8.63-21.504-17.846-11.995-9.363-22.674-17.847-23.845-18.871-15.945-13.02-49.737-39.059-50.76-39.059-0.586 0.147-19.896 14.922-42.862 33.061z m233.325 180.37C507.465 493.275 508.928 492.105 505.417 489.911c-3.072-1.902-11.556-8.485-64.073-50.03-9.07-7.168-18.578-14.775-21.358-16.823-2.78-2.194-8.777-6.875-13.312-10.532-4.68-3.657-10.679-8.339-13.312-10.533-13.165-10.24-71.095-56.027-102.107-80.457-5.852-4.681-11.41-8.485-12.142-8.485-0.731 0-10.971 7.754-22.674 17.116-11.703 9.508-22.674 18.286-24.284 19.456-1.755 1.17-5.12 3.95-7.46 6.144-2.34 2.34-4.828 4.096-5.413 4.096-3.072 0-0.731 3.072 6.437 8.777 4.096 3.218 8.777 6.875 10.094 8.046 1.316 1.024 10.24 8.045 19.748 15.506s23.26 18.286 30.428 23.99c19.31 15.215 31.89 25.308 127.853 101.084 47.836 37.742 88.796 69.779 90.844 71.095 3.657 2.487 3.95 2.487 7.46-0.292a1041.42 1041.42 0 0 0 16.092-12.727c6.875-5.413 14.775-11.703 17.554-13.897 30.135-23.699 80.018-63.05 81.774-64.512 1.17-1.024 12.434-9.802 24.868-19.603s37.888-29.696 56.32-44.324c18.579-14.629 46.227-36.425 61.733-48.567 15.506-12.142 27.794-22.528 27.502-23.26-0.878-1.17-57.637-47.104-59.978-48.274-0.731-0.439-18.578 12.727-39.497 29.257z" fill="#8a8a8a" p-id="2450"></path><path d="M57.93 489.326c-15.215 12.288-28.527 23.405-29.697 24.576-2.34 2.194-5.412-0.44 80.018 66.852 33.207 26.185 32.622 25.747 57.637 45.495 10.386 8.192 36.279 28.672 57.783 45.495 38.18 30.135 44.91 35.401 52.663 41.545 2.048 1.756 22.967 18.14 46.372 36.572 23.26 18.432 74.167 58.514 112.933 89.088 38.912 30.573 71.095 55.734 71.826 56.027 0.732 0.293 7.46-4.389 14.921-10.386 21.797-16.97 90.259-70.949 101.523-79.872 5.705-4.535 12.873-10.24 15.945-12.58 3.072-2.488 6.436-5.12 7.314-5.852 0.878-0.878 11.85-9.509 24.283-19.31 20.773-16.091 59.1-46.226 64.366-50.615 1.17-1.024 5.12-4.096 8.777-6.875 3.657-2.78 7.9-6.29 9.509-7.607 1.609-1.317 14.775-11.703 29.257-23.113 29.11-22.82 42.277-33.207 88.503-69.632 17.262-13.605 32.475-25.454 33.646-26.478 2.486-2.048 31.451-24.869 44.617-35.255 4.827-3.657 9.07-7.168 9.508-7.607 0.44-0.585 5.998-4.827 12.435-9.8 6.436-4.828 13.165-10.24 15.067-11.85l3.365-2.926-9.948-7.753c-5.412-4.388-10.24-8.192-10.679-8.63-1.17-1.317-22.381-18.433-30.135-24.284-3.95-3.072-7.314-5.998-7.606-6.73-1.317-3.071-6.73 0.147-29.258 17.994-13.458 10.532-25.746 20.187-27.355 21.504-1.61 1.463-10.533 8.338-19.749 15.652-9.216 7.168-17.115 13.459-17.554 13.898-0.439 0.438-6.583 5.412-13.897 10.971-7.168 5.559-15.214 11.703-17.7 13.75-4.974 4.097-5.413 4.39-20.334 16.239-5.56 4.388-11.264 8.777-12.435 9.8-1.17 1.025-20.333 16.092-42.422 33.354-22.09 17.408-41.546 32.768-43.155 34.084-1.609 1.463-14.482 11.557-28.525 22.528s-40.814 32.037-59.539 46.812c-18.578 14.775-42.276 33.353-52.516 41.399s-23.26 18.285-28.965 22.82l-10.386 8.339-4.389-3.072c-2.34-1.756-4.68-3.511-5.12-3.95-0.439-0.439-4.973-4.096-10.24-8.046-11.849-9.216-14.482-11.264-16.676-13.166-0.878-0.877-4.243-3.51-7.46-5.851-3.22-2.487-6.145-4.681-6.584-5.12-0.439-0.439-6.875-5.705-14.482-11.703-7.607-5.851-14.921-11.556-16.091-12.58-1.317-1.17-17.116-13.605-35.255-27.795-17.993-14.19-35.109-27.648-38.035-29.842-5.705-4.681-33.499-26.624-125.074-98.743-34.523-27.209-72.704-57.344-84.846-66.852-49.737-39.498-55.15-43.594-56.905-43.447-0.877 0-14.043 10.24-29.257 22.528z" fill="#8a8a8a" p-id="2451"></path></svg>

然后修改.vitepress/config.ts中的配置

export default defineConfig({
    // ...
    themeConfig: {
        socialLinks: [
      { icon: "github", link: "https://github.com/gumingWu/vitepress-fun" },
      {
        icon: {
              svg: 'xxxxxx',  // 这里贴上svg内容，太长了我就省略了，拷贝上面的就行
        },
        link: "https://juejin.cn/user/1469381099657902",
      },
    ],
    }
    // ...
})

在首页右上角即可看到掘金的logo，并且点击能正常跳转

准备工作

我们要优化文档样式，那么首先就得有一个文档页面，我们先来新建一个文档页

在文档根目录下，也就是跟.vitepress目录同级的路径下，新建guide目录，然后新建index.md文件，在文件中输入内容

# Hello World

Im Guide

然后修改根目录下的index.md中的按钮跳转路径

hero:
  name: VitePress-Fun
  text: VitePress趣玩系列
  tagline: Lorem ipsum...
  image:
    src: /cat.png
    alt: VitePress
  actions:
    - theme: brand
      text: Get Started
      link: /guide/

添加一个菜单栏sidebar，在.vitepress/theme中配置

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: "基础",
        items: [{ text: "快速开始", link: "/guide/" }],
      },
    ],
  }
})

这时候点击首页的Get Start按钮，就会跳转到guide/index.md这个文件了，并且显示文件中写的内容

拓展，路由的写法

我们需要展示guide/index.md的内容时，sidebar配置是

sidebar: [
  {
    text: "基础",
    items: [{ text: "快速开始", link: "/guide/" }],
  },

那如果我们在guide目录下有一个文件usage.md，我们要这样配置sidebar才能正确跳转

sidebar: [
  {
    text: "基础",
    items: [
      { text: "快速开始", link: "/guide/" },
      { text: "使用方法", link: "/guide/usage" },
    ],
  },
],

同理，我们有另外的内容目录，也是跟guide一样进行配置，新建目录components，与guide目录同级，并且新建两个文件comA.md、comB.md，此时配置的sidebar为

sidebar: [
  {
    text: "基础",
    items: [
      { text: "快速开始", link: "/guide/" },
      { text: "使用方法", link: "/guide/usage" },
    ],
  },
  {
    text: "组件",
    items: [
      { text: "ComA 组件A", link: "/components/comA" },
      { text: "ComB 组件B", link: "/components/comB" },
    ],
  },
],

路由总结

• 对于目录下的index.md，只需要写成/目录名/，比如上面的/guide/
• 对于目录下的非index.md的其他md，需要带上文件名，比如上面的/guide/usage
• 注意，/guide/usage后面不能带/，如果带上/，就表示guide目录下的usage目录下的index.md

文档适配主题色

可以看到我们的文档的主题色还是默认的vitepress主题的绿色，我们需要通过修改vitepress暴露的css变量来更改整个主题基色

如果跟着本系列做下来的工程，我们的css变量文件是放在.vitepress/theme/style/var.css，在这个文件中加上主题基色属性

:root {
  /* 标题 */
  --vp-home-hero-name-color: transparent;
  --vp-home-hero-name-background: linear-gradient( 135deg, #F6CEEC 10%, #D939CD 100%);
  
  /* 图标背景 */
  --vp-home-hero-image-background-image: linear-gradient( 135deg, #F6CEEC 10%, #D939CD 100%);
  --vp-home-hero-image-filter: blur(150px);

  /* brand按钮 */
  --vp-button-brand-border: #F6CEEC;
  --vp-button-brand-text: #F6CEEC;
  --vp-button-brand-bg: #D939CD;

  --vp-button-brand-hover-border: #F6CEEC;
  --vp-button-brand-hover-text: #fff;
  --vp-button-brand-hover-bg: #D939CD;

  --vp-button-brand-active-border: #F6CEEC;

  /* 主题基色 */
  --vp-c-brand: #D939CD;
  --vp-c-brand-light: #D939CD;
  --vp-c-brand-dark: #D939CD;
}

可以看到，文档中的按钮和锚点色调跟主题是保持一致的了

更改代码块的主题

假设我们做一个工具类文档，或者一个组件库文档，就会在文档中添加代码块来展示使用方法，比如我们在components/comA.md中修改内容

# ComA

我是ComA

```vue
<template>
  <div>{{ msg }}</div>
</template>

<script setup>
const msg = '我是ComA组件'
</script>

可以看到代码块了

如果我们希望使用不同的主题代码块呢？这时候我们可以通过修改.vitepress/config.ts中的markdown属性，添加上主题

export default defineConfig({
    // ...
    markdown: {
      theme: {
        light: "vitesse-light",
        dark: "vitesse-dark",
      },
    },
    // ...
})

再看文档中的代码块，我们就能发现代码块的代码高亮风格已经改变了

源码解析

在vitepress源码中，src/node/cli.ts表示vitepress这个cli所进行的处理，比如我们打开文档时所用到的命令vitepress dev，在这里就能看到处理过程

可以看到，vitepress dev命令其实就是启动了一个server，然后开启监听

以上是开启服务所进行的步骤，处理代码块主题的处理在圈出的plugins属性中进行，这里是调用了createVitePressPlugin方法进行处理，第一个参数config就是读取的.vitepress/config.ts中的用户配置，和系统默认配置进行merge后的配置，感兴趣的伙伴可以看上面的resolveConfig方法进一步了解

createVitePressPlugin方法中，首先将配置解构出来，在上图的红圈中使用了这个markdown配置，那么这里就是使用markdown配置的地方了

createMarkdownToVueRenderFn方法中的第二个参数options就是刚才说的markdown配置，这里传入一个createMarkdownRenderer方法生成一个md实例，这里就是对markdown配置中的theme属性进行使用的地方

注意到，vitepress中的md解析器，都是使用了markdown-it库来实现的

红圈中的highlight属性，就是markdown-it构造方法的highlight属性，传入了我们在.vitepress/config.ts配置的theme属性

所以通过这里能看到，不仅theme属性能配置代码块主题，用highlight属性也能进行代码块主题配置

因为我们传入的是theme属性，所以highlight的值由后面的highlight方法生成

通过该方法，我们可以得出以下结论：

• theme配置，可以配成字符串，或一个有name属性的对象，或者一个有light属性和dark属性的对象

  // 写法一
  theme: 'vitesse-light'
  
  // 写法二
  theme: {
      name: 'vitesse-light'
  }
  
  // 写法三
  theme: {
      light: 'vitesse-light',
      dark: 'vitesse-dark'
  }
  

• 代码高亮方案使用的是shiki，getHighlighter方法来自shiki库

• 代码块主题，是通过<pre>标签包裹实现的

我们既然知道了代码高亮方案是来自shiki，那么就表示我们能使用shiki库中的所有高亮主题了，以下是能提供的高亮主题，来源github仓库

我们尝试着改成其他主题

export default defineConfig({
    // ...
    markdown: {
      theme: {
        light: "material-lighter",
        dark: "material-darker",
      },
    },
    // ...
})

修改代码块背景色

vitepress默认的代码块背景色都是黑色，如果我希望能在亮色模式的时候用白色，深色模式的时候才用黑色，要怎么做呢

通过浏览器控制台定位元素，我们可以看到代码块的background-color由一个css变量--vp-code-block-bg控制，我们可以通过修改这个变量，达到修改代码块背景色的需求

修改.vitepress/theme/style/var.css

:root {
    /* 代码块背景色 */
  --vp-code-block-bg: rgba(125,125,125,.04);
}

可以看到两种模式下的代码块显示效果都不错