# Hexo 主题

Hexo 框架搭建以后，就可以开始写博客了，不过初始站点的样式简陋，功能简单，而 Hexo 主题市场中的个性化主题可以提供更多的样式和功能。下面以这个博客采用的 Shoka 主题为例介绍 Hexo 框架中主题的相关配置。

Shoka 主题是参考笔记软件 Bear 和 Next 主题设计，具有丰富的样式和功能，相较于 Hexo 框架的默认语言引擎，支持更多的文章标签，还有分类精选、文章配图和多媒体播放等功能。

# 主题安装

在博客根目录下打开 Git Bash Here 控制台，输入下面的 git 克隆命令安装 Shoka主题 ：

git clone https://github.com/amehime/hexo-theme-shoka.git ./themes/shoka

安装完成后，打开博客目录的 themes 文件夹，已经有了 shoka 主题文件夹，这个文件夹下存放着主题的配置文件和样式资源等。

# 语言引擎

在配置之前，还需要卸载 Hexo 框架默认的 Markdown 语言引擎，并安装 shoka 主题使用的 markdown-it 语言引擎。

卸载默认语言引擎：

npm un hexo-renderer-marked --save

安装 markdown-it 引擎：

npm i hexo-renderer-multi-markdown-it --save --ignore-scripts

命令末尾的 --ignore-scripts 命令参数是为了跳过下载语言引擎 puppeteer 组件中的 Chromium内核 ，避免国内网络的原因无法下载内核导致引擎下载失败的情况，没有内核仅会影响到 mermaid流程图 标签无法使用，有网络条件的可以去掉该参数再开始下载。

# 插件下载

插件是 Hexo 框架丰富网站样式和功能的主要途径，可以按需下载，以下是 Shoka 主题主要功能涉及到的几个插件。

# Autoprefixer

该插件必须安装，功能是给生成的 css 文件添加浏览器前缀，不安装会影响到首页卡片翻转功能在部分浏览器上的显示效果。

npm i hexo-autoprefixer --save

# Algoliasearch

Algolia 插件提供内容搜索功能，非必需插件，不安装会导致搜索按钮失灵，安装后还需要相关配置才能使用搜索功能。

npm i hexo-algoliasearch --save

# Symbols-count-time

Symbols 插件可以统计站点的文本字数和阅读时间，非必需插件，不过建议安装。

npm i hexo-symbols-count-time --save

# Feed

Feed 插件可以优化搜索 SEO，非必需插件，不安装则不会生成 Feed 文件。

npm i hexo-feed --save

# 主题配置

在博客文件夹和 Shoka 主题文件夹下，可以看到均有一个名称为 _config.yml 的文件。博客根目录下的 config 文件是站点全局配置文件，包含站点的基础信息、主题选择和插件控制等配置，而主题文件夹下的 config 文件则是主题样式和功能控制的配置文件。

另外，建议在博客根目录下创建命名为 _config.shoka.yml 的主题配置文件，在这个文件中修改和保存自定义的主题配置，因为主题升级时，需要拉取新的主题配置文件，会覆盖原有修改过的主题配置文件，而渲染时博客根目录下的 _config.shoka.yml 文件中的主题配置优先于原有的主题配置文件，所以更新主题后仍可保留自定义配置。

# 全局配置文件调整

以下配置项都是在博客根目录下的 config 全局配置文件中修改或者添加。

# 主题启用

找到 theme 配置项，初始站点的默认主题为 landscape ，修改为 shoka 即表示启用 shoka 主题，其他主题的启用类似。

theme: shoka

# 引擎配置

添加 markdown 属性，配置 markdown-it 渲染引擎，以下的配置内容直接复制即可，无需修改。

	markdown:
	render: # 渲染器设置
	html: false # 过滤 HTML 标签
	xhtmlOut: true # 使用 '/' 来闭合单标签（比如 <br />）。
	breaks: true # 转换段落里的 '\n' 到 <br>。
	linkify: true # 将类似 URL 的文本自动转换为链接。
	typographer:
	quotes: '“”‘’'
	plugins: # markdown-it 插件设置
	- plugin:
	name: markdown-it-toc-and-anchor
	enable: true
	options: # 文章目录以及锚点应用的 class 名称，shoka 主题必须设置成这样
	tocClassName: 'toc'
	anchorClassName: 'anchor'
	- plugin:
	name: markdown-it-multimd-table
	enable: true
	options:
	multiline: true
	rowspan: true
	headerless: true
	- plugin:
	name: ./markdown-it-furigana
	enable: true
	options:
	fallbackParens: "()"
	- plugin:
	name: ./markdown-it-spoiler
	enable: true
	options:
	title: "你知道得太多了"

# 文章分类卡片

目录 博客根目录\source\_post 下存放着文章的源文件，而该目录下的文件夹及其子目录均可视为不同的文章分类。这些分类若要在首页以卡片形式显示，在对应目录下放一张命名为 cover.jpg 的封面图即可，父目录与其子目录均配置封面图的情况下，首页会分成两张卡片显示。配置为同一分类下的文章会现在是在 TOC目录 的 系列文章 中，按照发布时间和文章名称正序排列。

分类卡片默认以文件夹名称为分类名，英文名称的文件夹想要显示中文分类名，可以在全局配置文件的 category_map 项配置分类映射，格式为 分类名称: 文件夹名称 。

	category_map:
	个人博客: blog

# 文件压缩

添加 minify 配置，用于压缩站内文件，优化网页的渲染速度，内容复制即可。

	minify:
	html:
	enable: true
	exclude: # 排除 hexo-feed 用到的模板文件
	- '**/json.ejs'
	- '**/atom.ejs'
	- '**/rss.ejs'
	css:
	enable: true
	exclude:
	- '*/.min.css'
	js:
	enable: true
	mangle:
	toplevel: true
	output:
	compress:
	exclude:
	- '*/.min.js'

# 代码高亮

Shoka 主题 Mac 样式的代码高亮功能，不过需要先停用默认的代码高亮插件才能正常显示，将 highlight 项和 prismjs 项配置为 false 即可。

	highlight:
	enable: false

	prismjs:
	enable: false

# Autoprefixer 插件

添加 autoprefixer 配置，复制即可。

	autoprefixer:
	exclude:
	- '*.min.css'

# Algolia 插件

添加 algolia 配置。此项主题默认添加 # 注释掉了，自行注册 Algolia {} 账号进行配置后可以启用。

	# algolia:
	# appId:
	# apiKey:
	# adminApiKey:
	# chunkSize: 5000
	# indexName:
	# fields:
	# - title #必须配置
	# - path #必须配置
	# - categories #推荐配置
	# - content:strip:truncate,0,4000
	# - gallery
	# - photos
	# - tags

# Feed 插件

添加 feed 配置，用于生成 feed 文件，内容复制即可。

	feed:
	limit: 20
	order_by: "-date"
	tag_dir: false
	category_dir: false
	rss:
	enable: true
	template: "themes/shoka/layout/_alternate/rss.ejs"
	output: "rss.xml"
	atom:
	enable: true
	template: "themes/shoka/layout/_alternate/atom.ejs"
	output: "atom.xml"
	jsonFeed:
	enable: true
	template: "themes/shoka/layout/_alternate/json.ejs"
	output: "feed.json"

# 主题配置文件调整

下列配置均在主题配置文件（主题文件夹下或博客根目录下的_config.shoka.yml 文件）中修改或添加，涉及的配置项在原主题配置文件中都有配置，因此可以先复制到 _config.shoka.yml 文件后再修改。

# 站点别称

alternate 项的配置会替换站点页面顶部和底部版权标识 © 处的 Logo 文本。

alternate: YU NIAN

# 过渡动画

start 项控制页面加载时的动画， switch 项则控制页面切换时的过渡动画。 true 表示开启动画， false 则是关闭动画。

	loader:
	start: false # When entering the page
	switch: false # When switching to another page

# 自动定位

开启后在打开页面时或者刷新后，自动定位到上次浏览的位置。 true 表示开启定位功能，配置为 false 将停用该功能。

auto_scroll: true

# 烟花效果

将 enable 项配置为 true 表示启用烟花效果，配置为 false 时关闭效果。启用后在鼠标点击页面时会有烟花绽放的效果，后面的 color 项调整 RGBA 的值可以控制烟花的颜色。

	fireworks:
	enable: true # 是否启用
	color: # 烟花颜色
	- "rgba(255,182,185,.9)"
	- "rgba(250,227,217,.9)"
	- "rgba(187,222,214,.9)"
	- "rgba(138,198,209,.9)"

# 菜单与社交

menu 项配置的是页面顶部的导航菜单， social 项则可以配置侧边栏中简介上其他平台的跳转链接和图标样式。

各项的配置格式为 链接或路径 || 图标 || 颜色值 ，其中 链接或路径 和 图标 为必填项，颜色值不填表示默认颜色值， || 仅作为分隔符，前后均有一个空格。

在填写路径时，博客根目录下的 public 目录即是资源文件对应的起始路径， / 表示的即是 public 目录，子目录与其对应，路径处也可以直接填入网址超链接。

图标列表可以在 博客根目录/themes/shoka/source/css/_iconfont.styl 文件中查阅，填入时只需主体名称，不用添加前缀，如图标配置的主体名称为 github ，而不是列表中的 ic i-github ，解析时会自动转换。

颜色码的配置是使用十六进制码，并且用英文双引号 "" 包括，十六进制的颜色码可以搜索查询。

另外菜单支持配置子目录，但每级子目录的第一项必须配置 default 项，用于指定子目录父级按钮的样式。按钮的显示文本可以在语言文件中修改或添加，与菜单配置项的按钮对应即可，语言文件在主题文件夹下的 language 目录下，中文语言包对应的文件名称是 zh-CN.yml 。

	menu:
	home: / \|\| home
	about: /about/ \|\| user
	posts:
	default: / \|\| feather
	archives: /archives/ \|\| list-alt
	categories: /categories/ \|\| th
	tags: /tags/ \|\| tags
	friends: /friends/ \|\| heart
	links: /links/ \|\| magic
	social:
	github: https://github.com/yourname \|\| github \|\| "#191717"
	#google: https://plus.google.com/yourname \|\| google
	#twitter: https://twitter.com/yourname \|\| twitter \|\| "#00aff0"
	#zhihu: https://www.zhihu.com/people/yourname \|\| zhihu \|\| "#1e88e5"
	#music: https://music.163.com/#/user/home?id=yourid \|\| cloud-music \|\| "#e60026"
	#weibo: https://weibo.com/yourname \|\| weibo \|\| "#ea716e"
	#about: https://about.me/yourname \|\| address-card \|\| "#3b5998"
	#email: mailto:yourname@mail.com \|\| envelope \|\| "#55acd5"
	#facebook: https://www.facebook.com/yourname \|\| facebook
	#stackoverflow: https://stackoverflow.com/yourname \|\| stack-overflow
	#youtube: https://youtube.com/yourname \|\| youtube
	#instagram: https://instagram.com/yourname \|\| instagram
	#skype: skype:yourname?call\|chat \|\| skype
	#douban: https://www.douban.com/people/yourname/ \|\| douban

# 侧边栏

侧边栏指个人头像、简介以及社交平台等信息显示的区域， sidebar 配置控制的是侧边栏的显示位置及个人头像。 position 项控制侧边栏展示在页面左侧或右侧； avatar 项配置个人头像图片，本地头像图片需要直接放在 博客根目录/source/_data/images/ 路径下，不能使用相对路径，也可以配置为在线图片的链接。

	sidebar:
	# Sidebar Position.
	position: left
	#position: right
	# Replace the default avatar image and set the url here.
	avatar: avatar.jpg

# 随机文章和最近评论

页面底部可以增加显示随机文章和最近的评论，配置 true 时开启， false 为关闭。

	widgets:
	random_posts: true # 显示随机文章
	recent_comments: true # 显示最近评论

# 字数和阅读时间统计

前面安装了 hexo-symbols-count-time 插件并完成配置后，文章顶部配图处显示文章字数及阅读时长等，底部也将显示全站的统计数据，如站点运行时间、全站总字数、总阅读时长等信息。

	# 页尾全站统计
	footer:
	since: 2023
	count: true
	# 文章界面统计
	post:
	count: true

# Valine 文章评论

主题使用了 Hexo 内置的 MiniValine 文章评论系统，配置前需要获取 appId 和 appKey ，参考 Valine 教程完成注册以及应用创建等即可。

评论者名称后的标签的名称 tagMeta 、颜色 tagColor 和成员 tagMember 等均可以配置，未配置在成员中的用户则默认角色为访客 visitor 。访客角色的英文名必须为 visitor 无法调整，其他角色标签的英文名与中文名均支持更换，注意每个角色的属性一一对应。

	valine:
	appId: #Your_appId
	appKey: #Your_appkey
	placeholder: ヽ(○´∀`)ﾉ♪ # Comment box placeholder
	avatar: mp # Gravatar style : mp, identicon, monsterid, wavatar, robohash, retro
	pageSize: 10 # Pagination size
	lang: zh-CN
	visitor: true # 文章访问量统计
	NoRecordIP: false # 不记录 IP
	serverURLs: # When the custom domain name is enabled, fill it in here (it will be detected automatically by default, no need to fill in)
	powerMode: true # 默认打开评论框输入特效
	tagMeta:
	visitor: 新朋友
	master: 盟主
	friend: 小伙伴
	investor: 大老板
	tagColor:
	master: "var(--color-orange)"
	friend: "var(--color-aqua)"
	investor: "var(--color-pink)"
	tagMember:
	master:
	# - hash of master@email.com
	# - hash of master2@email.com
	friend:
	# - hash of friend@email.com
	# - hash of friend2@email.com
	investor:
	# - hash of investor1@email.com

# 其他配置

# Logo、打赏等图片替换

在路径 博客根目录\themes\shoka\source\images\ 下存放着站点 Logo 图片及打赏的二维码等，而除了头像图片可以修改名称外，列表中其他图片的命名最好不要修改，替换时将其他图片对应修改为主题图片的名称放入该目录下覆盖原图即可。

若是修改了个人头像图片名称，侧边栏的默认配置中也要修改，两边要保持一致。而带 ``ico 及 svg` 后缀的图片替换时，最好将替换的图片转换为对应格式再覆盖原图，因为重命名时修改后缀并不能转换为这两种图片格式。

图片名称	用途
404.png	404 网页的贴图
algolia_log.svg	algolia 评论者的头像贴图
alipay.png	支付宝打赏二维码
apple-touch-icon.png	移动设备图标
avatar.jpg	个人头像
failure.ico	页面被切换后的 Logo 图标
favicon.ico	当前页面图标
logo.svg
paypal.png	Paypal 打赏二维码
play_disc.png	多媒体图标
play_needle.png	多媒体图标
search.png	搜索弹窗的贴图
wechatpay.png	微信打赏二维码

# 主题配色

主题的页面配色文件的路径为 博客根目录\themes\shoka\source\css\_colors.styl ，如要调整页面配色，可以在 博客根目录\source\_data 目录下新建 colors.styl 文件，将原来颜色文件的内容复制到新颜色文件下调整，避免自定义颜色在更新主题时被覆盖，调整时要注意原来的所有样式名称不能缺少，防止样式显示异常。

# 自定义样式

可以在 博客根目录\source\_data 目录下新建 custom.styl 文件，用于保存自定义的样式，自定义样式将优先于主题样式显示。

# 随机图库

站点顶部及文章卡片显示的图片是从图库文件的列表中随机抽取的，原图库文件的路径为 博客根目录/themes/shoka/_images.yml ，因为原图库使用的图库已经关闭，图片无法正常显示，所以需要在 博客根目录\source\_data\ 路径下新建一个 images.yml 文件，填入至少 6 张图片的链接地址，格式如下：

	- https://i.loli.net/2020/10/30/qAMYEFXxJcKRsiG.gif
	- https://i.loli.net/2020/10/30/rjdhcSgEN8COBPA.jpg
	- https://i.loli.net/2020/10/30/HKyzSd7NI3mlBpt.jpg
	- https://i.loli.net/2020/10/30/Y1CBXqgeokEs457.jpg
	- https://i.loli.net/2020/10/30/Z5W6r2BSoiThHG1.jpg
	- https://s2.loli.net/2024/11/23/ANpwmlVLDerqKfU.jpg

如果有图床 API 的话，也可以在 主题配置文件 中直接添加图床的访问接口：

image_server: "https://acg.xydwz.cn/api/api.php"

# 背景音乐

站点全局的背景音乐列表在 主题配置文件 中添加 audio 多媒体配置，支持网易云、虾米和 QQ 音乐的多个单曲或歌单，格式如下：

单列表

	audio:
	- https://music.163.com/song?id=1387098940
	- https://music.163.com/#/playlist?id=2088001742
	- https://www.xiami.com/collect/250830668
	- https://y.qq.com/n/yqq/playsquare/3535982902.html

还可以同时配置不同列表

多列表

	audio:
	- title: 列表1
	list:
	- https://music.163.com/#/playlist?id=2943811283
	- https://music.163.com/#/playlist?id=2297706586
	- title: 列表2
	list:
	- https://music.163.com/#/playlist?id=2031842656

	menu:
	home: / \|\| home
	about: /about/ \|\| user
	posts:
	default: / \|\| feather
	archives: /archives/ \|\| list-alt
	categories: /categories/ \|\| th
	tags: /tags/ \|\| tags
	friends: /friends/ \|\| heart
	links: /links/ \|\| magic
	social:
	github: https://github.com/yourname \|\| github \|\| "#191717"
	#google: https://plus.google.com/yourname \|\| google
	#twitter: https://twitter.com/yourname \|\| twitter \|\| "#00aff0"
	#zhihu: https://www.zhihu.com/people/yourname \|\| zhihu \|\| "#1e88e5"
	#music: https://music.163.com/#/user/home?id=yourid \|\| cloud-music \|\| "#e60026"
	#weibo: https://weibo.com/yourname \|\| weibo \|\| "#ea716e"
	#about: https://about.me/yourname \|\| address-card \|\| "#3b5998"
	#email: mailto:yourname@mail.com \|\| envelope \|\| "#55acd5"
	#facebook: https://www.facebook.com/yourname \|\| facebook
	#stackoverflow: https://stackoverflow.com/yourname \|\| stack-overflow
	#youtube: https://youtube.com/yourname \|\| youtube
	#instagram: https://instagram.com/yourname \|\| instagram
	#skype: skype:yourname?call\|chat \|\| skype
	#douban: https://www.douban.com/people/yourname/ \|\| douban