Hexo - Shoka主题使用手册

AI 摘要

本文是 ShokaX 定制版 Hexo 主题的使用手册，只记录本站实际可用的写法和配置，并为每条语法附上渲染效果。全文分为三部分：Markdown 语法特性，涵盖基础语法、行内样式、内容容器、图片与卡片、代码、图表与公式、题目和 Hexo 标签；设置点，包括站点配置、文章 Front-matter 及读者侧的“显示与阅读”面板；本站扩展点，汇总主题之外新增的文章、页面、构建与资源功能，并链接到详细文章。

AI 生成 · 仅供参考

# 引言

Hexo 主题 Shoka 使用手册，用于个人使用查找。

本站目前运行的是 ShokaX 的定制分支，Markdown 由 hexo-renderer-aether 渲染。手册只记录当前站点实际可用的写法和配置，每条语法后面都直接附上渲染效果。

全文分三块：

Markdown 语法特性：写文章时能用哪些语法，长什么样。按用途分成基础语法、行内样式、内容容器、图片与卡片、代码、图表与公式、题目和 Hexo 标签。
设置点：站点配置、文章 Front-matter，以及读者侧的「显示与阅读」面板。
本站扩展点：在主题上额外加的功能，有单独文章的直接跳过去看。

# Markdown 语法特性

# 基础语法

常规的 CommonMark / GFM 写法都可以直接用，这里只列几个和默认行为不太一样的地方。

语法	写法	说明
标题	`## 标题`	自动生成锚点，并进入右侧目录
强调	`粗体`、`斜体`	—
删除线	`~~删除~~`	删除
行内代码	`code`	`code`
链接	`[文字](url)`	裸链接也会自动转换
图片	`![alt](url)`	自动懒加载，点击用查看器放大
引用	`> 引用`	—
分割线	`---`	—

站点开启了 breaks: true，段落内的单个换行会直接变成换行，不需要行尾加两个空格。想要一个新段落，还是空一行。

任务列表：

- [x] 写引言
- [ ] 写结语

写引言
写结语

表格支持对齐，也支持多行单元格、合并行和无表头表格：

| 左对齐 | 居中 | 右对齐 |
| :--- | :---: | ---: |
| A | B | C |

左对齐	居中	右对齐
A	B	C

正文里允许直接写 HTML，下文的题目语法就依赖这一点。

# 行内样式

# 彩色文字

在方括号后面跟上颜色类名：

[红色]{.red} [粉色]{.pink} [橙色]{.orange} [黄色]{.yellow} [绿色]{.green}
[青色]{.aqua} [蓝色]{.blue} [紫色]{.purple} [灰色]{.grey}

红色粉色橙色黄色绿色
青色蓝色紫色灰色

方括号里可以继续写其他 Markdown，比如 [**加粗的蓝字**]{.blue}：加粗的蓝字

# 标签与按键

[默认]{.label} [主要]{.label .primary} [成功]{.label .success}
[信息]{.label .info} [警告]{.label .warning} [危险]{.label .danger}

按 [Ctrl]{.kbd} + [C]{.kbd} 复制，[Esc]{.kbd .red} 退出

默认主要成功
信息警告危险

按 Ctrl + C 复制，Esc 退出

按键是 [Ctrl]{.kbd}，不是 [[Ctrl]]。花括号里的属性写法同样适用于图片，例如 ![图](url){width="60%"}。

# 插入、高亮与上下标

++插入的内容++，==高亮的内容==，H~2~O，2^10^ = 1024

插入的内容，高亮的内容，H₂O，2¹⁰ = 1024

# 黑幕

这里有个!!剧透!!，还有个!!模糊的剧透!!{.blur}

这里有个剧透，还有个模糊的剧透

鼠标移上去才显示，悬停提示统一是「你知道得太多了」。

# 注音

{星空^ほしぞら}，{漢字^かん.じ}，{重点^*}

星空(ほしぞら)，漢(かん)字(じ)，重●点●

用 . 按字拆分注音，* 表示每个字上方加着重点。

# 缩写与表情

*[GFM]: GitHub Flavored Markdown

GFM 是 GitHub 扩展的 Markdown 方言 :smile: :rofl:

GFM 是 GitHub 扩展的 Markdown 方言 😄 🤣

定义好缩写后，正文中出现的同名词会自动加上悬停解释。

# 脚注与行内批注

脚注用 [^标识] 引用。行内批注用 [+术语]，点击术语会在旁边弹出解释。定义可以写在文章任意位置。脚注统一列在文末，批注只在弹窗里显示，脚本没加载时才会在文末列出「文中批注」：

这篇手册采用[+渐进增强]的写法，渲染器是 aether[^renderer]。

[^renderer]: 即 `hexo-renderer-aether`，基于 markdown-it 和 Shiki。
[+渐进增强]: 先保证正文与链接可用，再添加弹窗等交互。
    脚本没加载时，点击会跳到文末的「文中批注」。

这篇手册采用渐进增强⁠的写法，渲染器是 aether¹。同一个批注可以重复引用：渐进增强⁠。

没有定义的引用会原样显示。只有定义、没有被引用的条目不会被列出。

# 内容容器

# 提示块

::: 后面接类型，一共六种：

:::default
默认
:::

:::primary
主要
:::

default 默认

primary 主要

success 成功

info 信息

warning 警告

danger 危险

直接写 :::info，不要写成 :::note info。

# 折叠块

+++ 后面接可选的样式和标题，默认收起：

+++primary 点击展开
折叠的内容，里面可以继续写代码块、列表等。
+++

点击展开

折叠的内容，里面可以继续写代码块、列表等。

不带样式的折叠

样式可选 primary、success、info、warning、danger。省略样式时在 +++ 后留一个空格。

适合收起长代码，曲线目录一文的完整源码就是这么收起来的。

# 标签页

连续的 ;;; 块，ID 相同的会合并成一组标签页：

;;;demo Windows
`winget install OpenJS.NodeJS`
;;;

;;;demo macOS
`brew install node`
;;;

winget install OpenJS.NodeJS

brew install node

;;; 后面先写分组 ID，再写标签标题。

# 定义列表

Hexo
: 快速、简洁的静态博客框架

ShokaX
: 基于 Shoka 的 Hexo 主题

Hexo: 快速、简洁的静态博客框架
ShokaX: 基于 Shoka 的 Hexo 主题

# 步骤流

:::steps 里放一个有序列表，每个最外层列表项就是一步。同一步里的段落、代码和子列表要和正文对齐缩进：

:::steps[发布一篇博客]
1. **创建文章**
   在博客根目录执行：
   ```bash
   hexo new "我的新文章"
   ```
2. **编写并预览**
   - 检查图片与链接。
   - 检查手机上的阅读效果。
3. **生成静态文件**
:::

发布一篇博客STEP BY STEP

创建文章
在博客根目录执行：
```
hexo new "我的新文章"
```
编写并预览
- 检查图片与链接。
- 检查手机上的阅读效果。
生成静态文件

标题也可以写成 {title="标题"}，start 用来接着上一段流程继续编号：

:::steps{title="继续检查" start="4"}
1. **确认生成结果**：查看页面是否正常。
2. **发布更新**：按原有方式部署。
:::

继续检查STEP BY STEP

确认生成结果：查看页面是否正常。
发布更新：按原有方式部署。

容器里只能放一个有序列表。结构不对时按普通 Markdown 显示，内容不会丢。

# 文件树

用缩进列表写，每多两个空格表示下一层：

:::file-tree{title="博客示例目录"}
- source
  - _posts
    - **hello.md** # 重点关注的文章
  - images/ # 点开这个目录
    - cover.webp
  - drafts/
- themes
  - shokax-src
    - ++ markdown-blocks.styl # 新增样式
    - -- legacy.css # 准备移除
- package.json # 依赖清单
:::

博客示例目录FILE TREE

source
- _posts
  - hello.md重点关注的文章
- images点开这个目录
  - cover.webp
- drafts
themes
- shokax-src
  - markdown-blocks.styl新增新增样式
  - legacy.css删除准备移除
package.json依赖清单

写法	效果
`- src` 下面继续缩进	目录，默认展开
`- src/` 下面继续缩进	目录，默认折叠
`- empty/` 没有子项	空目录
`- ++ new.js` / `- -- old.js`	新增 / 删除标记
`- main.js`	强调文件名
`- main.js # 入口文件`	名称旁的说明，必须是「空格 + `#` + 空格」，`C#` 不会被误判

tree 命令输出的文本也能直接贴进 file-tree 代码块，支持 ├──、└──、│ 和 Windows 的 +---、\---、|。icon="simple" 使用统一颜色的图标，省略时按文件类型着色：

```file-tree title="构建后的文件" icon="simple"
public
├── css/
│   ├── app.css
│   └── post.css
├── js/
│   └── app.js
└── index.html
```

构建后的文件FILE TREE

public
- css
  - app.css
  - post.css
- js
  - app.js
- index.html

# 参数卡片

field-group 是可选的外层分组，套在外面时要比内层多写一个冒号。@type 写类型、@required / @optional 标记是否必填、@default 写默认值，元信息后空一行再写说明：

::::field-group
:::field title
@type string
@required

文章标题，写一段简洁清楚的文字。
:::
:::field toc_style {type="string" optional default="default"}
目录样式，可选 `default` 或 `curve`，未设置时沿用主题配置。
:::
::::

titlestring必填

文章标题，写一段简洁清楚的文字。

toc_stylestring可选

默认值default

目录样式，可选 default 或 curve，未设置时沿用主题配置。

第二张卡片演示了把参数写在开头花括号里的写法，两种写法可以混用。

# 图片与卡片

# 图片网格

把图片放进 :::grid，每张单独一行。点开任意一张都用文章的图片查看器看原图：

:::grid{columns="2" aspect="16/9"}
![猫咪小镇 · 白天](/images/footer/cat-town.webp)
![猫咪小镇 · 夜晚](/images/footer/cat-town-night.webp "图注优先使用标题")
:::

参数	可用值	默认值
`columns`	1 到 6 的整数	3
`aspect`	正数比例，例如 `16/9`、`1/1`	`cover` 为 `16/10`，`contain` 为原图比例
`fit`	`cover` 裁剪填满，`contain` 完整显示	`cover`

窄于 768px 时最多两列，窄于 480px 时一列。容器里混入了图片以外的文字时，整块按普通 Markdown 显示。contain 适合不能裁剪的截图，不写 aspect 时按原图比例显示，不会留白：

:::grid{columns="2" fit="contain"}
![Scriptable 浅色](/images/projects/scriptable-playground-light.png)
![Scriptable 深色](/images/projects/scriptable-playground-dark.jpg)
:::

# GitHub 仓库卡片

repo 填「所有者/仓库名」，不要粘贴完整网址：

::github{repo="zhangyxXyz/hexo-theme-shokaX"}

zhangyxXyzGitHub · 开源仓库

hexo-theme-shokaX

查看项目源码、文档与最新动态。

查看源码

zhangyxXyz /hexo-theme-shokaX

Stars: —
Forks: —
Issues: —

卡片接近可视区域时才读取 GitHub 公开接口，补充简介、Stars、Forks、Issues、语言和许可证。同一仓库在本次浏览中缓存 30 分钟。请求失败时保留静态说明和链接，不会反复重试。

网络不稳定或不想访问接口时，写一段静态说明并加 fetch="false"：

::github{repo="theme-shoka-x/hexo-theme-shokaX" description="本站主题的上游项目。" fetch="false"}

theme-shoka-xGitHub · 开源仓库

hexo-theme-shokaX

本站主题的上游项目。

查看源码

theme-shoka-x /hexo-theme-shokaX

仓库在 GitHub 设置里填了 Website 时，卡片会自动显示「项目主页」，没有就不显示。也可以用 homepage 手动指定，手写的地址优先：

::github{repo="zhangyxXyz/hexo-circle-of-friends" description="本站友链朋友圈的抓取与接口服务，部署在 Vercel。" homepage="https://hexo-circle-of-friends-git-main-zzzyxs-projects.vercel.app"}

zhangyxXyzGitHub · 开源仓库

hexo-circle-of-friends

本站友链朋友圈的抓取与接口服务，部署在 Vercel。

查看源码项目主页

zhangyxXyz /hexo-circle-of-friends

Stars: —
Forks: —
Issues: —

# 友链卡片

{% links %}
- site: StarryNights
  owner: Seiun
  url: /
  desc: 记录代码，也收藏星光。
  image: assets/avatar.jpg
  color: "#e8608f"
{% endlinks %}

StarryNights

记录代码，也收藏星光。

站内图片写站点根目录下的路径，开头不加 /。外部图片直接写完整地址，友链页用的都是完整地址。

列表很长时，可以把数据放进 source 下的 YAML 文件，用 {% linksfile friend-links/_data.yml %} 引入，友链页就是这么做的。

# 代码

# 代码块

代码高亮由 Shiki 在构建时完成，日间和夜间各一套配色。代码块会自动加上：

语言名称标题栏和行号。
复制、自动换行、全屏三个按钮。
超过 15 行时默认折叠，点击展开。

想强调某几行，在代码行末用注释标记，标记本身不会出现在最终页面里：

标记	效果
`[!code highlight]`	高亮该行
`[!code focus]`	聚焦该行，其余行变淡
`[!code ++]` / `[!code --]`	新增行 / 删除行
`[!code error]` / `[!code warning]`	错误行 / 警告行

注释符号跟随语言，JavaScript 写 // [!code ++]，Python、YAML 写 # [!code ++]：

const renderer = 'aether'
const theme = 'shoka'
const theme = 'shokax'

语言后面写 {1,3} 指定高亮行、写自定义标题，目前都 不生效，标题栏固定显示语言名。

# 代码树

把多个代码块放进 :::code-tree，每个代码块用 title="路径/文件名" 声明它是哪个文件，就会得到一个左侧是文件导航、右侧是代码的小型编辑器。路径里的 / 会自动归成文件夹：

:::code-tree{title="一个主题按钮" height="360px" entry="src/main.js"}
```html title="index.html"
<button class="hello">点我试试</button>
```

```js title="src/main.js"
const button = document.querySelector('.hello')
button.addEventListener('click', () => {
  button.textContent = '你好，ShokaX！'
})
```

```css title="src/button.css"
.hello {
  padding: 10px 18px;
  border: 0;
  border-radius: 12px;
  color: white;
  background: linear-gradient(135deg, #f9709e, #819ee8);
}
```
:::

一个主题按钮3 个文件

index.html

<button class="hello">点我试试</button>

src/main.js

const button = document.querySelector('.hello')
button.addEventListener('click', () => {
  button.textContent = '你好，ShokaX！'
})

src/button.css

.hello {
  padding: 10px 18px;
  border: 0;
  border-radius: 12px;
  color: white;
  background: linear-gradient(135deg, #f9709e, #819ee8);
}

点击左侧文件切换代码，右上角可以复制当前文件或全屏阅读。手机上文件导航会放到代码上方。代码树只展示代码，不会执行里面的示例。title="路径" 只在代码树里有文件导航的含义，普通代码块不受影响。

参数	用途	默认值
`title`	顶部名称	示例工程
`height`	桌面端阅读区高度，支持 `px`、`rem`、`em`、`vh`	`420px`
`entry`	默认打开的文件，建议写完整相对路径	第一个文件
`icon`	`colored` 彩色图标或 `simple` 单色图标	`colored`

也可以在某个代码块的首行末尾加 :active 指定默认文件。entry 和 :active 同时存在时以 entry 为准，没有匹配上就回到第一个文件：

:::code-tree{title="选择默认文件"}
```json title="package.json"
{ "name": "demo" }
```

```js title="main.js" :active
console.log('默认先显示这个文件')
```
:::

选择默认文件2 个文件

package.json

{ "name": "demo" }

main.js

console.log('默认先显示这个文件')

示例比较多时，可以把准备公开的文件放进博客根目录的 examples/，再用一行指令导入，构建时读取并写进页面：

示例文件放在哪里FILE TREE

my-blog
- examples
  - markdown-demo
    main.js
    message.js
    styles
    button.css
- source
  - _posts

::code-tree{dir="/examples/markdown-demo" title="公开的本地示例" entry="main.js"}

公开的本地示例3 个文件

main.js

// 这是可以公开展示的示例，不包含网站真实配置。
import { greeting } from './message.js'

const button = document.querySelector('.hello')
button?.addEventListener('click', () => {
  button.textContent = greeting('ShokaX')
})

message.js

export function greeting(name) {
  return `你好，${name}！`
}

styles/button.css

.hello {
  padding: 10px 18px;
  border: 0;
  border-radius: 12px;
  color: white;
  background: linear-gradient(135deg, #f9709e, #819ee8);
}

也可以写成 @[code-tree title="公开的本地示例" entry="main.js"](/examples/markdown-demo)，效果相同。

/examples/ 指博客根目录下的这个文件夹，不是网站 URL。为避免泄露，只能导入它里面的目录，_config.yml、主题目录或博客外的路径都会被拒绝并在页面上提示。导入时会跳过隐藏文件、符号链接、常见的敏感文件名（密钥、证书、带 secret、token、password 的文件等）和不支持的文件类型，上限为 40 个文件、单文件 64 KB、合计 512 KB。文件名普通不代表内容安全，放进去之前请自己确认没有密码、密钥。

修改了被导入的文件后，文章不会自动重新生成，执行 hexo clean 后重新生成即可。examples/ 本身不会发布，只有被指令选中的文件内容会进入页面。

# 图表与公式

# Mermaid 图表

语言写 mermaid 的代码块会画成图，流程图、时序图、甘特图等 Mermaid 支持的图表都能用。图表滚动到附近时才加载，切换明暗模式会跟着重画：

```mermaid title="写文章的流程"
flowchart LR
  A[写文章] --> B{用到新语法?}
  B -- 是 --> C[保存后实时预览]
  B -- 否 --> D[正常发布]
  C --> D
```

Ctrl / ⌘ + 滚轮缩放 · 放大后可拖动平移放大后可拖动平移

flowchart LR
  A[写文章] --> B{用到新语法?}
  B -- 是 --> C[保存后实时预览]
  B -- 否 --> D[正常发布]
  C --> D

时序图：

Ctrl / ⌘ + 滚轮缩放 · 放大后可拖动平移放大后可拖动平移

sequenceDiagram
  participant 读者
  participant 页面
  participant GitHub
  读者->>页面: 打开文章
  页面->>GitHub: 读取仓库信息
  GitHub-->>页面: Stars、Forks
  页面-->>读者: 显示仓库卡片

标题栏左侧会按语法自动显示图表类型（Flowchart、Sequence、Gantt……，和代码块的语言名一样不做翻译），在语言后面写 title="…" 还能加一个标题，如上面的流程图。右侧工具栏可以缩小、放大、恢复初始视角，还能切换源码和全屏查看。画布支持拖动。按住 Ctrl（Mac 上是 ⌘）再滚动滚轮可以以指针为中心缩放，普通滚轮照常滚动页面。点击画布后还可以用键盘操作：+、- 缩放，方向键平移，0 恢复初始视角。手机上，图表放大以后才能拖动，没放大时手指滑动仍然是滚动页面。

语法写错时，图表位置会提示出错并显示源码，不会让整页报错。

全站图表可以统一换成手绘风格，在 _config.shokax.yml 里设置：

mermaid:
    look: handDrawn  # classic 为普通样式（默认）
    font_family: Excalifont, JasonHandwriting1  # 手绘字体，按顺序逐级回落，最后回落到正文字体

流程图、状态图、类图和 ER 图用 Mermaid 自带的手绘效果。时序图、甘特图、饼图等 Mermaid 不支持手绘的图表，会先按普通样式画好，再交给 svg2roughjs 重描一遍线条和填充。同一张图每次刷新的笔触都相同。手绘脚本加载失败时，这类图表照常显示普通样式。

手绘风格下，图表文字换成手写字体：英文和数字用 Excalifont，中文用清松手寫體，简体和繁体都有对应字形，切换简繁后不会混进别的字体。两款字体和正文字体一样用 @font-face 声明，只有页面里出现手绘图表时才会下载。普通样式沿用正文字体。

# 数学公式

公式在构建时由 KaTeX 渲染。文章 Front-matter 加上 math: true，复制公式时会得到 LaTeX 源码。

行内公式 $E = mc^2$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

行内公式 $E = mc^2$

$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$

具体公式写法见 Latex基本语法。

# 题目

给有序列表项加上 {.quiz} 就是一道题。选项列表末尾另起一行写 {.options}，正确选项加 {.correct}，引用块作为解析：

1. 本站使用哪个 Markdown 渲染器？{.quiz}
    - hexo-renderer-marked
    - hexo-renderer-aether{.correct}
    - hexo-renderer-markdown-it
    {.options}
    > 解析：当前使用 `hexo-renderer-aether`。

2. 下列哪些属于提示块类型？{.quiz .multi}
    - info{.correct}
    - note
    - warning{.correct}
    {.options}
    > 解析：没有 `note` 类型。

3. 代码块可以用 `{1,3}` 指定高亮行。{.quiz .false}
    > 解析：不生效，改用 `[!code highlight]` 注释。

本站使用哪个 Markdown 渲染器？
- hexo-renderer-marked
- hexo-renderer-aether
- hexo-renderer-markdown-it
解析：当前使用 hexo-renderer-aether。
下列哪些属于提示块类型？
- info
- note
- warning
解析：没有 note 类型。
代码块可以用 {1,3} 指定高亮行。
解析：不生效，改用 [!code highlight] 注释。

点击选项判断对错，点击题干展开解析。题型类名还有 .true（判断题，正确）、.fill（填空）、.essay（问答）。

# Hexo 标签

Hexo 自带的标签都能用，常用的是站内文章链接：

{% post_link Shoka/shoka-post-history-timeline %}
{% post_link Shoka/shoka-post-history-timeline 自定义链接文字 %}

Shoka主题: 文章更新历史记录时间轴

参数是相对 source/_posts 的路径，不带 .md。

代码块里的 {% %} 会原样显示，不需要额外处理。行内代码或正文里要原样输出，用 raw 和 endraw 标签包起来。

# 设置点

# 站点配置

主题配置写在博客根目录的 _config.shokax.yml，只写需要覆盖的部分，其余沿用主题默认值。下面按用途列出常调的配置项。

# 外观

配置项	作用	本站取值
`palette.primary` / `secondary`	站点主色和辅助色	`#E8608F` / `#D35A9E`
`darkmode`	没有自动规则时是否默认深色	`false`
`auto_dark.start` / `end`	按时段自动切换深色	`21` 点到 `8` 点
`theme_transition`	明暗切换动画，`sunrise` 或 `moon-stars`	`moon-stars`
`font`	各区域字体与字号	自定义字体
`loader`	首次进入和切页的加载动画	均开启
`festival.enable`	节日与节气装饰	开启
`footer.landscape`	页脚风景图，日夜各一张	开启

# 侧栏与列表页

配置项	作用	本站取值
`sidebar.position`	侧栏位置	`right`
`sidebar.toc_style`	目录样式，`default` 或 `curve`	`curve`
`widgets.random_posts` / `recent_comments`	侧栏随机文章、最近评论	开启
`archive_view.mode`	归档页 `tree` 或 `classic`	`tree`，不允许切换
`category_view.mode`	分类页 `cards` 或 `classic`	`cards`
`tagcloud.mode`	标签云 `2d` 或 `3d`	`2d`
`homeConfig.cateCards`	首页分类卡片	6 个分类

# 文章

配置项	作用	本站取值
`post.count`	字数与阅读时长	开启
`isOutdated.days`	超过多少天提示内容可能过时	`30`
`summary.enable`	构建时生成 AI 摘要	开启
`related_reading.enable`	文末继续阅读推荐	开启
`article_graph.enable`	文章引用关系图	开启
`reward.enable`	文末赞赏	开启
`creative_commons`	版权协议	`by-nc-sa`
`auto_scroll`	回到页面时恢复上次阅读位置	开启

# 功能模块

配置项	作用	本站取值
`modules.pjax`	无刷新切页，音乐不中断	开启
`modules.tabs` / `modules.quiz`	标签页、题目交互	开启
`waline`	评论系统	开启
`pagefind.enable`	站内搜索	开启
`visitor`	阅读次数与访问量	开启
`live2d.enable`	看板娘	开启
`fireworks.enable`	点击烟花	开启
`reading_settings.enable`	显示与阅读面板	开启

pagefind 的索引不是 hexo generate 自动生成的，需要另外执行 pnpm run search:build。

# 文章 Front-matter

除了 title、date、tags、categories 这些常规字段，下面这些可以针对单篇文章调整：

字段	作用
`sticky: true`	首页置顶
`cover`	指定封面图
`photos`	文首图集
`link`	标题直接跳转外部链接
`math: true`	公式复制为 `LaTeX` 源码
`toc_style`	单篇使用 `default` 或 `curve` 目录
`comment: false`	关闭评论
`comment_layout`	评论区布局，`slide` 或 `bottom`
`reward: false`	关闭赞赏
`copyright: false`	隐藏版权声明
`nocopy: true`	禁止复制正文
`audio`	本页歌单，`false` 表示不加载
`pjax: false`	本页禁用无刷新切页
`isOutdated: false`	关闭过时提示
`ai_summary: false`	不生成 AI 摘要
`related_reading: false`	不参与继续阅读推荐
`article_graph: false`	隐藏引用关系图
`password`	加密文章
`changelogs`	更新历史
`reprintlink`	转载来源

文章里写了就用文章的，没写就继承站点配置。

# 显示与阅读

页面右下角工具栏里的「显示与阅读」是给读者用的，调整结果只保存在当前浏览器，不影响站点配置。

选项	可选值	默认
主题主色、辅助颜色	色块取色，或输入 HEX / RGB	跟随站点配置
正文字号	标准、稍大、更大	标准
正文行距	紧凑、标准、宽松	标准
明暗模式	主题默认、跟随系统、浅色、深色	主题默认
减少动态效果	跟随系统、开启	跟随系统
页首横幅	图片横幅、简洁主题色	图片横幅
背景纹理	无、星点、点阵、等高线、折纸、樱花	无
纹理浓度	5% ~ 25%	12%
首页排列	列表、双列	列表

字号和行距只作用于文章正文。双列只在宽屏生效，手机仍然是单列。

# 本站扩展点

下面这些是在主题之外补充或改造的功能。有单独文章的，直接点过去看实现。

# 文章相关

功能	用法	详细说明
曲线目录	`toc_style: curve`	Hexo: 给 ShokaX 迁移一个 Fumadocs 风格的曲线目录
更新历史时间轴	`changelogs`	Shoka主题: 文章更新历史记录时间轴
过时提示	`isOutdated`	Shoka主题: 文章添加实效性提示
转载标记	`reprintlink`	Shoka主题: 文章添加转载标记
文章加密	`password`	Hexo: 文章加密
图片相对路径	`![desc](./文章名/图片.png)`，本地编辑器也能预览	Shoka主题: 自定义过滤器重定向资源文件夹图片相对路径引用
AI 摘要	站点 `summary` + 文章 `ai_summary`	—
继续阅读与引用关系图	`related_reading`、`article_graph`	—
简繁转换	工具栏按钮，整页转换	—

changelogs 的格式，以本文为例，按时间从早到晚排列：

changelogs:
  - summary: 2022-06-06 立项
    list:
      - 1. 建立使用手册，用于个人查找主题写法
  - summary: 2026-11-05 补全使用手册
    list:
      - 1. 整理 Markdown 语法与渲染效果
      - 2. 整理站点配置与文章 Front-matter
      - 3. 汇总本站扩展点

reprintlink 支持三种写法：只写来源名、只写链接，或者 来源名||链接。

# 站点与页面

功能	说明
显示与阅读面板	见上文「显示与阅读」
归档时间树、分类卡片	归档、分类、标签详情页的新视图
标签云数字角标	Hexo: 标签云TagCloud标签文章数量数字角标
朋友圈	聚合友链博客的最新文章，见朋友圈
资讯、统计、项目、书签	独立页面
音乐播放器	`nyx-player`，支持频谱和歌词，切页不中断
看板娘	节日、节气提醒
节日装饰、页脚风景	按日期自动切换
评论	`Waline` 定制客户端，带友链徽章和等级配色

# 构建与资源

功能	说明
资源本地化	第三方资源下载到本站，见 Shoka主题: 去jsDelivr依赖之资源本地化
主题构建	`pnpm run theme:build`，从主题源码生成运行目录
本地预览	`pnpm run dev`
发布	`pnpm run publish`，构建、压缩、生成搜索索引后部署

# 结语

写文章常用的就是彩色文字、提示块、折叠和代码块这几样，其他的忘了回来翻一翻就行。

手册会跟着站点一起更新，有新写法再补上~

文中批注

渐进增强
先保证正文与链接可用，再添加弹窗等交互。
脚本没加载时，点击会跳到文末的「文中批注」。
↩¹ ↩²

脚注

即 hexo-renderer-aether，基于 markdown-it 和 Shiki。
↩

文章关联

9 篇关联

顺着引用的连线，读见篇章交错的脉络

展开关系图

拖动平移 · Ctrl / ⌘ + 滚轮缩放 · 点击节点阅读使用 + / − 按钮缩放 · 放大视图后可拖动 · 点击节点阅读单指拖动平移 · 使用 + / − 按钮缩放 · 点击节点阅读

当前文章本文引用

引用列表

引用本文0

暂无

本文引用9

Latex基本语法
AI 摘要
文章介绍 LaTeX 是生成 .tex 纯文本的排版系统，非所见即所得，广泛用于数学、计算机等学术写作，便于专注内容。浏览器中可借助开源引擎 MathJax 渲染 LaTeX、MathML 和 ASCIIMathML 公式。本文主要讲解 MathJax 的 LaTeX 基础语法，不涉及安装配置，并汇总公式位置、保留字符、希腊字母、上下标、括号、空格换行、颜色、字体、运算符、关系符及集合、箭头、特殊符号等常用标记。
Shoka主题: 去jsDelivr依赖之资源本地化
AI 摘要
文章因 jsDelivr 在国内访问异常，Shoka 主题资源加载受阻，作者将第三方依赖本地化。做法是下载 vendors 资源到 source/cdn.jsdelivr.net 并保持目录结构，整包下载 KaTeX、表情包，处理 MiniValine 嵌套依赖并替换链接；修改主题配置及加载代码为本地路径，配置压缩白名单，并可选用 Git、COS、CDN 优化推送缓存。最终摆脱 jsDelivr 依赖，提升稳定性。
Shoka主题: 自定义过滤器重定向资源文件夹图片相对路径引用
AI 摘要
文章讨论 Hexo 启用资源文件夹后，Markdown 用相对路径引用图片便于本地预览，却与生成发布时的资源路径重定向冲突，官方方案又会破坏本地预览。作者提出利用 Hexo 的 after_post_render 过滤器，通过 cheerio 处理文章内容中的 img 标签，将 data-src 修改为指向文章资源文件夹的正确路径，从而兼顾本地预览和发布重定向。
Hexo: 文章加密
AI 摘要
作者重启Hexo静态博客后，为保护隐私文章，采用hexo-blog-encrypt插件实现文章加密。文章介绍了插件安装、Front-matter配置、基于tag的全局加密，以及利用优先级实现单篇豁免或自定义密码。随后针对Shoka主题，通过修改模板解决解密后目录不显示的问题，并添加加密图标提示。整体分享了Hexo文章加密的完整实践与主题适配经验。
Hexo: 给 ShokaX 迁移一个 Fumadocs 风格的曲线目录
AI 摘要
本文记录为 ShokaX 博客主题实现 Fumadocs 风格曲线目录的过程。核心是将高亮从阅读进度改为当前视口内标题范围，命中标题同时控制高亮和子目录展开；用 SVG 绘制底线、弯折路径与裁剪高亮区间，配合 TypeScript 监听滚动、动画和 PJAX 清理，并保留层级编号、点击跳转、主题配色、长标题换行及全局和单篇开关，最后给出按文件接入的完整方案。
Hexo: 标签云TagCloud标签文章数量数字角标
AI 摘要
作者在 Hexo 的 Shoka 主题中，为标签云增加显示标签对应文章数量的数字角标。他通过 F12 和源码定位到 Hexo 内置的 tagcloud 辅助函数，在主题 scripts/helpers 下新建 tagcloudplus.js，复制并改写源码，在链接中插入 sup 标签输出 tag.length，再调整标签云样式、颜色变量，并将 page.njk 中的调用替换为 tagcloudplus。这样避免直接修改 node_modules，便于跨设备维护。
Shoka主题: 文章添加实效性提示
AI 摘要
本文介绍为 Shoka 主题添加文章时效性提示的方法。通过修改 _config.yml、多语言文件、layout.njk、global.js、pjax.js 和 script.js，配置启用开关、超时天数、提示模板与多语言文本；再由脚本计算文章发布及最后更新距今时间，超过设定天数后在正文顶部插入警告。文章还可通过 Front-matter 的 isOutdated: false 单独关闭提示。
Shoka主题: 文章添加转载标记
AI 摘要
文章介绍为 Shoka 主题添加文章转载标记的方法。借由文章 Front-matter 中的 reprintlink 字段记录转载信息，以“||”分隔链接文本与网址；若只写一部分则两者共用，非 http 链接会提示原文出处暂无处追寻。实现上需修改 zh-CN.yml 增加多语言文案，并调整 postmeta.njk 与 post.njk，在主页缩略信息头部和正文头部展示转载标识与来源链接。
Shoka主题: 文章更新历史记录时间轴
AI 摘要
文章介绍如何在Hexo主题中为文章添加修订记录时间轴。灵感来自归档时间轴，通过在文章Front-matter中配置changelogs记录更新摘要与明细，渲染时解析生成对应HTML，并复制修改归档样式，新增颜色变量和语言包键值，在post.njk模板中插入可折叠的时间轴代码。发布后即可在文章头部展示更新记录，实现优雅的历史版本展示。

基于GitHub Pages + Hexo搭建个人博客
AI 摘要
文章介绍 Hexo 静态博客框架及搭建教程。先对比静态与动态博客，指出 Hexo 省心、省钱、速度快、利于 SEO，但缺动态功能、维护成本较高；随后讲解环境准备，包括安装 Git、Node.js、Hexo CLI，初始化博客并执行 clean、generate、server 三连预览；再说明安装 butterfly 等主题、配置部署插件并发布到 GitHub Pages，最后介绍绑定腾讯云或阿里云域名并做 DNS 解析。
Hexo: 使用gulp压缩博客文件
AI 摘要
文章介绍用 gulp 自动化压缩优化 Hexo 生成的博客文件，以减小空白与资源体积、提升访问速度。作者安装 gulp 及 CSS、JS、图片、HTML 压缩插件，新建 gulpfile.js，配置各项 minify 任务并默认并行执行。最后建议在部署命令中加入 gulp，形成 hexo clean、generate、gulp、deploy 的四连流程。
Lua - 基础语法篇
AI 摘要
这篇Lua学习笔记以官方文档为参考，系统整理Lua基础语法，包括八种数据类型、局部与全局变量、table构造式，以及算术、关系、逻辑、连接和长度运算符与优先级；同时介绍赋值、控制结构（if、while、repeat、数字型for和泛型for）及break、return等语句，适合作为游戏开发中的Lua备忘。

本文作者：Seiun@繁夜
本文链接：https://onlyzyx.com/posts/27651.html
版权声明：本站所有文章除特别声明外，均采用 (CC)BY-NC-SA 许可协议。转载请注明出处！