安装 ShokaX

在开始之前

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

为确保安装正常进行，你需要：

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

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

使用 ShokaX 即食罐头

提示

本方法仅适用于 ShokaX 0.4.5+ 的全新环境，对于0.4.5以下请参考后文的 ShokaX-CLI 安装

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 环境

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

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

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

安装 ShokaX

使用包管理器安装 ShokaX

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

使用 ShokaX-CLI 安装 ShokaX

警告

根据 ShokaX 生命周期计划，ShokaX-CLI 已弃用，请勿在新项目中使用

pnpm add shokax-cli -g
SXC install shokaX

使用 git 安装 ShokaX

提示

通过 git 方式安装时，我们建议 Fork 一个 ShokaX 的 Github 仓库并从你的 fork 版本 clone，这会极大降低修改主题后升级的难度
同时，ShokaX 的 git 方式安装并不是为普通用户准备的，此流程比 npm 或即食罐头更复杂且可能出现其他错误 \

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 了

前置配置

警告

请注意：

• Windows 或 Mac OS 用户且不使用 CI 工作流部署的可无视本条
• Linux 用户请注意修改所有和 ShokaX 有关内容时使用 shokax，例如主题配置文件应当是_config.shokax.yml，主题应该是theme: shokax，如果需要在 github pages/netlify/vercel 等平台进行工作流部署，则也需要遵守本条

另外： 本段内容在 hexo 目录下的_config.yml中修改，向其中加入或修改为提供内容

按照上文将_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:

危险

minify.html自0.1.5起添加minifier选项，允许使用：

• html-minifier：更稳定
• minify-html：更快

但由于 minify-html#181 和 minify-html#170， minify-html 并不可靠，且大概率会产生错误的 html（例ShokaX#220 和 ShokaX#243） 无论如何，不建议在上述问题修复前使用minify-html

如果您正在使用 0.1.4 或更早版本或使用minify-html缩小器时页面渲染错误，将缩小器调整为html-minifier大概率能修复

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 CMD	mklink /J .\themes\shokax .\node_modules\hexo-theme-shokax
Linux Bash	cd ../themes && ln -s ../node_modules/hexo-theme-shokax shokax

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