常用插件安装
自动管理frontmatter
npm install vitepress-plugin-setfrontmatter -D安装提示版本兼容问题时，可用该命令
npm install vitepress-plugin-setfrontmatter -D --force
在.vitepress/config.mjs文件中添加以下内容：
import VitePluginVitePressAutoFrontmatter from 'vitepress-plugin-setfrontmatter'
export default defineConfig({
vite: {
plugins: [
VitePluginVitePressAutoFrontmatter({
pattern: '**/*.md',
globOptions: { ignore: [""] }, //忽略的文件或目录
permalinkPrefix: 'pages', // 永久链接前缀，如设置为"/pages/"，生成的permalink为"/pages/xxxx",不设置不会生成
categories: true // 是否启用自动添加frontmatter.categories功能
})
]
}
})IMPORTANT
安装该插件是为实现Markdown文件自动创建permalink，再结合永久链接插件，实现自动配置永久链接。
详细配置项，可参考原链接：
永久链接
安装vitepress-plugin-permalink插件，该插件中Proxy方式可实现永久链接。
npm install vitepress-plugin-permalink -D安装提示版本兼容问题时，可用该命令
npm install vitepress-plugin-permalink -D --force
在.vitepress/config.mjs文件中添加以下内容：
import Permalink from "vitepress-plugin-permalink";
export default defineConfig({
//添加以下内容
vite: {
plugins: [Permalink(Proxy)],
},
});假设项目的目录结构如下：
.
├─ docs # 项目根目录
│ ├─ guide
│ │ └─ api.md在 Markdown文件的 frontmatter 中添加permalink内容：
---
#方式一：
permalink: /guide/xxxx
#方式二：
permalink: /xxxx
---该文件除了通过 文件路径 访问，也可以通过 permalink 访问，xxxx可自定义输入。 Markdown文件的访问链接不再局限于文件名和其上级目录名。
IMPORTANT
安装该插件是为实现自动读取Markdown文件的permalink，结合自动管理frontmatter插件实现自动配置永久链接。
参考链接：
自动生成侧边栏
npm install vitepress-sidebar -D安装提示版本兼容问题时，可用该命令
npm install vitepress-sidebar -D --force
先单独修改.vitepress/config.mjs文件中sidebar的内容，数值留空就行。
export default {
themeConfig: {
.....
// 修改
sidebar: [
{
text: '',
items: [
{ text: '', link: '' },
{ text: '', link: '' }
]
}
],
.....
}
};修改.vitepress/config.mjs文件的整体结构。
import { withSidebar } from 'vitepress-sidebar';
//存放原来结构下的设置
const vitePressOptions = {
title: "My Awesome Project",
description: "A VitePress Site",
themeConfig: {
.....
}
};
//存放Sidebar的自定义配置项
const vitePressSidebarOptions = {
// 遍历目录
documentRootPath: '/docs',
//分组是否展开,null或undefined:全部展开，false：所有分组展开。true：所有分组折叠
collapsed: false,
//菜单名称的第一个字母强制大写，true：大写
capitalizeFirst: false,
//控制台显示输出过程
debugPrint: true,
//显示h1内容作为标题，没有则为Unknown
useTitleFromFileHeading: true,
//根据文件中指定的Frontmatter中的键名如"name: 文章名称"显示菜单标题。
//如果name在Frontmatter中不存在,将使用默认的title作为后备。
//frontmatterTitleFieldName:'name' ,
//Frontmatter中title的值显示标题。
// 如果无法解析该值,则如果useTitleFromFileHeading选项为true,则从h1标签中获取该值,如果失败,则从文件名中获取该值。
useTitleFromFrontmatter: false,
//默认使用前缀分隔符(.),例如菜单将重命名为文件名:1.hello ->hello 1.1.hello -> 1.hello 1-1.hello -> hello
removePrefixAfterOrdering: true,
//配合removePrefixAfterOrdering，也可使用正则，
// 如2024-01-01-hello，'/[0-9]{4}-[0-9]{2}-[0-9]{2}-/g' 执行后为hello
prefixSeparator: '.',
//排除目录或文件在菜单中显示,['abc/', 'def.md', 'ghi/file-**']
excludeByGlobPattern: []
//如果定义值为exclude,放在frontmatter中为exclude: true的文档，则不会显示。
// excludeFilesByFrontmatterFieldName: 自定义名称
};
export default defineConfig(withSidebar(vitePressOptions, vitePressSidebarOptions));更多Sidebar配置项，参考源链接：
图片缩放
npm install medium-zoom安装提示版本兼容问题时，可用该命令
npm install medium-zoom --force
在.vitepress\theme\index.js中，引入插件。
import { onMounted, watch, nextTick } from 'vue'
import { useRoute } from 'vitepress'
import mediumZoom from 'medium-zoom'
export default {
extends: DefaultTheme,
//添加内容
setup() {
const route = useRoute()
const initZoom = () => {
// 为所有图片增加缩放功能
mediumZoom('.main img', { background: 'var(--vp-c-bg)' })
}
onMounted(() => {
initZoom()
})
watch(
() => route.path,
() => nextTick(() => initZoom())
)
},
}创建 .vitepress\theme\style\index.css 文件。
@import './var.css';在 .vitepress/theme/index.js 文件中引入index.css
import './style/index.css'在.vitepress\theme\style\var.css中加入样式。
/************************ 图片缩放 ************************/
.medium-zoom-overlay {
background-color: var(--vp-c-bg) !important;
z-index: 100;
}
.medium-zoom-overlay ~ img {
z-index: 101;
}
.medium-zoom--opened .medium-zoom-overlay {
opacity: 0.9 !important;
}
/************************ 图片缩放 ************************/参考链接：
Tab标签
npm i -D vitepress-plugin-tabs安装提示版本兼容问题时，可用该命令
npm i -D vitepress-plugin-tabs --force
在docs\.vitepress\config.mjs文件中加入以下内容。
import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
export default defineConfig({
markdown: {
config(md) {
md.use(tabsMarkdownPlugin)
},
},
})在docs\.vitepress\theme\index.js文件中加入以下内容。
import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
enhanceAppWithTabs(app)
},
}实际用例：
:::tabs
=== tab 页签标题 2
内容区域 1
=== tab 页签标题 1
内容区域 2
:::内容区域 1
参考链接：
时间线
提醒
修改了时间线的样式，视觉显示更明显。
npm install vitepress-markdown-timeline安装提示版本兼容问题时，可用该命令
npm install vitepress-markdown-timeline --force
在docs\.vitepress\config.mjs文件中加入以下内容。
import timeline from "vitepress-markdown-timeline"
export default {
// ...
markdown: {
// ...
config: (md) => {
md.use(timeline);
},
},
};在docs\.vitepress\theme\index.js文件中引入插件。
import "vitepress-markdown-timeline/dist/theme/index.css"在docs\.vitepress\theme\style\blur.css中加入新样式。
/************************* 时间线*************************/
.timeline-dot {
position: relative;
padding: 0 0 18px 24px;
color: var(--vp-custom-block-danger-text);
box-sizing: border-box;
}
.timeline-dot::before {
position: absolute;
left: 0;
top: 0;
content: "";
width: 16px;
height: 16px;
border-radius: 50%;
border: solid 4px #FF7242;
transform: translate(0, 18%);
}
.timeline-dot::after {
position: absolute;
left: 7px;
top: 19px;
content: "";
width: 2px;
height: calc(100% - 18px);
background-color: #49B1F5;
}
/************************* 时间线*************************/
参考原链接：
代码折叠
npm install vitepress-plugin-codeblocks-fold安装提示版本兼容问题时，可用该命令
npm install vitepress-plugin-codeblocks-fold --force
在docs\.vitepress\theme\index.js文件中引入以下内容。
import { useData, useRoute } from 'vitepress'
import codeblocksFold from 'vitepress-plugin-codeblocks-fold'
import 'vitepress-plugin-codeblocks-fold/style/index.css'
export default {
DefaultTheme,
setup() {
// 获取前言和路由
const { frontmatter } = useData();
const route = useRoute();
// 基础使用
codeblocksFold({ route, frontmatter });
// 可配置参数
// codeblocksFold({ route, frontmatter }, true, 400);
}
};其中配置项codeblocksFold() 接收三个参数：
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| vitepressObj | Object | 是 | - | 包含 route 和 frontmatter 属性的对象 |
| defaultAllFold | Boolean | 否 | true | 是否默认所有页面的代码块都设置成折叠状态 |
| height | Number | 否 | 400 | 代码块被折叠后的高度(px) |
可单独设置markdown文件，在frontmatter中添加cbf参数：
| 参数名 | 类型 | 可能值 | 描述 |
|---|---|---|---|
| cbf | Array | boolean | [1,2,3], true, false |
当在frontmatter中设置
cbf: [1,2,3]时，该数组含义为：
- 当
defaultAllFold设置为true（默认全部页面折叠）时，当前页面第 1、2、3 个代码块强制展开（不折叠）- 当
defaultAllFold设置为false（默认全部页面展开）时，当前页面第 1、2、3 个代码块强制折叠cbf 还有两个参数：
true和false
true表示当前页面所有代码块折叠false表示当前页面所有代码块展开
参考链接：