主题配置
本文档详细介绍了主题的所有配置项,您可以根据需要进行个性化定制。主题配置文件位于.vitepress/theme/assets/themeConfig.mjs
,通过修改此文件来自定义您的站点外观和功能。
目录
文档YAML扩展
可以在Markdown文档的frontmatter中使用以下YAML扩展选项来控制单个页面的显示效果:
yaml# 标题
title: 文档标题
# 标签
tags: [标签1, 标签2]
# 分类
categories: [分类1, 分类2]
# 发布时间
date: 2025-01-01
# 置顶
top: true
# 推荐
recommend: true
# 主色 (用于文章封面,不设置主色会根据文章封面图片自动计算封面主色)
mainColor: #6e78a2
# 封面图片
cover: /example/cover.jpg
# 参考资料 (用于文章底部参考资料) title 标题 url 链接
references:
- title: 参考资料标题
url: https://example.com/
# 描述
description: 文档描述
# 文章GPT
articleGPT: 文章GPT描述
# 折叠代码块 (默认折叠)
cbx: false
# 转载文章 (用于转载文章) title 标题 desc 描述 url 链接
reprint:
title: 转载文章
desc: 转载文章描述
url: https://example.com/
# 侧边栏 (默认显示)
aside: false
# 内边距 (默认显示)
padding: false
# pages页面的卡片背景
card: true
# 评论 (pages页面默认不显示)
comment: true
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
配置项 | 类型 | 描述 | 默认值 |
---|
title | String | 文档标题 | - |
tags | Array | 文章标签 | [] |
categories | Array | 文章分类 | [] |
date | String | 发布时间 | 当前时间 |
top | Boolean | 是否置顶文章 | false |
recommend | Boolean | 是否推荐文章 | false |
mainColor | String | 文章封面主色 | 自动计算 |
cover | String | 文章封面图片路径 | 随机封面 |
references | Array | 文章底部参考资料列表 | [] |
description | String | 文章描述 | - |
articleGPT | String | 文章GPT描述 | - |
cbx | Boolean | 是否默认折叠代码块 | true |
reprint | Object | 转载文章信息 | - |
aside | Boolean | 是否显示侧边栏 | true |
padding | Boolean | 是否显示内边距 | true |
card | Boolean | 是否使用卡片背景(pages页面) | false |
comment | Boolean | 是否显示评论(pages页面) | false |
站点信息
站点信息配置包含了网站的基本信息,如标题、描述、logo等。这些信息将在站点的各个位置显示。
jssiteMeta: {
// 站点标题
title: '呢喃Ninc',
// 站点描述
description: '以乐观为笔,绘就多彩生活。',
// 头像
avatar: '/images/cxLogo/avatar.jpg',
// 站点logo
logo: '/images/cxLogo/cxLogo.png',
// 站点地址
site: 'http://localhost:5173',
// 站点基础路径
base: '/',
// 语言
lang: 'zh-CN',
// 作者
author: {
name: '呢喃Ninc',
cover: '/images/cxLogo/cxLogo.png',
email: 'i@ninc.top',
link: 'javascript:void(0)'
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
配置项 | 类型 | 描述 | 示例 |
---|
title | String | 站点标题,将显示在浏览器标签页和站点多处位置 | '呢喃Ninc' |
description | String | 站点描述,用于SEO和站点介绍 | '以乐观为笔,绘就多彩生活。' |
avatar | String | 博主头像图片路径,显示在侧边栏等位置 | '/images/cxLogo/avatar.jpg' |
logo | String | 站点logo图片路径,显示在导航栏等位置 | '/images/cxLogo/cxLogo.png' |
site | String | 站点完整URL地址 | 'https://example.com' |
base | String | 站点基础路径,通常为'/',如果部署在子目录则需要设置 | '/' 或 '/blog/' |
lang | String | 站点语言设置,影响站点内部多语言显示 | 'zh-CN' |
author | Object | 作者信息对象 | - |
author.name | String | 作者名称 | '呢喃Ninc' |
author.cover | String | 作者头像/封面图片路径 | '/images/cxLogo/cxLogo.png' |
author.email | String | 作者邮箱地址 | 'example@example.com' |
author.link | String | 作者个人链接 | 'https://example.com' |
首页配置
首页配置主要涉及网站首页的顶部信息展示,包括标题、副标题、横幅和分类导航等。
jshomeTop: {
title: '以乐观为笔',
subtitle: '绘就多彩生活。',
link: 'zcxiao.cn',
banner: {
title: '绘就多彩生活。',
tip: '以乐观为笔',
image: '/images/cover/003405.jpeg',
link: '/'
},
category: [
{
name: '前端',
path: '/life',
shadow: 'var(--main-shadow-blue)',
icon: 'icon-img',
class: 'blue'
},
{
name: '技术',
path: '/tech',
shadow: 'var(--main-shadow-red)',
icon: 'icon-copy',
class: 'red'
},
{
name: '生活',
path: '/life',
shadow: 'var(--main-shadow-blue)',
icon: 'icon-by-line',
class: 'green'
}
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
主要配置项
配置项 | 类型 | 描述 | 示例 |
---|
title | String | 首页主标题 | '以乐观为笔' |
subtitle | String | 首页副标题 | '绘就多彩生活。' |
link | String | 首页链接文本 | 'zcxiao.cn' |
banner | Object | 首页横幅配置 | - |
category | Array | 首页分类导航配置 | - |
banner配置
配置项 | 类型 | 描述 | 示例 |
---|
title | String | 横幅标题 | '绘就多彩生活。' |
tip | String | 横幅提示文字 | '以乐观为笔' |
image | String | 横幅背景图片路径 | '/images/cover/003405.jpeg' |
link | String | 横幅点击跳转链接 | '/' |
category配置(数组项)
配置项 | 类型 | 描述 | 示例 |
---|
name | String | 分类名称 | '前端' |
path | String | 分类页面路径 | '/life' |
shadow | String | 分类卡片阴影样式 | 'var(--main-shadow-blue)' |
icon | String | 分类图标类名 | 'icon-img' |
class | String | 分类卡片样式类名 | 'blue' |
基础配置
以下是站点的基础配置项,这些配置影响站点的整体功能和显示:
js// 备案信息
icp: '萌ICP备00000号',
// 建站日期
since: '2022-12-28',
// 每页文章数据
postSize: 8,
1
2
3
4
5
6
配置项 | 类型 | 描述 | 示例 |
---|
icp | String | 网站备案号,显示在页脚 | '萌ICP备00000号' |
since | String | 站点建立日期,用于显示站点运行时间 | '2022-12-28' |
postSize | Number | 每页显示的文章数量 | 8 |
页面注入
页面注入配置允许您向站点页面的<head>
标签中添加各种元素,如脚本、样式表、图标等。
jsinject: {
// 头部
// https://vitepress.dev/zh/reference/site-config#head
header: [
// favicon
['link', { rel: 'icon', href: '/favicon.ico' }],
['link', { rel: 'stylesheet', href: 'https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css' }],
['meta', { name: 'referrer', content: 'no-referrer' }],
['script', { src: 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.0/jquery.min.js', defer: true }],
['script', { src: '//cdnjs.cloudflare.com/ajax/libs/lettering.js/0.6.1/jquery.lettering.min.js', defer: true }],
['script', { src: '/debugger.js', defer: true }],
// 51la
['script', { charset: 'UTF-8', id: 'LA_COLLECT', src: 'https://sdk.51.la/js-sdk-pro.min.js' }],
['script', { src: '/51la.js' }],
// HarmonyOS font
[
'link',
{
crossorigin: 'anonymous',
rel: 'stylesheet',
href: 'https://s1.hdslb.com/bfs/static/jinkela/long/font/regular.css'
}
],
// iconfont
[
'link',
{
crossorigin: 'anonymous',
rel: 'stylesheet',
href: 'https://cdn2.codesign.qq.com/icons/g5ZpEgx3z4VO6j2/latest/iconfont.css'
}
],
// Embed code
[
'link',
{
crossorigin: 'anonymous',
href: 'https://use.sevencdn.com/css2?family=Fira+Code:wght@300..700&display=swap',
rel: 'stylesheet'
}
]
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
inject.header
是一个数组,每个数组项都是一个定义要插入到页面 <head>
标签中的元素的数组。元素定义遵循以下格式:
js['标签名', { 属性1: '值1', 属性2: '值2', ... }, '内容(可选)']
1
常见的注入类型包括:
类型 | 描述 | 示例 |
---|
favicon | 网站图标 | ['link', { rel: 'icon', href: '/favicon.ico' }] |
样式表 | 外部CSS样式 | ['link', { rel: 'stylesheet', href: '路径' }] |
外部脚本 | JavaScript脚本 | ['script', { src: '路径', defer: true }] |
内联脚本 | 直接执行的脚本 | ['script', {}, 'console.log("Hello")'] |
元数据 | 页面元信息 | ['meta', { name: 'description', content: '描述' }] |
提示:您可以引用 VitePress 的 head 配置文档 获取更多详细信息。
导航菜单
导航菜单配置项用于设置站点顶部的导航栏和左侧的更多导航菜单。
顶部导航栏
配置站点顶部的主导航菜单:
jsnav: [
{
text: '文库',
items: [
{ text: '文章列表', link: '/pages/archives', icon: 'article' },
{ text: '全部分类', link: '/pages/categories', icon: 'folder' },
{ text: '全部标签', link: '/pages/tags', icon: 'hashtag' }
]
},
{
text: '专栏',
items: [
{ text: '技术分享', link: '/pages/categories/技术分享', icon: 'technical' },
{ text: '我的项目', link: '/pages/project', icon: 'code' },
{ text: '效率工具', link: '/pages/tools', icon: 'tools' }
]
},
// ... 更多导航项
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
导航配置项
配置项 | 类型 | 描述 | 示例 |
---|
text | String | 导航项文本 | '文库' |
link | String | 导航项链接(单项导航时使用) | '/pages/archives' |
items | Array | 下拉菜单项(多项导航时使用) | - |
下拉菜单项配置
配置项 | 类型 | 描述 | 示例 |
---|
text | String | 菜单项文本 | '文章列表' |
link | String | 菜单项链接 | '/pages/archives' |
icon | String | 菜单项图标 | 'article' |
左侧更多导航
配置左侧的更多导航菜单:
jsnavMore: [
{
name: '博客',
list: [
{
icon: '/images/cxLogo/avatar.jpg',
iconType: 'img',
name: '我的主页',
url: 'https://ninc.top',
target: '_blank'
},
{
icon: '/images/cxLogo/avatar.jpg',
iconType: 'img',
name: '博客',
url: 'https://blog.ninc.top',
target: '_blank'
}
]
},
// ... 更多导航组
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
导航组配置
配置项 | 类型 | 描述 | 示例 |
---|
name | String | 导航组名称 | '博客' |
list | Array | 导航项列表 | - |
导航项配置
配置项 | 类型 | 描述 | 示例 |
---|
name | String | 导航项名称 | '我的主页' |
url | String | 导航项链接 | 'https://ninc.top' |
icon | String | 导航项图标(路径或类名) | '/images/cxLogo/avatar.jpg' |
iconType | String | 图标类型('img'表示图片,'iconfont'表示图标字体) | 'img' |
target | String | 链接打开方式 | '_blank'(新窗口打开) |
页面布局
页面布局配置项用于控制站点的整体布局和显示效果。
封面配置
封面配置控制文章页面的封面图片显示方式:
jscover: {
// 是否开启双栏布局
twoColumns: true,
// 是否开启封面显示
showCover: {
// 是否开启封面显示 文章不设置cover封面会显示异常,可以设置下方默认封面
enable: true,
// 封面布局方式: left | right | both
coverLayout: 'both',
// 默认封面(随机展示)
defaultCover: [
'/images/cover/003405.jpeg',
'/images/cover/235950.jpeg',
'/images/cover/003655.jpeg',
// ... 更多封面图片
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
主要配置项
配置项 | 类型 | 描述 | 可选值/示例 |
---|
twoColumns | Boolean | 是否开启双栏布局 | true /false |
showCover | Object | 封面显示配置 | - |
showCover.enable | Boolean | 是否开启封面显示 | true /false |
showCover.coverLayout | String | 封面布局方式 | 'left'/'right'/'both' |
showCover.defaultCover | Array | 默认封面图片列表 | 图片路径数组 |
注意:如果文章没有设置封面图片,将随机使用defaultCover
中的图片作为封面。
页脚配置
页脚配置用于设置站点底部的显示内容,包括社交链接和站点地图。
jsfooter: {
// 社交链接(请确保为偶数个)
social: [
{
icon: 'email',
link: 'mailto:i@ninc.top'
},
{
icon: 'github',
link: 'https://www.github.com/zhChuXiao/'
},
// ... 更多社交链接
],
// sitemap
sitemap: [
{
text: '博客',
items: [
{ text: '近期文章', link: '/' },
{ text: '全部分类', link: '/pages/categories' },
{ text: '全部标签', link: '/pages/tags' },
{ text: '文章归档', link: '/pages/archives' }
]
},
// ... 更多站点地图项
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
社交链接配置
social
是一个数组,用于配置页脚显示的社交媒体链接。
注意:社交链接数量应为偶数,以保证页面布局美观。
站点地图配置
sitemap
是一个数组,用于配置页脚显示的站点地图链接组。
站点地图组配置
配置项 | 类型 | 描述 | 示例 |
---|
text | String | 站点地图组标题 | '博客' |
items | Array | 站点地图链接项 | - |
站点地图链接项配置
配置项 | 类型 | 描述 | 示例 |
---|
text | String | 链接项文本 | '近期文章' |
link | String | 链接项URL | '/' |
newTab | Boolean | 是否在新标签页打开(可选) | true |
评论系统
评论系统配置用于设置站点的评论功能,支持多种评论系统。
jscomment: {
enable: true,
// 评论系统选择
// artalk / twikoo
type: 'twikoo',
// artalk
// https://artalk.js.org/
artalk: {
site: '',
server: ''
},
// twikoo
// https://twikoo.js.org/
twikoo: {
// 必填,若不想使用 CDN,可以使用 pnpm add twikoo 安装并引入
// js: "https://mirrors.sustech.edu.cn/cdnjs/ajax/libs/twikoo/1.6.39/twikoo.all.min.js",
envId: 'http://121.37.175.207:40063/',
// 环境地域,默认为 ap-shanghai,腾讯云环境填 ap-shanghai 或 ap-guangzhou;Vercel 环境不填
region: 'ap-shanghai',
lang: 'zh-CN'
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
主要配置项
配置项 | 类型 | 描述 | 可选值/示例 |
---|
enable | Boolean | 是否启用评论系统 | true /false |
type | String | 使用的评论系统类型 | 'artalk' / 'twikoo' |
Artalk 评论系统配置
Artalk 是一个轻量的自托管评论系统。
Twikoo 评论系统配置
Twikoo 是一个简洁、安全的评论系统,支持云函数和 Vercel 部署。
侧边栏
侧边栏配置用于设置站点右侧边栏的显示内容,包括站点简介、微信二维码、欢迎信息、目录、标签、倒计时和站点数据等。
jsaside: {
// 站点简介
hello: {
enable: true,
text: '这里有关于<strong>开发</strong>相关的问题和看法,也会有一些<strong>奇技淫巧</strong>的分享,其中大部分内容会侧重于<strong>前端开发</strong>。希望你可以在这里找到对你有用的知识和教程。'
},
// 微信二维码
wechat: {
enable: true,
face: '/images/weixin.png',
back: '/images/weixin-qrcode.png'
},
// 欢迎
welcome: {
enable: true,
text1: '👋🏻 Hi,我是呢喃ninc,欢迎你!',
text2: '新的站点采用VitePress重新搭建',
text3: '正在逐步完善中。',
// 博主邮箱
email: 'i@ninc.top',
// 博主坐标
address: [120.146782, 35.982411]
},
// 目录
toc: {
enable: true
},
// 标签
tags: {
enable: true
},
// 倒计时
countDown: {
enable: true,
// 倒计时日期
data: {
name: '春节',
date: '2026-02-16'
}
},
// 站点数据
siteData: {
enable: true
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
站点简介配置
配置项 | 类型 | 描述 | 示例 |
---|
enable | Boolean | 是否启用站点简介 | true /false |
text | String | 站点简介内容(支持HTML标签) | '这里有关于开发相关的问题...' |
微信二维码配置
配置项 | 类型 | 描述 | 示例 |
---|
enable | Boolean | 是否启用微信二维码 | true /false |
face | String | 微信二维码正面图片路径 | '/images/weixin.png' |
back | String | 微信二维码背面图片路径(扫码图) | '/images/weixin-qrcode.png' |
欢迎信息配置
配置项 | 类型 | 描述 | 示例 |
---|
enable | Boolean | 是否启用欢迎信息 | true /false |
text1 | String | 欢迎信息第一行 | '👋🏻 Hi,我是呢喃ninc,欢迎你!' |
text2 | String | 欢迎信息第二行 | '新的站点采用VitePress重新搭建' |
text3 | String | 欢迎信息第三行 | '正在逐步完善中。' |
email | String | 博主邮箱 | 'example@example.com' |
address | Array | 博主坐标 [经度,纬度] | [120.146782, 35.982411] |
目录配置
配置项 | 类型 | 描述 | 示例 |
---|
enable | Boolean | 是否启用文章目录 | true /false |
标签配置
配置项 | 类型 | 描述 | 示例 |
---|
enable | Boolean | 是否启用标签云 | true /false |
倒计时配置
配置项 | 类型 | 描述 | 示例 |
---|
enable | Boolean | 是否启用倒计时 | true /false |
data.name | String | 倒计时事件名称 | '春节' |
data.date | String | 倒计时目标日期(YYYY-MM-DD格式) | '2026-02-16' |
站点数据配置
配置项 | 类型 | 描述 | 示例 |
---|
enable | Boolean | 是否启用站点数据统计 | true /false |
友情链接
友情链接配置用于设置站点的友情链接页面和留言板。
jsfriends: {
// 友链朋友圈
circleOfFriends: '',
// 动态友链
dynamicLink: {
server: '',
app_token: '',
table_id: ''
},
// 留言板
comments: {
// 留言板标题
title: '留言板',
// 留言板描述
author: '呢喃ninc',
cover: '/images/cover/003405.jpeg',
message: [
'✨「欢迎光临我的小天地!想聊什么都可以~你的快乐、迷茫、小秘密,我都会安静收好!」',
'📢 留言区权限开放:夸我、吐槽我、安利美食…(违法内容除外!)',
'📖 每一句留言都会成为这个角落的光。你的故事、灵感,或是一瞬的喜怒哀乐,我都在听。'
],
bottom: '以乐观为笔,绘就多彩生活'
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
友链朋友圈配置
动态友链配置
配置项 | 类型 | 描述 | 示例 |
---|
server | String | 动态友链服务器地址 | 'https://api.example.com' |
app_token | String | 应用令牌 | 'your_app_token' |
table_id | String | 表格ID | 'your_table_id' |
留言板配置
配置项 | 类型 | 描述 | 示例 |
---|
title | String | 留言板标题 | '留言板' |
author | String | 留言板作者 | '呢喃ninc' |
cover | String | 留言板封面图片路径 | '/images/cover/003405.jpeg' |
message | Array | 留言板提示消息(数组中的每个字符串为一段消息) | ['✨「欢迎光临我的小天地!...'] |
bottom | String | 留言板底部文字 | '以乐观为笔,绘就多彩生活' |
功能模块
功能模块配置用于设置站点的特殊功能,如音乐播放器、搜索功能、打赏功能等。
音乐播放器
音乐播放器配置用于设置站点的背景音乐播放器。
jsmusic: {
enable: true,
// url
url: 'http://121.37.175.207:19991/api',
// id
id: 483637943,
// netease / tencent / kugou
server: 'netease',
// playlist / album / song
type: 'playlist'
}
1
2
3
4
5
6
7
8
9
10
11
配置项 | 类型 | 描述 | 可选值/示例 |
---|
enable | Boolean | 是否启用音乐播放器 | true /false |
url | String | API接口地址 | 'http://example.com/api' |
id | Number | 音乐ID(歌单ID、专辑ID或歌曲ID) | 483637943 |
server | String | 音乐服务提供商 | 'netease'(网易云音乐)/ 'tencent'(腾讯音乐)/ 'kugou'(酷狗音乐) |
type | String | 音乐类型 | 'playlist'(歌单)/ 'album'(专辑)/ 'song'(单曲) |
搜索功能
搜索功能配置用于设置站点的搜索功能,基于 Algolia 搜索服务。
jssearch: {
enable: false,
appId: '00000000000000000000000000000000',
apiKey: '00000000000000000000000000000000'
}
1
2
3
4
5
配置项 | 类型 | 描述 | 示例 |
---|
enable | Boolean | 是否启用搜索功能 | true /false |
appId | String | Algolia 应用ID | 'your_app_id' |
apiKey | String | Algolia API密钥 | 'your_api_key' |
打赏功能
打赏功能配置用于设置站点的打赏功能。
jsrewardData: {
enable: true,
// 微信二维码
wechat: 'https://pic.efefee.cn/uploads/2024/04/07/66121049d1e80.webp',
// 支付宝二维码
alipay: 'https://pic.efefee.cn/uploads/2024/04/07/661206631d3b5.webp'
}
1
2
3
4
5
6
7
图片灯箱
图片灯箱配置用于设置站点的图片预览功能。
jsfancybox: {
enable: true,
js: 'https://mirrors.sustech.edu.cn/cdnjs/ajax/libs/fancyapps-ui/5.0.36/fancybox/fancybox.umd.min.js',
css: 'https://mirrors.sustech.edu.cn/cdnjs/ajax/libs/fancyapps-ui/5.0.36/fancybox/fancybox.min.css'
}
1
2
3
4
5
外链中转
外链中转配置用于设置站点的外部链接中转功能,提高安全性并跟踪访问统计。
jsjumpRedirect: {
enable: true,
// 排除类名
exclude: [
'cf-friends-link',
'upyun',
'icp',
'author',
'rss',
'cc',
'power',
'social-link',
'link-text',
'travellings',
'post-link',
'report',
'more-link',
'skills-item',
'right-menu-link',
'link-card'
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
配置项 | 类型 | 描述 | 示例 |
---|
enable | Boolean | 是否启用外链中转 | true /false |
exclude | Array | 排除的链接类名列表(这些类名的链接不会被中转) | ['cf-friends-link', 'upyun', ...] |
站点统计
站点统计配置用于设置站点的访问统计功能。
jstongji: {
'51la': ''
}
1
2
3
配置项 | 类型 | 描述 | 示例 |
---|
51la | String | 51.LA统计ID | 'your_51la_id' |
结语
以上是主题的所有配置项,您可以根据需要进行个性化定制。如有任何疑问或建议,请随时提出。