创建主题配置文件
主题目录下的 _config.yml
文件通常负责主题相关配置,我们强烈建议您使用代替的主题配置文件以防止自己的配置丢失。那么如何使用代替主题配置文件呢?
在博客根目录的 _config.yml
文件旁边新建一个文件: _config.volantis.yml
,这个文件中的配置信息优先级高于主题文件夹中的配置文件。
当您需要修改某项内容时,例如导航栏菜单,那么您需要在主题配置文件中找到相关内容,复制进自己创建的配置文件中:
navbar: |
小提示
使用「npm i hexo-theme-volantis
」方式安装的主题,主题配置文件在「blog/node_modules/hexo-theme-volantis/_config.yml
」
使用传统方式安装的主题,主题配置文件在「blog/themes/volantis/_config.yml
」
自定义主题外观
最大布局宽度
custom_css: |
网页所呈现的内容的最大宽度,即 body 和 sidebar 的宽度之和。
抗锯齿
custom_css: |
自定义光标样式
custom_css: |
导航栏样式
您可以设置导航栏的高度以及视觉特效,视觉特效目前可选的有:
- shadow:卡片阴影。
- floatable:当鼠标移动到容器内时,呈现出浮起来的效果。
- blur:背景模糊效果(毛玻璃),当浏览器不支持时显示为不透明。
custom_css: |
滚动条样式
custom_css: |
侧边栏样式
视觉特效参数同上,值得注意的是:卡片的 floatable
效果和 blur
效果相冲突。
custom_css: |
正文区域样式
视觉特效参数同上,值得注意的是:卡片的 floatable
效果和 blur
效果相冲突。您可以在 language: true
这里设置代码块显示语言名称。text_align
可以设置 h1/h2/h3/h4/p 的文字对齐方向。
custom_css: |
布局间距
您可以设置几种标题的布局间距 h2/h3/h4、段落间距 line、区块内部的段落间距 inline。
custom_css: |
自定义字体
您可以自定义正文和代码字体。
custom_css: |
自定义颜色
多彩配色方案查看所有相关配置
############################### Color Scheme ############################### > start |
自定义右键菜单
右键菜单
右键在菜单项上根据配置文件自行生成前端代码,所以统一了一个共用的菜单对象:
{id: '', name: '', icon: '', link: '', event: '', group: ''} |
同时为了响应不同状态下的右键行为,提出了内置组 (defaultGroup
)的概念,相应的对于右键默认提供的功能实现则定义为内置实现(defaultEvent
)。
{ |
具体来说,内置组对应右键行为,例如 inputBox
代表在输入框下右键行为;内置实现对应自定义右键默认提供的功能实现,例如 readMode
代表了阅读模式。
参数解释
rightmenus: |
右键菜单加载
菜单的具体加载由 order
控制,可供使用的内容为:plugins.[组名], menus.[组名], hr, music 这四大类。
右键菜单排序
菜单的排序由 order
字段的先后顺序和组内菜单项的先后顺序决定。
右键菜单类
菜单项共分为两大类:plugins
和 menus
,前者放置内置组及内置菜单,允许添加/修改组内菜单;后者为用户自建菜单类,允许添加/修改组及组内菜单。一般意义上 plugins 类的组为动态组,根据实际的右键状态进行显示;menus 类中内容由用户添加,菜单项默认显示。
右键菜单项
菜单项共六个字段:id
, name
, icon
, link
, event
, group
,具体作用如下:
- id: 唯一值
- name: 用于菜单名称显示
- icon: 用于菜单图标显示
- link: 跳转链接
- event: 事件,当输入内容不为内置事件时,作 JavaScript 代码执行
- group: 菜单项所处分组名称
note link/event 二选一,同时出现时仅处理 link。
内置功能
内置组
组名 | 描述 | 备注 |
---|---|---|
navigation | 导航组件,横向排列,共用一行,仅显示图标 | 原则上支持的数量不限 |
inputBox | 文本输入框相关组件 | 生效于 input/textarea |
seletctText | 文本选中类组件 | 生效于右键选中文本,text 为选中的文本 |
elementCheck | 链接判断组件 | 生效于链接处的右键行为,link 为链接地址 |
elementImage | 图片判断类组件 | 生效于图片类的右键行为,link 为链接地址 |
articlePage | 文章页面组件 | 生效于 post.article 页面 |
note 除 navigation 外的内置组,在显示时会隐藏含 link 属性的菜单项。
内置实现
事件名 | 描述 | 备注 |
---|---|---|
copyText | 复制文本 | 复制选中文本 |
copyLink | 复制链接地址 | 复制 a 或 image 下的链接至剪切板 |
copyPaste | 粘贴文本 | 需要用户批准相应权限,仅支持粘贴文本至输入框(暂不支持粘贴图片) |
copyAll | 全选文本 | 选中输入框内的文本内容 |
copyCut | 剪切文本 | 剪切输入框中选中的文本内容 |
copyImg | 复制图片 | 支持 Chrome 浏览器,复制图片资源至剪切板 |
printMode | 打印页面 | 一个调制过样式的打印功能 |
readMode | 阅读模式 | 一个简单的阅读模式功能 |
默认设置
iconPrefix
Fontawesome 图标前缀,音乐类组件使用,参考内容:fa-solid, fa-regular, fa-light, fa-thin, fa-duotone, fa-brands。
articleShowLink
在 articlePage 组显示时(文章页)时依旧显示含 link 属性的菜单项。
musicAlwaysShow
当设定全局音乐播放器时,是否一直显示音乐控制菜单。false:仅当音乐播放时启用。
回调方法
volantis.rightmenu.handle
在右键菜单打开时执行。
volantis.rightmenu.handle(callBack[,"callBackName", "setRequestAnimationFrame = true"])。
此外,你还可以在 volantis.mouseEvent
处获得 MouseEvent 信息。
配置文件
blog/_config.volantis.yml
### 自定义右键 新 |
高级玩法
可以利用 Custom Files 自定义文件 功能,实现自定义右键菜单脚本及菜单项控制。
- 一个在右键菜单中添加 查看上一篇、查看下一篇 菜单项的范例:
设置网站导航栏
导航栏配置
导航栏分为 logo、menu、search 三个区域设置,其中 logo 区域如果设置了图片,则不能显示图标和标题, menu 区域的设置可以写在一个单独的文件中。
############################### Navigation Bar ############################### > start |
菜单嵌套
导航栏菜单支持嵌套,嵌套的属性名为 rows
,写法示例:
... |
分割线
在子菜单中,新增一个只有 name: hr
的“菜单”就会被渲染成一个分割线。
- name: hr |
小标题
在子菜单中,新增一个只有 name: 小标题内容
(也可以有 icon: 小标题的图标
)的“菜单”就会被渲染成一个小标题。
... |
播放器
在子菜单中,新增一个 icon: fa-solid fa-compact-disc
的“菜单”就会被渲染成一个 APlayer 播放器。
- name: 背景音乐 |
设置网站页脚
您通过 layout
可以自由布局网站页脚内容 aplayer
, social
, license
, info
, copyright
。
site_footer: |
其中,aplayer
需要在插件部分设置中启用。您可以新增文字属性,用于展示其它文字信息,例如:
site_footer: |
网站与文章封面
封面高度
cover: |
目前主题提供两种首页封面高度方案,其它页面均为半屏幕高度。
封面布局方案
cover: |
布局方案 | 适合场景 |
---|---|
search | 注重搜索 |
dock | 入口选项比较多 |
featured | 选项在4个左右 |
focus | 选项在4个左右 |
默认显示设置
cover: |
由于主页、归档是 hexo 自动生成的,您需要在主题配置文件中设置是否显示封面,而其它页面则可以在 front-matter
中通过设置 cover: true/false
来决定显示封面或者不显示封面。
文章布局配置
查看所有相关配置
############################### Article Layout ############################### > start |
其中 top_meta
和 bottom_meta
部分的取值自 meta_library
库。
侧边栏配置
侧边栏小组件与 meta 库不同的是:除了现有的 widget ,您可以很轻易地创建自己的 widget ,然后放在需要的地方。此外,您还可以将 widget 写在单独的文件中。
查看所有相关配置
############################### Sidebar ############################### > start |
每一个小部件都有 class
和 display
,前者代表这个小部件是什么,后者代表这个小部件在什么桌面和移动平台中是否显示,如果在移动平台显示,由于屏幕宽度有限,侧边栏的小部件则会被移动到正文区域下方,因此部分侧边栏小部件便失去意义,建议设置为仅桌面端显示。
小部件名: |
博主信息部件
blogger: |
其中,今日诗词 jinrishici
如果设置为一个字符串,这个字符串会变成占位文字,加载失败时显示。如果不需要,就请设置为 jinrishici: false
。social
的具体内容请在网站页脚部分设置。
文章目录部件
toc: |
这个部件只能放置在侧边栏,并且在文章中有效。在移动设备中预览时,手指向上滑动时,导航栏右边会出现 TOC 按钮,点击即可展开 TOC 部件。如果您需要显示章节序号,请设置 list_number
。 min_depth
和 max_depth
代表 TOC 支持的标题层级,最大范围是2~6。
文章分类部件
category: |
这个部件可以直接显示所有文章分类,如果您希望有一个独立的页面来展示,需要自己创建一个文件,具体操作在「页面」部分文档中。
标签云部件
tagcloud: |
这个部件可以直接显示所有文章的标签,如果您希望有一个独立的页面来展示,需要自己创建一个文件,具体操作在「页面」部分文档中。
二维码部件
donate: |
您可以放置在文章页脚用于展示打赏图片,也可以放置在侧边栏。
通用文本部件
repos: |
您可以创建用于展示任何文本内容的文本部件。
通用列表部件
wiki-hexo-theme: |
您可以创建用于展示任何链接列表的列表部件。列表的 rows
中的每一项支持的属性有: name
、url
、icon
、img
、avatar
,其中 img
是方形图片的链接,avatar
是圆形图片的链接。
组索引
这个部件的布局继承自 list 部件,用于展示文章所属的分组的文章列表。请将您的 Volantis 升级至 2.5 版本以上使用。
group-1: |
在文章的 front-matter 中设置:
group: group-1 |
「group-1」卡片将会以列表的形式显示所有设置了 group: group-1
的文章,顺序按照 order
从小到大排列。
通用网格部件
feedback: |
您可以创建用于展示任何链接列表的网格部件。网格默认根据文字长度自动确定每一个格子的宽度,如果文字长短不一,建议通过设置 fixed: true
来固定宽度,此时文字过长的格子中的文字会换行显示。
通用页面部件
test: |
您可以把整个页面的md内容作为一个小部件渲染显示出来。只需要设置小部件里的 pid
属性和文章的 front-matter
中设置一样的 pid
即可。 content
代表这个部件显示的内容,可选 excerpt
,more
,content
分别对应文章的摘要、摘要后面的内容、全文。
音乐部件
music: |
选择评论系统
目前共支持 14 款评论系统:
artalk, giscus, beaudar, utterances, twikoo, waline, discuss, disqus, disqusjs, gitalk, vssue, livere, isso, hashover
comments: |
GitHub Discussions 系列
A comments system powered by GitHub Discussions.
https://giscus.app/
comments: |
GitHub Issues 系列
Beaudar 名称源于粤语“表达”的发音,是 Utterances 的中文版本。
https://beaudar.lipk.org/
comments: |
A lightweight comments widget built on GitHub issues.
https://utteranc.es/
comments: |
Vue 驱动的、基于 Issue 的评论插件
https://vssue.js.org/zh/
comments: |
A modern comment component based on Github Issue and Preact.
https://gitalk.github.io/
comments: |
clientID 和 clientSecret 的获取方法可自行搜索教程,这里仅简单描述一下步骤:
- 点击 GitHub -> Settings
https://github.com/settings/profile
- 点击 Developer settings
https://github.com/settings/developers
- 点击 New OAuth App
https://github.com/settings/applications/new
- 填写信息:
Application name 随便填,我的是:xaoxuu.com
Homepage URL 和 Authorization callback URL 都写你的网址,我的是:https://xaoxuu.com
可以通过设置 gitalk.id 实现多个页面共用一个评论框。
|
Disqus 系列
Disqus - The #1 way to build an audience on your website.
https://disqus.com/
comments: |
可以通过设置 disqus.path 实现多个页面共用一个评论框。
|
Render Disqus comments in Mainland China using Disqus API
https://github.com/SukkaW/DisqusJS
comments: |
A commenting server similar to Disqus.
https://posativ.org/isso/
comments: |
Valine 衍生系列
Valine 在 5.0 版本被移除,具体原因可参考hexo-theme-next#188#issuecomment-766578906
以下是在解决 valine 遗留问题同一时期产生的评论系统故归为一类, 然在其社区issue中也报告了类似的攻击事件(eg: twikoo#157 waline#424 waline#430),故请谨慎选择.
一款简单,安全,免费的评论系统 | A simple, safe, free comment system
https://discuss.js.org
comments: |
其中,placeholder
支持在 front-matter 中设置。
|
也可以通过设置 discuss.path
实现多个页面共用一个评论框。
|
一个简洁、安全、免费的静态网站评论系统 | A simple, safe, free comment system.
https://twikoo.js.org/
comments: |
其中,placeholder
支持在 front-matter 中设置。
|
也可以通过设置 twikoo.path
实现多个页面共用一个评论框。
|
一个简洁、安全、免费的静态网站评论系统 | A simple, safe, free comment system.
https://waline.js.org/
comments: |
其中,placeholder
支持在 front-matter 中设置。
|
也可以通过设置 waline.path
实现多个页面共用一个评论框。
|
Others 其他系列
一款简洁的自托管评论系统 | A Selfhosted Comment System.
https://artalk.js.org/
comments: |
其中,placeholder
支持在 front-matter 中设置。
|
也可以通过设置 artalk.path
实现多个页面共用一个评论框。
|
Communication makes better world.
https://www.livere.com/
comments: |
在这里查看你的 uid:https://livere.com/insight/myCode
,在【代码管理 -> 一般网站】中找到如下这段代码,其中 data-uid
中的内容就是你的 livere_uid
。
<!-- 来必力City版安装代码 --> |
A free and open source PHP comment system designed to allow completely anonymous comments and easy theming.
https://www.barkdull.org/software/hashover
comments: |
这里写布局代码 |
这里要写加载 js 的代码 |
可以通过在 front-matter 设置 config 实现在特定页面修改评论系统的相关配置。
支持的有(按字母顺序): discuss, giscus, gitalk, twikoo, waline
|
站内搜索
配置代码
# To use hexo search, you need to install the following plugins: |
- 你需要安装 hexo-generator-json-content,并根据它的文档去做相应配置。
- 修改 主题配置文件。
search: |
- 你需要安装 hexo-algoliasearch 或 hexo-algolia,根据它们的说明文档去做相应的配置。
- 修改 主题配置文件。
search: |
如果你使用 hexo-algoliasearch,请记得配置 fields 参数的 title, permalink 和 content:strip
- MeiliSearch 为自托管搜索引擎,需要服务器支撑,部署文档详见:Meilisearch Doc。
- 数据集需要自行上传,可使用 hexo-generator-json-content 生成索引,同时配置修改如下:
blog/_config.yml jsonContent:
meta: false
pages: false
posts:
title: true
path: true
text: true
uuid: true # <--- 做主键 - 你需要为文章分配一个唯一 ID 作为主键,此处推荐使用 hexo-uuid 生成。
- 修改 主题配置文件。
search: |
原 google, azure, baidu 站内搜索 系祖传代码, 且文档丢失, 不便后续维护 在 5.0 版本移除
插件库
概述
Volantis 为丰富的插件提供了兼容性优化。大部分插件您只需开启和关闭,无需进行设置。
幻灯片背景(视差滚动效果)
jquery.backstretch 在 5.0 版本 移除, 被 parallax 替代
plugins: |
幻灯片背景图片显示的位置可以选择粘贴在封面上,跟随封面一起滑动,也可以选择固定作为网页背景图片。
语法高亮
plugins: |
如果需要使用 highlight.js 进行语法高亮,请将站点配置文件中的 highlight.enable
设置为 false
否则不会加载插件。您可以在 94 种 语法高亮主题 中挑选喜爱的主题,然后替换上面的 css 链接。
如果您使用 highlight.js 请确保没有使用 hexo 官方的 codeblock 标签,否则会报错。
经测试,使用 highlight.js 的情况下,部分容器内的代码可能仍然会被渲染甚至报错。
APlayer 音乐播放器
plugins: |
暗黑模式
plugins: |
结束支持
plugins: |
Artitalk
plugins: |
BBtalk
plugins: |
Tidio
plugins: |
友链朋友圈
plugins: |
消息提示
plugins: |
轮播标签
使用方法参见:swiper
# swiper |