4.7 KiB
4.7 KiB
Hexo-Highlight-Shiki
English丨简体中文
一个使用 Shiki 作为代码块高亮器的 Hexo 插件。
需要 Hexo v7.0.0+。
功能
- 使用 Shiki 渲染代码块，且与 Hexo 默认的代码高亮渲染的格式相似（因此你不需要对你现在使用的主题做很大的修改）。
- 支持多主题切换（需要自行编写对应的样式与脚本）。
- 支持自定义语言。
- 支持自定义主题。
- 支持 @shikijs/transformers 中的转换器。
安装与配置
首先，安装本插件：
npm install hexo-highlighter-shiki --save
然后在 config.yml 中切换代码高亮引擎：
syntax_highlighter: shiki
最后配置 shiki：
shiki:
theme: one-dark-pro
并使用
hexo clean && hexo generate
来享受由 Shiki 提供的代码高亮功能。
配置项
完整配置如下：
shiki:
theme: "one-dark-pro" # 主题，请参阅 https://shiki.style/themes 以获取支持的主题列表。
line_number: false
strip_indent: true
tab_replace: " "
pre_style: true # 保留 <pre> 标签的样式，即主题的 `background-color`。
default_color: light # 仅在同时使用多个主题时生效。默认值：light
css_variable_prefix: --shiki- # 仅在同时使用多个主题时生效。默认值：--shiki-
transformers:
# 需要启用的转换器列表。请参阅 https://shiki.style/packages/transformers 以获取支持的转换器列表。
- "example1" # 不需要设置选项时，可省略 `name` 与 `option`，直接使用字符串。
- name: example2 # 需要设置选项时，请显式设置 name 与 option。
option:
# 转换器的选项，请查看转换器的源码以获取支持的选项列表
# 转换器源码：https://github.com/shikijs/shiki/tree/main/packages/transformers/src/transformers
exampleOption1: exampleValue1
exampleOption2: exampleValue2
additional:
themes: # 要添加的主题的 TextMate 主题 json 列表。
- path/to/theme.json
langs: # 要添加的语言的 TextMate 语法 json 列表。
- path/to/lang_grammar.json
lang_alias: # 语言的别名列表。
your_alias1: lang_name1
your_alias2: lang_name2
例如，如果你想标记某些行，你可以使用 Hexo 的代码块标签插件（本插件对其做了适配）：
{% codeblock lang:rust mark:2 %}
fn main() {
println!("Hello, world!");
}
{% endcodeblock %}
但是，如果你想在反引号代码块中标记某些行，你可以使用转换器：
transformers:
- name: transformerNotationHighlight
option:
classActiveLine: marked # 与 Hexo 的代码块标签标记行的类相同，默认值：highlighted
classActivePre: '' # 默认值：has-highlighted
并在你的代码块中添加一些注释：
```rust
fn main() {
println!("Hello, world!"); // [!code highlight]
}
```
结果与 Hexo 的代码块标签插件相同。
额外地，你可以在 theme 选项中指定多个主题：
shiki:
theme:
light: one-light
dark: one-dark-pro
# ...
在 Dual Themes 中查看如何切换多个主题。
Bugs
mathjax
如果你正在使用 hexo-filter-mathjax 或其他任意在本地使用 mathjax 渲染数学公式的插件，在渲染包含代码块且开启 mathjax 渲染的文章时可能会出现 Error: Can't find handler for document。这是 mathjax 的问题，mathjax 的 LiteDOM adaptor 无法解析复杂的 HTML 片段。
解决方法
以 hexo-filter-mathjax 插件为例，修改源代码中的这一行:
- data.content = mathjax(data.content);
+ data.content = data.content.replace(/<span\s+class="math\s+[^"]*">\\[\(\[].*?\\[\)\]]<\/span>/gs, mathjax);
这可以避免对那些复杂的 HTML 片段进行渲染导致的 Can't find handler for document 错误。
相关 Issues
感谢
本插件基于
进行开发。