简单介绍下 VitePress 中的 vp-doc 和 vp-raw

VitePress 是一个轻量级的静态网站生成器，专为快速构建文档网站而设计。它是基于 Vite 和 Vue 3 构建的，旨在提供快速的开发体验和高效的构建过程。

存在两个需要注意的点：vp-doc 和 vp-raw，它们代表了不同的 CSS 样式类和用途，涉及页面内容的呈现方式。

1. vp-doc 的含义与用法

1.1 含义

vp-doc 是 VitePress 用来构建文档页面时，应用于整个页面 布局的一种 CSS 样式类。它是 VitePress 内部定义的一个类，作为页面的根容器元素，包含了文档的结构样式，确保文档内容的排版、间距、背景色等统一性。

1.2 用法

vp-doc 作为文档页面的根容器，包含了所有文档内容。它通常用于包裹整个文档站点的 HTML 结构。

通过对 vp-doc 类样式进行修改，可以自定义整个文档站点的布局和样式。

在 VitePress 中，vp-doc 是自动添加的，无需手动去创建这个类。它作为 VitePress 渲染文档的一个基础，控制页面的整体布局。

因此，当遇到自定义样式不生效时，需要考虑是否优先使用了 vp-doc 样式。

举个 🌰

当编写一个 table 组件时，展示为：

代码为：

javascript 复制代码

import { defineComponent } from "vue";
import { ElButton, ElTable, ElTableColumn } from "element-plus";
import "./index.less";

export default defineComponent({
  setup() {
    const tableData = [
      { name: 'Sophia', age: 18, country: '美国' },
      { name: 'William', age: 20, country: '新加坡' },
      { name: 'Alice', age: 25, country: '中国' },
      { name: 'Evelyn', age: 30, country: '法国' },
      { name: 'Emma', age: 10, country: '俄罗斯' },
    ];

    return () => (
      <div class="table-container">
        <ElTable data={tableData} style={{ width: '100%' }} border stripe>
          <ElTableColumn prop="name" label="姓名" />
          <ElTableColumn prop="age" label="年龄" />
          <ElTableColumn prop="country" label="国家" />
          <ElTableColumn min-width="120" label="操作">
            {{
              default: () => (
                <div class="operation">
                  <ElButton link type="primary" size="default">查看</ElButton>
                  <ElButton link type="primary" size="default">编辑</ElButton>
                  <ElButton link type="primary" size="default">删除</ElButton>
                </div>
              )
            }}
          </ElTableColumn>
        </ElTable>
      </div>
    );
  }
});

问题来了：为什么表格展示有问题呢？

翻看一下元素就明白了，vp-doc 样式起作用，全部注释掉之后，就恢复为正常表格。

也就是给属性默认值：

css 复制代码

.vp-doc table:not(:where(.vp-raw, .vp-raw *)) {
  border-collapse: initial;
  margin: 0 auto;
  display: table;
}

注意📢：这个样式的位置要考虑全面，避免影响到全局。

正常展示为：

遇到其余类似情况，也是一样的处理。

1.3 注意事项

vp-doc 是 VitePress 内部使用的一个类，通常不需要直接去修改它，除非需要全局定制样式。它是页面的主要结构，包含了 VitePress 的默认布局，除非有特殊的需求，通常不建议直接去删除或修改这个类的结构。

2. vp-raw 的含义与用法

2.1 含义

vp-raw 是 VitePress 中用于处理原始 HTML 或未经过解析的内容的一个特殊类。它允许用户在文档中插入原始 HTML 或其他不会被 VitePress 处理的内容。

2.2 用法

vp-raw 通常与 VitePress 渲染过程中需要"原生"呈现的内容结合使用。

举个 🌰

在 VitePress 中，使用普通 class 类名和 vp-raw 类名直接插入 HTML 代码块的区别。

普通 class

html 复制代码

<div class="custom-html">
  <p>This content is implemented using a regular class name.</p>
</div>

vp-raw 类

html 复制代码

<div class="vp-raw">
  <p>This content is implemented using the vp-raw class name.</p>
</div>

区别：二者的 p 元素样式是不同的。

2.3 意义

vp-raw 类的关键在于，**它可以防止内容在渲染过程中被 VitePress 进一步解析，保留其原始形式。**这样可以让开发者插入非 Markdown 或非 VitePress 处理的内容。

注意：尽量避免过度使用 vp-raw，因为直接插入 HTML 可能会破坏 VitePress 的一致性和文档结构。只有在必要时，才建议使用该类。

2.4 特别使用

当项目中不想使用额外的 vp-doc 的样式，也就是 VitePress 本身的样式文件，可以在目录：vitepress/vp-demo/index.vue 内部代码的最外层设置：

css 复制代码

<div class="vp-raw">
  ...
</div>

即可实现页面应用的都是自定义样式。

3. 额外补充一点「::: demo」

在 VitePress 中，::: demo 是一个非常有用的语法，它是 VitePress 中的一个自定义容器，用于创建一个可交互的代码演示区域。通过包裹代码块的方式，使得代码示例可以在页面上呈现出来。

也就是上述表格的展示方式。