VitePress 学习指南

主题

CSS 变量覆盖 ​

VitePress 默认主题使用 CSS 变量系统，可通过覆盖变量来定制外观。

版本说明

  • 本文档基于 VitePress v1.0.0+ 编写
  • CSS 变量系统在 v0.20.0+ 即可使用
  • 部分新增变量在后续版本中引入

颜色系统 ​

品牌颜色 ​

css
:root {
  /* 品牌主色 */
  --vp-c-brand-1: #646cff;      /* 最深色，用于文字 */
  --vp-c-brand-2: #535bf2;      /* 中等色，用于悬停 */
  --vp-c-brand-3: #3b3bdb;      /* 最浅色，用于背景 */
  --vp-c-brand-soft: rgba(100, 108, 255, 0.14);  /* 柔和色 */
}

预设颜色 ​

VitePress 提供了多种预设颜色：

css
:root {
  /* 绿色 */
  --vp-c-green-1: #3b9251;
  --vp-c-green-2: #2f8142;
  --vp-c-green-3: #207137;
  
  /* 黄色 */
  --vp-c-yellow-1: #d9a600;
  --vp-c-yellow-2: #c19600;
  --vp-c-yellow-3: #a37e00;
  
  /* 红色 */
  --vp-c-red-1: #d53934;
  --vp-c-red-2: #c42e29;
  --vp-c-red-3: #ae2320;
  
  /* 灰色 */
  --vp-c-gray-1: #515c67;
  --vp-c-gray-2: #414853;
  --vp-c-gray-3: #32363f;
}

语义颜色 ​

css
:root {
  /* 默认 */
  --vp-c-default-1: var(--vp-c-gray-1);
  --vp-c-default-2: var(--vp-c-gray-2);
  --vp-c-default-3: var(--vp-c-gray-3);
  
  /* 提示 */
  --vp-c-tip-1: var(--vp-c-brand-1);
  --vp-c-tip-2: var(--vp-c-brand-2);
  --vp-c-tip-3: var(--vp-c-brand-3);
  
  /* 警告 */
  --vp-c-warning-1: var(--vp-c-yellow-1);
  --vp-c-warning-2: var(--vp-c-yellow-2);
  --vp-c-warning-3: var(--vp-c-yellow-3);
  
  /* 危险 */
  --vp-c-danger-1: var(--vp-c-red-1);
  --vp-c-danger-2: var(--vp-c-red-2);
  --vp-c-danger-3: var(--vp-c-red-3);
}

深色模式 ​

为深色模式单独配置：

css
/* 深色模式 */
.dark {
  --vp-c-brand-1: #747bff;
  --vp-c-brand-2: #646cff;
  --vp-c-brand-3: #535bf2;
  
  /* 背景 */
  --vp-c-bg: #1e1e1e;
  --vp-c-bg-soft: #252525;
  --vp-c-bg-mute: #2f2f2f;
  
  /* 文字 */
  --vp-c-text-1: rgba(255, 255, 255, 0.87);
  --vp-c-text-2: rgba(255, 255, 255, 0.6);
}

组件变量 ​

版本说明

部分 CSS 变量在后续版本中新增，请根据实际使用的 VitePress 版本确认变量可用性。

变量类型最低版本说明
颜色系统v0.20.0基础颜色变量
组件变量v0.20.0按钮、导航栏等
首页样式v1.0.0英雄区域渐变等
响应式变量v1.0.0媒体查询相关

按钮 ​

css
:root {
  /* 品牌按钮 */
  --vp-button-brand-border: transparent;
  --vp-button-brand-text: var(--vp-c-white);
  --vp-button-brand-bg: var(--vp-c-brand-3);
  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
  --vp-button-brand-active-bg: var(--vp-c-brand-1);
  
  /* 替代按钮 */
  --vp-button-alt-border: var(--vp-c-default-1);
  --vp-button-alt-text: var(--vp-c-text-1);
  --vp-button-alt-bg: var(--vp-c-default-soft);
}

导航栏 ​

css
:root {
  --vp-nav-height: 64px;
  --vp-nav-bg-color: var(--vp-c-bg);
  --vp-nav-border-color: var(--vp-c-divider);
}

侧边栏 ​

css
:root {
  --vp-sidebar-width: 272px;
  --vp-sidebar-bg-color: var(--vp-c-bg-alt);
}

自定义容器 ​

css
:root {
  /* 提示容器 */
  --vp-custom-block-tip-border: var(--vp-c-brand-1);
  --vp-custom-block-tip-text: var(--vp-c-text-1);
  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
  
  /* 警告容器 */
  --vp-custom-block-warning-border: var(--vp-c-warning-1);
  --vp-custom-block-warning-text: var(--vp-c-text-1);
  --vp-custom-block-warning-bg: var(--vp-c-warning-soft);
  
  /* 危险容器 */
  --vp-custom-block-danger-border: var(--vp-c-danger-1);
  --vp-custom-block-danger-text: var(--vp-c-text-1);
  --vp-custom-block-danger-bg: var(--vp-c-danger-soft);
}

首页样式 ​

css
:root {
  /* 英雄区域标题 */
  --vp-home-hero-name-color: transparent;
  --vp-home-hero-name-background: linear-gradient(
    120deg,
    #bd34fe 30%,
    #41d1ff
  );
  
  /* 英雄区域图片背景 */
  --vp-home-hero-image-background-image: linear-gradient(
    -45deg,
    #bd34fe 50%,
    #47caff 50%
  );
  --vp-home-hero-image-filter: blur(44px);
}

代码块 ​

css
:root {
  --vp-code-line-height: 1.7;
  --vp-code-font-size: 0.875em;
  --vp-code-color: var(--vp-c-text-2);
  --vp-code-bg: var(--vp-c-default-soft);
  --vp-code-block-color: var(--vp-c-text-1);
  --vp-code-block-bg: var(--vp-c-bg-alt);
}

完整示例 ​

css
/* docs/.vitepress/theme/style.css */

/* 浅色模式 */
:root {
  /* 品牌色 - 使用自定义紫色 */
  --vp-c-brand-1: #7c3aed;
  --vp-c-brand-2: #6d28d9;
  --vp-c-brand-3: #5b21b6;
  --vp-c-brand-soft: rgba(124, 58, 237, 0.14);
  
  /* 首页英雄渐变 */
  --vp-home-hero-name-background: linear-gradient(
    120deg,
    #7c3aed 30%,
    #a78bfa
  );
  
  /* 英雄图片背景 */
  --vp-home-hero-image-background-image: linear-gradient(
    -45deg,
    #7c3aed 50%,
    #a78bfa 50%
  );
}

/* 深色模式 */
.dark {
  --vp-c-brand-1: #a78bfa;
  --vp-c-brand-2: #8b5cf6;
  --vp-c-brand-3: #7c3aed;
}

/* 自定义按钮样式 */
:root {
  --vp-button-brand-border: transparent;
  --vp-button-brand-text: #ffffff;
  --vp-button-brand-bg: #7c3aed;
}

/* 响应式调整 */
@media (min-width: 640px) {
  :root {
    --vp-home-hero-image-filter: blur(56px);
  }
}

@media (min-width: 960px) {
  :root {
    --vp-home-hero-image-filter: blur(68px);
  }
}

本项目自定义变量 ​

本项目在 theme/styles/variables.css 中定义了额外的 CSS 变量，用于统一管理间距、圆角、阴影和语义色。

间距系统 ​

css
:root {
  /* 间距变量 */
  --space-xs: 4px;
  --space-sm: 8px;
  --space-md: 16px;
  --space-lg: 24px;
  --space-xl: 32px;
  --space-2xl: 48px;
}

使用示例：

css
.custom-card {
  padding: var(--space-md);
  margin-bottom: var(--space-lg);
  gap: var(--space-sm);
}

圆角系统 ​

css
:root {
  /* 圆角变量 */
  --radius-sm: 4px;    /* 小圆角：标签、徽章 */
  --radius-md: 8px;    /* 中圆角：按钮、输入框 */
  --radius-lg: 12px;   /* 大圆角：卡片 */
  --radius-xl: 16px;   /* 超大圆角：模态框 */
  --radius-full: 9999px; /* 完全圆角：头像、药丸按钮 */
}

使用示例：

css
.badge {
  border-radius: var(--radius-sm);
}

.card {
  border-radius: var(--radius-lg);
}

.avatar {
  border-radius: var(--radius-full);
}

阴影系统 ​

css
:root {
  /* 阴影变量 - 浅色模式 */
  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.06);
  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
  --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.12);
  --shadow-xl: 0 16px 40px rgba(0, 0, 0, 0.16);
}

/* 深色模式阴影更深 */
.dark {
  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.25);
  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.35);
  --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.45);
  --shadow-xl: 0 16px 40px rgba(0, 0, 0, 0.55);
}

使用示例：

css
.dropdown {
  box-shadow: var(--shadow-md);
}

.modal {
  box-shadow: var(--shadow-xl);
}

语义色系统 ​

css
:root {
  /* 成功色 */
  --color-success: #10b981;
  --color-success-soft: rgba(16, 185, 129, 0.14);

  /* 警告色 */
  --color-warning: #f59e0b;
  --color-warning-soft: rgba(245, 158, 11, 0.14);

  /* 危险色 */
  --color-danger: #ef4444;
  --color-danger-soft: rgba(239, 68, 68, 0.14);

  /* 信息色 */
  --color-info: #3b82f6;
  --color-info-soft: rgba(59, 130, 246, 0.14);
}

/* 深色模式调整透明度 */
.dark {
  --color-success-soft: rgba(16, 185, 129, 0.18);
  --color-warning-soft: rgba(245, 158, 11, 0.18);
  --color-danger-soft: rgba(239, 68, 68, 0.18);
  --color-info-soft: rgba(59, 130, 246, 0.18);
}

使用示例：

css
.alert-success {
  background: var(--color-success-soft);
  border-color: var(--color-success);
  color: var(--color-success);
}

.alert-danger {
  background: var(--color-danger-soft);
  border-color: var(--color-danger);
  color: var(--color-danger);
}

变量速查表 ​

颜色变量 ​

变量用途默认值
--vp-c-brand-1品牌主色（文字）#6366f1
--vp-c-brand-2品牌悬停色#4f46e5
--vp-c-brand-3品牌背景色#4338ca
--vp-c-brand-soft品牌柔和背景rgba(99, 102, 241, 0.14)

布局变量 ​

变量用途默认值
--vp-nav-height导航栏高度64px
--vp-sidebar-width侧边栏宽度272px
--vp-layout-max-width内容最大宽度1440px

本项目扩展 ​

变量用途默认值
--space-md标准间距16px
--radius-md标准圆角8px
--shadow-md标准阴影0 4px 12px rgba(0, 0, 0, 0.08)
--color-success成功色#10b981
--color-warning警告色#f59e0b
--color-danger危险色#ef4444
--color-info信息色#3b82f6

下一步 ​

学习 布局插槽 来更灵活地定制页面结构。

贡献者

加载中...

想要成为贡献者？

在 CNB 上参与贡献

Copyright © 2016 - 2026 VitePress 学习指南