我是基于ChatGPT-turbo-3.5实现的AI助手,在此网站上负责整理和概括文章
本文记录了使用Hexo+ShokaX主题搭建个人博客的过程。首先介绍了准备工作,包括安装Node.js和包管理器pnpm。然后详细说明了Hexo的安装步骤以及ShokaX主题的安装和配置过程。最后,给出了基本配置的步骤,包括markdown配置、停用默认代码高亮、文件压缩和feed生成等。通过本文的指导,可以顺利搭建个人博客并进行初步配置。
本文记录了我的搭建过程,以及过程中我遇到的问题和解决方法,应该可以给同样想要搭建 shokax 主题博客的大家提供一定的参考。
以下均由博主自行摸索得来,其中如果有误,还请各位大佬指正。
博主半瓶水术语使用不专业,如若有疑问,欢迎留言咨询。
# 准备工作
# Node.js
根据官方文档中所述,ShokaX 主题需要 nodejs 18 以及更高的版本,因此需要提前准备好,避免到时候掉链子
如果你已经安装好 nodejs 的话,可以直接跳过去下一步
如果没有的话,这边推荐使用 nvm, 方便以后管理 nodejs 版本,有时候不同的项目要求的 nodejs 版本不同,来回切换真的很麻烦
通过 nvm 可以快速的切换 nodejs 版本,去 Github 下载最新版 nvm 安装程序
之后一直下一步就行了
装完之后 Win + R 打开命令提示符,输入
nvm version |
能看见版本号就说明安装好了
接下来就是安装 node 了
在命令提示符里面输入
nvm install 18.19.0 | |
#静静等待安装完成的提示 | |
#速度慢的话切换国内镜像,网上教程很多,我就不过多赘述了,毕竟这不是今天的主题 | |
nvm use 18.19.0 |
到此 nodejs 就算安装成功了
# 包管理器
pnpm
接下来安装包管理器,官方文档建议我们使用 pnpm,那我们就安装它
很简单,只需要在命令提示符里面输入
npm install -g pnpm@latest-10 |
# Hexo 安装
打开命令提示符,输入以下命令
pnpm add hexo-cli -g | |
#cd 你的博客目录 | |
hexo init | |
#静静等待命令执行完成 |
完成之后我们会得到如图所示的一堆文件
命令行执行 hexo s
,打开给出的那串地址,可以看到 hexo 已经安装成功了
# ShoaX 安装
下面我们 cd 到 themes
进行 ShokaX 主题的安装
cd themes | |
git clone https://github.com/theme-shoka-x/hexo-theme-shokaX.git | |
#这里可以替换成你自己的仓库,建议 fork 主题仓库,方便后续更新主题 | |
#clone 完成之后,把 hexo-theme-shokaX 重命名成 shokax | |
cd shokax | |
node ./toolbox/compiler.mjs |
这时候遇到报错了,先别急,仔细看看,貌似是缺少 esbuild
依赖包,我们把它装上
命令行执行 pnpm add esbuild
pnpm add esbuild |
等待安装完成之后再次执行刚刚报错的命令就能够顺利执行了
编译完成之后我们 cd 到 hexo 根目录,执行下面的命令
cd ../.. | |
node ./themes/shokax/toolbox/hoistdep.mjs |
等待运行完成之后,打开 hexo 根目录的 _config.yml
,把 theme: landscape
改成 theme: shokax
顺便再把 language: cn
改成 language: zh-CN
更换博客主语言
接着再次 hexo s 进行预览,看见下面这样的,就已经成功 90% 了
按 Ctrl + C 可以结束进程
# 基本配置
在此之前
记得把 hexo 根目录的 _config.landscape.yml
重命名为 _config.shokax.yml
这很重要,把主题配置独立出来,既方便管理,也能避免主题更新时配置被覆盖的问题
# markdown 配置
打开 hexo 根目录的 _config.yml
文件,把下面的配置加到最后面 注意缩进
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: "你知道得太多了" |
# 停用默认代码高亮
打开 hexo 根目录 package.json
,查看 hexo
的版本,停用内建代码高亮组件
shokax 自己的渲染器自带代码高亮
如果小于等于 6.3.0
,修改 _config.yml
highlight: | |
enable: false | |
prismjs: | |
enable: false |
如果大于等于 7.0.0-rc1
syntax_highlighter: false |
# 文件压缩
把下面的配置加到 _config.yml
末尾
minify: | |
js: | |
enable: false # ShokaX 自带 esbuild 优化,不建议开启,其他主题建议开启 | |
exclude: # 排除文件,接受 string [],需符合 micromatch 格式 | |
css: | |
enable: true # 开启 CSS 优化 | |
options: | |
targets: ">= 0.5%" # browserslist 格式的 target | |
exclude: # 排除文件,接受 string [],需符合 micromatch 格式 | |
html: | |
minifier: html-minifier | |
enable: true # 开启 HTML 优化 | |
options: | |
comments: false # 是否保留注释内容 | |
exclude: # 排除文件,接受 string [],需符合 micromatch 格式 | |
image: | |
enable: false # 开启图片预处理和自动 WebP 化 | |
options: | |
avif: false | |
webp: true # 预留配置项,现版本无作用 | |
quality: 80 # 质量,支持 1-100 的整数、lossless 或 nearLossless | |
effort: 2 # CPU 工作量,0-6 之间的整数 (越低越快) | |
replaceSrc: false # 自动替换生成 html 中的本地图片链接为 webp 链接 | |
# 对于使用 CI 工作流部署的用户,请注意本配置可能导致图片 404,如果出现请关闭 | |
# 我们更建议使用 Service Worker 来在用户侧实现 replaceSrc 的功能,这将能够以一种侵入式更小的方式实现链接替换 | |
exclude: |
# feed 生成
同样加到 _config.yml
末尾
feed: | |
limit: 20 | |
order_by: "-date" | |
tag_dir: false | |
category_dir: false | |
rss: | |
enable: true | |
template: "node_modules/hexo-theme-shokax/layout/_alternate/rss.ejs" | |
output: "rss.xml" | |
atom: | |
enable: true | |
template: "node_modules/hexo-theme-shokax/layout/_alternate/atom.ejs" | |
output: "atom.xml" | |
jsonFeed: | |
enable: true | |
template: "node_modules/hexo-theme-shokax/layout/_alternate/json.ejs" | |
output: "feed.json" |
# 其他问题
# hexo g/s 报错
- 解决办法:hexo 根目录执行
pnpm add hexo-theme-shokax
pnpm add hexo-theme-shokax |
# 文档不渲染 / 部分渲染
- 解决办法:更换 hexo 自带 md 渲染器为 shokax 的 md 渲染器,hexo 根目录执行
pnpm remove hexo-renderer-marked | |
pnpm add hexo-renderer-multi-next-markdown-it | |
hexo clean && hexo g | |
#如果问题仍然存在,系浏览器缓存问题,清除缓存之后再次尝试 |