VitePress 学习指南

主题

自定义布局 ​

本站内置了 4 种常用页面布局，通过 frontmatter 的 layout 字段即可调用，无需编写组件代码。

版本说明

  • 本功能为站点自定义扩展，需要 VitePress v1.0.0+
  • 基于 VitePress 默认主题扩展开发
  • 支持 Node.js 18.0.0 及以上版本

快速开始 ​

在 Markdown 文件的 frontmatter 中指定布局类型：

yaml
---
title: 页面标题
layout: blog-list  # 布局类型
---

可用布局 ​

VitePress 提供了 3 种默认布局，本站扩展了 4 种自定义布局：

VitePress 默认布局 ​

布局用途说明
doc文档页面（默认）包含侧边栏、导航栏，适合教程文档
page宽页面布局无侧边栏，适合独立页面如 404
home首页布局用于首页 Hero 区域展示

本站自定义布局 ​

布局用途特性在线演示
blog-list博客文章列表标签筛选、关键词搜索、网格布局查看演示
about个人/团队介绍个人信息卡片、技能进度条、工作经历时间线查看演示
links友情链接分类展示、申请说明、本站信息查看演示
projects项目作品展示精选项目、状态筛选、标签筛选查看演示

博客文章列表 ​

用于展示博客文章列表，支持标签筛选和关键词搜索。

基础用法 ​

yaml
---
title: 博客文章
layout: blog-list
---

完整配置 ​

yaml
---
title: 博客文章
layout: blog-list
posts:
  - title: VitePress 入门指南
    url: /guide/getting-started
    date: 2026-02-28
    excerpt: 从零开始学习 VitePress，掌握静态站点生成器的核心概念和基本使用方法。
    tags: [VitePress, 教程]
    author: 作者名
    cover: /images/cover1.jpg
  - title: 主题定制详解
    url: /theme/custom-theme
    date: 2026-02-27
    excerpt: 深入了解 VitePress 主题定制，包括默认主题配置和自定义主题开发。
    tags: [VitePress, 主题]
    author: 作者名
    cover: /images/cover2.jpg
  - title: Markdown 扩展语法
    url: /basics/markdown
    date: 2026-02-26
    excerpt: VitePress 扩展了 Markdown 语法，支持 GitHub 风格的表格、任务列表等。
    tags: [Markdown, 基础]
    author: 作者名
---

字段说明 ​

字段类型必需说明
titlestring✅文章标题
urlstring✅文章链接
datestring✅发布日期
excerptstring✅文章摘要
tagsstring[]✅标签数组
authorstring❌作者名
coverstring❌封面图片路径

功能特性 ​

  • 标签筛选：点击标签快速筛选相关文章
  • 关键词搜索：实时搜索文章标题和摘要
  • 响应式布局：自适应不同屏幕尺寸
  • 封面图支持：可选的封面图片展示

关于页面 ​

用于展示个人或团队介绍信息，支持技能展示和工作经历。

基础用法 ​

yaml
---
title: 关于我
layout: about
---

完整配置 ​

yaml
---
title: 关于我
layout: about
profile:
  name: 张三
  title: 全栈开发工程师
  avatar: /images/avatar.jpg
  location: 北京市海淀区
  bio: 热爱开源，专注于 Web 技术开发。5 年前端开发经验，熟悉 Vue、React、TypeScript 等技术栈。
  email: zhangsan@example.com
  social:
    github: https://github.com/zhangsan
    twitter: https://twitter.com/zhangsan
    weibo: https://weibo.com/zhangsan
skills:
  - name: Vue.js
    level: 90
    color: '#42b883'
  - name: TypeScript
    level: 85
    color: '#3178c6'
  - name: React
    level: 80
    color: '#61dafb'
  - name: Node.js
    level: 75
    color: '#339933'
  - name: CSS/SCSS
    level: 85
    color: '#cc6699'
stats:
  - label: 年经验
    value: 5+
  - label: 开源项目
    value: 20+
  - label: 技术文章
    value: 100+
  - label: GitHub Stars
    value: 2k+
experiences:
  - company: 某科技有限公司
    position: 高级前端工程师
    period: 2022-03 至今
    description: 负责公司核心产品的前端架构设计和开发，主导技术选型和代码规范制定。
  - company: 另一家公司
    position: 前端工程师
    period: 2019-07 ~ 2022-02
    description: 参与多个项目的开发，积累了丰富的前端开发经验。
---

字段说明 ​

profile 配置 ​

字段类型必需说明
namestring✅姓名/昵称
titlestring✅职位/头衔
avatarstring✅头像图片路径
locationstring❌所在地
biostring❌个人简介
emailstring❌邮箱地址
socialobject❌社交链接

social 支持的平台 ​

  • github - GitHub 主页
  • twitter - Twitter/X 主页
  • weibo - 微博主页

skills 配置 ​

字段类型必需说明
namestring✅技能名称
levelnumber✅熟练度 (0-100)
colorstring❌进度条颜色

stats 配置 ​

字段类型必需说明
labelstring✅统计项名称
valuestring✅统计值

experiences 配置 ​

字段类型必需说明
companystring✅公司名称
positionstring✅职位
periodstring✅时间段
descriptionstring❌工作描述

友情链接 ​

用于展示友情链接，支持分类展示和申请说明。

基础用法 ​

yaml
---
title: 友情链接
layout: links
---

完整配置 ​

yaml
---
title: 友情链接
layout: links
categories:
  - name: 技术博客
    links:
      - name: 阮一峰博客
        url: https://www.ruanyifeng.com/blog/
        avatar: https://www.ruanyifeng.com/blog/images/avatar.jpg
        description: 科技爱好者周刊，每周五发布，分享优质技术内容。
      - name: 张鑫旭博客
        url: https://www.zhangxinxu.com/
        avatar: https://www.zhangxinxu.com/avatar.png
        description: CSS 大神，专注前端开发与用户体验。
  - name: 开源项目
    links:
      - name: Vue.js
        url: https://vuejs.org/
        avatar: https://vuejs.org/images/logo.png
        description: 渐进式 JavaScript 框架，易学易用。
      - name: VitePress
        url: https://vitepress.dev/
        avatar: https://vitepress.dev/vitepress-logo-mini.svg
        description: Vue 驱动的静态站点生成器。
  - name: 朋友们
    links:
      - name: 小明的博客
        url: https://xiaoming.blog/
        avatar: https://xiaoming.blog/avatar.jpg
        description: 分享生活与技术点滴。
applyInfo:
  name: VitePress 学习指南
  url: https://your-site.com
  avatar: https://your-site.com/logo.svg
  description: VitePress 完整学习指南，从入门到精通。
requirements:
  - 网站内容健康、原创为主
  - 网站正常运行超过 3 个月
  - 支持 HTTPS 协议
  - 优先考虑技术类博客
---

字段说明 ​

categories 配置 ​

字段类型必需说明
namestring✅分类名称
linksarray✅链接数组
字段类型必需说明
namestring✅网站名称
urlstring✅网站链接
avatarstring❌头像/Logo 图片
descriptionstring✅网站简介

applyInfo 配置 ​

字段类型必需说明
namestring✅本站名称
urlstring✅本站链接
avatarstring❌本站 Logo
descriptionstring❌本站简介

requirements 配置 ​

友链申请要求列表，可选配置。

项目展示 ​

用于展示项目作品集，支持精选项目、状态筛选和标签筛选。

基础用法 ​

yaml
---
title: 项目作品
layout: projects
---

完整配置 ​

yaml
---
title: 项目作品
layout: projects
projects:
  # 精选项目
  - name: VitePress 博客主题
    description: 一个简洁优雅的 VitePress 博客主题，支持深色模式、全文搜索、评论系统等功能。
    image: /images/projects/theme.png
    tags: [Vue, TypeScript, VitePress]
    status: active
    featured: true
    links:
      demo: https://theme-demo.example.com
      github: https://github.com/username/vitepress-theme
      docs: https://theme-docs.example.com
      npm: https://www.npmjs.com/package/vitepress-theme
  
  - name: 组件库
    description: 基于 Vue 3 的企业级 UI 组件库，包含 50+ 高质量组件。
    image: /images/projects/components.png
    tags: [Vue, TypeScript, 组件库]
    status: active
    featured: true
    links:
      demo: https://components-demo.example.com
      github: https://github.com/username/component-lib
      docs: https://component-docs.example.com
  
  # 普通项目
  - name: CLI 工具
    description: 项目脚手架工具，快速创建项目模板。
    tags: [Node.js, CLI]
    status: active
    featured: false
    links:
      github: https://github.com/username/cli-tool
      npm: https://www.npmjs.com/package/my-cli
  
  # 已归档项目
  - name: 旧版博客
    description: 基于 Hexo 的旧版博客系统，已迁移至 VitePress。
    image: /images/projects/old-blog.png
    tags: [Hexo, JavaScript]
    status: archived
    featured: false
    links:
      github: https://github.com/username/old-blog
---

字段说明 ​

字段类型必需说明
namestring✅项目名称
descriptionstring✅项目描述
imagestring❌项目截图
tagsstring[]✅技术标签
statusstring❌状态：active(维护中) / archived(已归档)
featuredboolean❌是否为精选项目（默认 false）
linksobject❌相关链接
字段类型说明
demostring在线演示地址
githubstringGitHub 仓库地址
docsstring文档地址
npmstringNPM 包地址

功能特性 ​

  • 精选展示：精选项目以大卡片形式突出显示
  • 状态筛选：快速筛选维护中/已归档项目
  • 标签筛选：按技术标签过滤项目
  • 多链接支持：支持 Demo、GitHub、文档、NPM 等多种链接类型

进阶用法 ​

结合数据加载器 ​

布局支持与 VitePress 的数据加载器配合使用，动态加载文章列表：

ts
// docs/.vitepress/posts.data.ts
import { createContentLoader } from 'vitepress'

export default createContentLoader('posts/*.md', {
  transform(raw): Post[] {
    return raw
      .filter(page => !page.url.includes('draft'))
      .map(page => ({
        title: page.frontmatter.title,
        url: page.url,
        date: page.frontmatter.date,
        excerpt: page.frontmatter.description,
        tags: page.frontmatter.tags || [],
        author: page.frontmatter.author
      }))
      .sort((a, b) => +new Date(b.date) - +new Date(a.date))
  }
})

自定义布局样式 ​

如需自定义布局样式，可在主题样式文件中覆盖：

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

/* 博客列表卡片样式 */
.blog-list-layout .post-card {
  border-radius: 12px;
}

/* 关于页面头像 */
.about-layout .avatar {
  border-width: 4px;
}

/* 项目卡片 */
.projects-layout .project-card {
  transition: transform 0.3s ease;
}

注意事项 ​

  1. 布局类型必须正确：layout 值必须是 blog-list、about、links、projects 之一
  2. 图片路径：使用相对路径时，图片需放在 docs/public 目录下
  3. 可选配置：所有配置都是可选的，不提供时使用默认示例数据
  4. 深色模式：所有布局都支持深色模式，样式自动适配

常见问题 ​

如何在布局中添加自定义内容？ ​

所有布局都支持 slot="after" 插槽，可以在布局后添加自定义内容：

html
---
layout: blog-list
---

<MyCustomComponent />

<template #after>
  <div class="custom-section">
    自定义内容
  </div>
</template>

如何动态加载文章列表？ ​

使用 VitePress 的数据加载器自动扫描文章目录：

ts
// docs/.vitepress/posts.data.ts
import { createContentLoader } from 'vitepress'

export interface Post {
  title: string
  url: string
  date: string
  excerpt: string
  tags: string[]
  author?: string
  cover?: string
}

declare const data: Post[]
export { data }

export default createContentLoader('posts/*.md', {
  transform(raw): Post[] {
    return raw
      .filter(page => !page.url.includes('draft'))
      .map(page => ({
        title: page.frontmatter.title,
        url: page.url,
        date: page.frontmatter.date,
        excerpt: page.frontmatter.description || '',
        tags: page.frontmatter.tags || [],
        author: page.frontmatter.author,
        cover: page.frontmatter.cover
      }))
      .sort((a, b) => +new Date(b.date) - +new Date(a.date))
  }
})

然后在页面中导入数据：

html
---
layout: blog-list
---

<script setup>
import { data as posts } from './posts.data'
</script>

<!-- 将 posts 传递给布局组件 -->

布局和主题有什么区别？ ​

对比项布局 (Layout)主题 (Theme)
范围单个页面整个站点
配置方式frontmatter配置文件
影响内容页面结构全局样式、组件
可复用性高中

为什么布局不生效？ ​

常见原因：

  1. layout 值拼写错误：检查是否为 blog-list、about、links、projects
  2. frontmatter 格式错误：确保 YAML 格式正确，--- 分隔符完整
  3. 布局组件未注册：检查 docs/.vitepress/theme/index.ts 是否正确导入布局

开发自定义布局 ​

如果你想开发自己的布局组件，可以参考以下步骤：

1. 创建布局组件 ​

在 docs/.vitepress/theme/layouts/ 目录下创建 Vue 组件：

vue
<!-- docs/.vitepress/theme/layouts/MyLayout.vue -->
<script setup lang="ts">
import { computed } from 'vue'
import { useData } from 'vitepress'

const { frontmatter } = useData()
const config = computed(() => frontmatter.value)
</script>

<template>
  <div class="my-layout">
    <header class="header">
      <h1>{{ config.title }}</h1>
    </header>
    <main class="content">
      <slot />
    </main>
    <slot name="after" />
  </div>
</template>

<style scoped>
.my-layout {
  max-width: 800px;
  margin: 0 auto;
  padding: 2rem;
}
</style>

2. 注册布局组件 ​

在主题入口文件中注册：

ts
// docs/.vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import MyLayout from './layouts/MyLayout.vue'

export default {
  extends: DefaultTheme,
  Layout: MyLayout  // 或通过 extends 钩子注册
}

3. 使用布局 ​

在 Markdown 文件中使用：

yaml
---
layout: my-layout
title: 我的页面
---

相关资源 ​

贡献者

加载中...

想要成为贡献者？

在 CNB 上参与贡献

Copyright © 2016 - 2026 VitePress 学习指南