Skip to content

安装 ShokaX

This content is not available in your language yet.

在开始之前

本文档为 ShokaX 的 Hexo 版本,请确保你想要安装基于此系统的 ShokaX

为确保安装正常进行,你需要:

  • nodejs 18 或更高版本
  • 一个适合你的包管理器(我们建议使用 pnpm)

为节省文档编写时间,文档内均使用 pnpm 作为示例

使用 ShokaX 即食罐头

Terminal window
git clone https://github.com/theme-shoka-x/shokax-can --depth=1
cd shokax-can
pnpm install
hexo s # 如果报错更换为 pnpm dlx hexo s

现在一个 ShokaX 环境已经创建好了,通过即食罐头创建的环境无需进行配置,可直接使用,如果需要软链接请查看最后一章

全新环境安装

初始化 Hexo 环境

Terminal window
pnpm add hexo-cli -g
# cd your_path
hexo init
# 如果报错: pnpm dlx hexo init

此时,你已经创建了一个基于 yarn 包管理器的 hexo 环境 我们建议通过以下方法更换为 pnpm:

Terminal window
# 请自行删除对应文件夹内的 node_modules 和 yarn.lock
pnpm install

安装 ShokaX

使用包管理器安装 ShokaX

Terminal window
pnpm add hexo-theme-shokax
# 对于npm/yarn用户可跳过,pnpm用户必须执行:
node ./node_modules/hexo-theme-shokax/toolbox/hoistdep.mjs

使用 ShokaX-CLI 安装 ShokaX

Terminal window
pnpm add shokax-cli -g
SXC install shokaX

使用 git 安装 ShokaX

Terminal window
cd themes
git clone https://github.com/theme-shoka-x/hexo-theme-shokaX.git # 可替换为你自己的项目
# 将 clone 完的文件夹改名为 shokax,下文均使用此名称
cd shokax
node ./toolbox/compiler.mjs
# 耐心等待编译完成
cd ../..
hexo s # 或 pnpm dlx hexo s
# pnpm 用户必须运行,yarn/npm遇到依赖错误可运行:
node ./themes/shokax/toolbox/hoistdep.mjs
# 等待运行完成后,问题通常会解决

此时将theme修改shokax后就可以使用 ShokaX 了

前置配置

按照上文将_config.yml中的theme修改为shokax,并将_config.landscape.yml修改为_config.shokax.yml

必要配置

markdown 配置

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: "你知道得太多了"

停用代码高亮

停用默认代码高亮(小于等于6.3.0):

highlight:
enable: false
prismjs:
enable: false

停用默认代码高亮(大于等于7.0.0-rc1):

syntax_highlighter: false

推荐配置

文件压缩

ShokaX 默认压缩器推荐配置:

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 生成

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"

配置建议

为了方便操作,建议为本主题文件夹创建软链接。

终端命令
Windows CMDmklink /J .\themes\shokax .\node_modules\hexo-theme-shokax
Linux Bashcd ../themes && ln -s ../node_modules/hexo-theme-shokax shokax

此时可从themes/shokax访问本主题文件