一直显示?点击任意区域即可关闭

主题配置

本文档详细介绍了主题的所有配置项,您可以根据需要进行个性化定制。主题配置文件位于.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
配置项类型描述默认值
titleString文档标题-
tagsArray文章标签[]
categoriesArray文章分类[]
dateString发布时间当前时间
topBoolean是否置顶文章false
recommendBoolean是否推荐文章false
mainColorString文章封面主色自动计算
coverString文章封面图片路径随机封面
referencesArray文章底部参考资料列表[]
descriptionString文章描述-
articleGPTString文章GPT描述-
cbxBoolean是否默认折叠代码块true
reprintObject转载文章信息-
asideBoolean是否显示侧边栏true
paddingBoolean是否显示内边距true
cardBoolean是否使用卡片背景(pages页面)false
commentBoolean是否显示评论(pages页面)false

站点信息

站点信息配置包含了网站的基本信息,如标题、描述、logo等。这些信息将在站点的各个位置显示。

js
siteMeta: {
  // 站点标题
  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)'
  }
}
配置项类型描述示例
titleString站点标题,将显示在浏览器标签页和站点多处位置'呢喃Ninc'
descriptionString站点描述,用于SEO和站点介绍'以乐观为笔,绘就多彩生活。'
avatarString博主头像图片路径,显示在侧边栏等位置'/images/cxLogo/avatar.jpg'
logoString站点logo图片路径,显示在导航栏等位置'/images/cxLogo/cxLogo.png'
siteString站点完整URL地址'https://example.com'
baseString站点基础路径,通常为'/',如果部署在子目录则需要设置'/' 或 '/blog/'
langString站点语言设置,影响站点内部多语言显示'zh-CN'
authorObject作者信息对象-
author.nameString作者名称'呢喃Ninc'
author.coverString作者头像/封面图片路径'/images/cxLogo/cxLogo.png'
author.emailString作者邮箱地址'example@example.com'
author.linkString作者个人链接'https://example.com'

首页配置

首页配置主要涉及网站首页的顶部信息展示,包括标题、副标题、横幅和分类导航等。

js
homeTop: {
  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'
    }
  ]
}

主要配置项

配置项类型描述示例
titleString首页主标题'以乐观为笔'
subtitleString首页副标题'绘就多彩生活。'
linkString首页链接文本'zcxiao.cn'
bannerObject首页横幅配置-
categoryArray首页分类导航配置-

banner配置

配置项类型描述示例
titleString横幅标题'绘就多彩生活。'
tipString横幅提示文字'以乐观为笔'
imageString横幅背景图片路径'/images/cover/003405.jpeg'
linkString横幅点击跳转链接'/'

category配置(数组项)

配置项类型描述示例
nameString分类名称'前端'
pathString分类页面路径'/life'
shadowString分类卡片阴影样式'var(--main-shadow-blue)'
iconString分类图标类名'icon-img'
classString分类卡片样式类名'blue'

基础配置

以下是站点的基础配置项,这些配置影响站点的整体功能和显示:

js
// 备案信息
icp: '萌ICP备00000号',
// 建站日期
since: '2022-12-28',
// 每页文章数据
postSize: 8,
配置项类型描述示例
icpString网站备案号,显示在页脚'萌ICP备00000号'
sinceString站点建立日期,用于显示站点运行时间'2022-12-28'
postSizeNumber每页显示的文章数量8

页面注入

页面注入配置允许您向站点页面的<head>标签中添加各种元素,如脚本、样式表、图标等。

js
inject: {
  // 头部
  // 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'
      }
    ]
  ]
}

inject.header 是一个数组,每个数组项都是一个定义要插入到页面 <head> 标签中的元素的数组。元素定义遵循以下格式:

js
['标签名', { 属性1: '值1', 属性2: '值2', ... }, '内容(可选)']

常见的注入类型包括:

类型描述示例
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 配置文档 获取更多详细信息。

导航菜单

导航菜单配置项用于设置站点顶部的导航栏和左侧的更多导航菜单。

顶部导航栏

配置站点顶部的主导航菜单:

js
nav: [
  {
    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' }
    ]
  },
  // ... 更多导航项
]

导航配置项

配置项类型描述示例
textString导航项文本'文库'
linkString导航项链接(单项导航时使用)'/pages/archives'
itemsArray下拉菜单项(多项导航时使用)-

下拉菜单项配置

配置项类型描述示例
textString菜单项文本'文章列表'
linkString菜单项链接'/pages/archives'
iconString菜单项图标'article'

左侧更多导航

配置左侧的更多导航菜单:

js
navMore: [
  {
    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'
      }
    ]
  },
  // ... 更多导航组
]

导航组配置

配置项类型描述示例
nameString导航组名称'博客'
listArray导航项列表-

导航项配置

配置项类型描述示例
nameString导航项名称'我的主页'
urlString导航项链接'https://ninc.top'
iconString导航项图标(路径或类名)'/images/cxLogo/avatar.jpg'
iconTypeString图标类型('img'表示图片,'iconfont'表示图标字体)'img'
targetString链接打开方式'_blank'(新窗口打开)

页面布局

页面布局配置项用于控制站点的整体布局和显示效果。

封面配置

封面配置控制文章页面的封面图片显示方式:

js
cover: {
  // 是否开启双栏布局
  twoColumns: true,
  // 是否开启封面显示
  showCover: {
    // 是否开启封面显示 文章不设置cover封面会显示异常,可以设置下方默认封面
    enable: true,
    // 封面布局方式: left | right | both
    coverLayout: 'both',
    // 默认封面(随机展示)
    defaultCover: [
      '/images/cover/003405.jpeg',
      '/images/cover/235950.jpeg',
      '/images/cover/003655.jpeg',
      // ... 更多封面图片
    ]
  }
}

主要配置项

配置项类型描述可选值/示例
twoColumnsBoolean是否开启双栏布局true/false
showCoverObject封面显示配置-
showCover.enableBoolean是否开启封面显示true/false
showCover.coverLayoutString封面布局方式'left'/'right'/'both'
showCover.defaultCoverArray默认封面图片列表图片路径数组

注意:如果文章没有设置封面图片,将随机使用defaultCover中的图片作为封面。

页脚配置

页脚配置用于设置站点底部的显示内容,包括社交链接和站点地图。

js
footer: {
  // 社交链接(请确保为偶数个)
  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' }
      ]
    },
    // ... 更多站点地图项
  ]
}

社交链接配置

social 是一个数组,用于配置页脚显示的社交媒体链接。

配置项类型描述示例
iconString社交媒体图标名称'email', 'github', 'twitter-x'
linkString社交媒体链接'mailto:example@example.com'

注意:社交链接数量应为偶数,以保证页面布局美观。

站点地图配置

sitemap 是一个数组,用于配置页脚显示的站点地图链接组。

站点地图组配置

配置项类型描述示例
textString站点地图组标题'博客'
itemsArray站点地图链接项-

站点地图链接项配置

配置项类型描述示例
textString链接项文本'近期文章'
linkString链接项URL'/'
newTabBoolean是否在新标签页打开(可选)true

评论系统

评论系统配置用于设置站点的评论功能,支持多种评论系统。

js
comment: {
  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'
  }
}

主要配置项

配置项类型描述可选值/示例
enableBoolean是否启用评论系统true/false
typeString使用的评论系统类型'artalk' / 'twikoo'

Artalk 评论系统配置

Artalk 是一个轻量的自托管评论系统。

配置项类型描述示例
siteString站点名称'My Blog'
serverStringArtalk 服务端地址'https://artalk.example.com'

Twikoo 评论系统配置

Twikoo 是一个简洁、安全的评论系统,支持云函数和 Vercel 部署。

配置项类型描述示例
jsStringTwikoo JS CDN 地址(可选)'https://cdn.jsdelivr.net/npm/twikoo@1.6.8/dist/twikoo.all.min.js'
envIdString环境 ID,腾讯云环境填写环境 ID,Vercel 环境填写网址'https://twikoo.example.com/'
regionString环境地域,腾讯云环境填写地域,Vercel 环境可不填'ap-shanghai'
langString评论系统语言'zh-CN'

侧边栏

侧边栏配置用于设置站点右侧边栏的显示内容,包括站点简介、微信二维码、欢迎信息、目录、标签、倒计时和站点数据等。

js
aside: {
  // 站点简介
  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
  }
}

站点简介配置

配置项类型描述示例
enableBoolean是否启用站点简介true/false
textString站点简介内容(支持HTML标签)'这里有关于开发相关的问题...'

微信二维码配置

配置项类型描述示例
enableBoolean是否启用微信二维码true/false
faceString微信二维码正面图片路径'/images/weixin.png'
backString微信二维码背面图片路径(扫码图)'/images/weixin-qrcode.png'

欢迎信息配置

配置项类型描述示例
enableBoolean是否启用欢迎信息true/false
text1String欢迎信息第一行'👋🏻 Hi,我是呢喃ninc,欢迎你!'
text2String欢迎信息第二行'新的站点采用VitePress重新搭建'
text3String欢迎信息第三行'正在逐步完善中。'
emailString博主邮箱'example@example.com'
addressArray博主坐标 [经度,纬度][120.146782, 35.982411]

目录配置

配置项类型描述示例
enableBoolean是否启用文章目录true/false

标签配置

配置项类型描述示例
enableBoolean是否启用标签云true/false

倒计时配置

配置项类型描述示例
enableBoolean是否启用倒计时true/false
data.nameString倒计时事件名称'春节'
data.dateString倒计时目标日期(YYYY-MM-DD格式)'2026-02-16'

站点数据配置

配置项类型描述示例
enableBoolean是否启用站点数据统计true/false

友情链接

友情链接配置用于设置站点的友情链接页面和留言板。

js
friends: {
  // 友链朋友圈
  circleOfFriends: '',
  // 动态友链
  dynamicLink: {
    server: '',
    app_token: '',
    table_id: ''
  },
  // 留言板
  comments: {
    // 留言板标题
    title: '留言板',
    // 留言板描述
    author: '呢喃ninc',
    cover: '/images/cover/003405.jpeg',
    message: [
      '✨「欢迎光临我的小天地!想聊什么都可以~你的快乐、迷茫、小秘密,我都会安静收好!」',
      '📢 留言区权限开放:夸我、吐槽我、安利美食…(违法内容除外!)',
      '📖 每一句留言都会成为这个角落的光。你的故事、灵感,或是一瞬的喜怒哀乐,我都在听。'
    ],
    bottom: '以乐观为笔,绘就多彩生活'
  }
}

友链朋友圈配置

配置项类型描述示例
circleOfFriendsString友链朋友圈地址'https://friends.example.com'

动态友链配置

配置项类型描述示例
serverString动态友链服务器地址'https://api.example.com'
app_tokenString应用令牌'your_app_token'
table_idString表格ID'your_table_id'

留言板配置

配置项类型描述示例
titleString留言板标题'留言板'
authorString留言板作者'呢喃ninc'
coverString留言板封面图片路径'/images/cover/003405.jpeg'
messageArray留言板提示消息(数组中的每个字符串为一段消息)['✨「欢迎光临我的小天地!...']
bottomString留言板底部文字'以乐观为笔,绘就多彩生活'

功能模块

功能模块配置用于设置站点的特殊功能,如音乐播放器、搜索功能、打赏功能等。

音乐播放器

音乐播放器配置用于设置站点的背景音乐播放器。

js
music: {
  enable: true,
  // url
  url: 'http://121.37.175.207:19991/api',
  // id
  id: 483637943,
  // netease / tencent / kugou
  server: 'netease',
  // playlist / album / song
  type: 'playlist'
}
配置项类型描述可选值/示例
enableBoolean是否启用音乐播放器true/false
urlStringAPI接口地址'http://example.com/api'
idNumber音乐ID(歌单ID、专辑ID或歌曲ID)483637943
serverString音乐服务提供商'netease'(网易云音乐)/ 'tencent'(腾讯音乐)/ 'kugou'(酷狗音乐)
typeString音乐类型'playlist'(歌单)/ 'album'(专辑)/ 'song'(单曲)

搜索功能

搜索功能配置用于设置站点的搜索功能,基于 Algolia 搜索服务。

js
search: {
  enable: false,
  appId: '00000000000000000000000000000000',
  apiKey: '00000000000000000000000000000000'
}
配置项类型描述示例
enableBoolean是否启用搜索功能true/false
appIdStringAlgolia 应用ID'your_app_id'
apiKeyStringAlgolia API密钥'your_api_key'

打赏功能

打赏功能配置用于设置站点的打赏功能。

js
rewardData: {
  enable: true,
  // 微信二维码
  wechat: 'https://pic.efefee.cn/uploads/2024/04/07/66121049d1e80.webp',
  // 支付宝二维码
  alipay: 'https://pic.efefee.cn/uploads/2024/04/07/661206631d3b5.webp'
}
配置项类型描述示例
enableBoolean是否启用打赏功能true/false
wechatString微信支付二维码图片地址'https://example.com/wechat.jpg'
alipayString支付宝支付二维码图片地址'https://example.com/alipay.jpg'

图片灯箱

图片灯箱配置用于设置站点的图片预览功能。

js
fancybox: {
  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'
}
配置项类型描述示例
enableBoolean是否启用图片灯箱true/false
jsString灯箱JS文件路径'https://cdn.jsdelivr.net/npm/@fancyapps/ui@5.0/dist/fancybox/fancybox.umd.js'
cssString灯箱CSS文件路径'https://cdn.jsdelivr.net/npm/@fancyapps/ui@5.0/dist/fancybox/fancybox.css'

外链中转

外链中转配置用于设置站点的外部链接中转功能,提高安全性并跟踪访问统计。

js
jumpRedirect: {
  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'
  ]
}
配置项类型描述示例
enableBoolean是否启用外链中转true/false
excludeArray排除的链接类名列表(这些类名的链接不会被中转)['cf-friends-link', 'upyun', ...]

站点统计

站点统计配置用于设置站点的访问统计功能。

js
tongji: {
  '51la': ''
}
配置项类型描述示例
51laString51.LA统计ID'your_51la_id'

结语

以上是主题的所有配置项,您可以根据需要进行个性化定制。如有任何疑问或建议,请随时提出。