diff --git a/README.md b/README.md index a084ce0..89468f8 100644 --- a/README.md +++ b/README.md @@ -45,17 +45,21 @@ shiki: line_number: false # default: false strip_indent: true # default: true tab_replace: " " # default: " " - pre_style: true # Preserve the style of the
tag, i.e., the theme's `background-color`. default: true
+ pre_style: true # Preserve the style of the tag. default: true
default_color: light # Only take effect when using multiple themes. default: light
css_variable_prefix: --shiki- # Only take effect when using multiple themes. default: --shiki-
transformers:
# List of transformers to be enabled.
# Please refer to https://shiki.style/packages/transformers for the list of supported transformers.
- - "example1" # You can omit `name` and `option` when no options are required, directly using the string.
- - name: example2 # When additional option are required, please explicitly set name and option.
+ # You can omit `name` and `option` when no options are required, directly using the string.
+ - "example1"
+ # When additional option are required, please explicitly set name and option.
+ - name: example2
option:
- # Options for the transformer, please check the @shikijs/transformer's source code to get the list of supported options
- # Source code of @shikijs/transformer: https://github.com/shikijs/shiki/tree/main/packages/transformers/src/transformers
+ # Options for the transformer.
+ # Please check the @shikijs/transformer's source code to get the list of supported options
+ # Source code of @shikijs/transformer:
+ # https://github.com/shikijs/shiki/tree/main/packages/transformers/src/transformers
exampleOption1: exampleValue1
exampleOption2: exampleValue2
additional:
@@ -68,7 +72,19 @@ shiki:
your_alias2: lang_name2
```
-For example, if you want to mark some lines, you can use Hexo's code block tag plugin (which has been adapted by this plugin):
+Additionally, you can specify multiple themes in the `theme` option:
+```yaml
+shiki:
+ theme:
+ light: one-light
+ dark: one-dark-pro
+ # ...
+```
+See [Dual Themes](https://shiki.style/guide/dual-themes) for how to switch between multiple themes.
+
+
+### Example of Using Transformers
+if you want to mark some lines, you can use Hexo's code block tag plugin (which has been adapted by this plugin):
```markdown
{% codeblock lang:rust mark:2 %}
fn main() {
@@ -82,8 +98,8 @@ But if you want to mark some lines in backtick code blocks, you can use transfor
transformers:
- name: transformerNotationHighlight
option:
- classActiveLine: marked # same to Hexo's code block tag marked line's class, default: highlighted
- classActivePre: has-marked # default: has-highlighted
+ classActiveLine: marked # same to Hexo's code block tag, default: highlighted
+ classActivePre: "" # default: has-highlighted
```
and add some comment to your code block:
````markdown
@@ -95,26 +111,17 @@ fn main() {
````
The result is the same as the Hexo code block tag plugin.
-Additionally, you can specify multiple themes in the `theme` option:
-```yaml
-shiki:
- theme:
- light: one-light
- dark: one-dark-pro
- # ...
-```
-See [Dual Themes](https://shiki.style/guide/dual-themes) for how to switch between multiple themes.
-
## Bugs
### mathjax
If you are using [hexo-filter-mathjax](https://github.com/next-theme/hexo-filter-mathjax) or any other plugin that uses mathjax to render mathematical formulas locally, you may encounter an `Error: Can't find handler for document` when rendering articles that include code blocks and have mathjax rendering enabled. This is a problem with mathjax, as its LiteDOM adaptor cannot parse complex HTML fragments.
#### Solution
-
For example, if you are using the hexo-filter-mathjax plugin, modify the [this line](https://github.com/next-theme/hexo-filter-mathjax/blob/20dc61352f8cf4d19425ad1833eb72b467c212ef/index.js#L20C3-L20C40) in the source code:
```js
- data.content = mathjax(data.content);
-+ data.content = data.content.replace(/\\[\(\[].*?\\[\)\]]<\/span>/gs, mathjax);
++ data.content = data.content.replace(
++ /\\[\(\[].*?\\[\)\]]<\/span>/gs,
++ mathjax);
```
This will prevent rendering errors for complex HTML fragments that result in `Can't find handler for document`.
diff --git a/README_zh-CN.md b/README_zh-CN.md
index b609398..16beb86 100644
--- a/README_zh-CN.md
+++ b/README_zh-CN.md
@@ -66,7 +66,18 @@ shiki:
your_alias2: lang_name2
```
-例如,如果你想标记某些行,你可以使用 Hexo 的代码块标签插件(本插件对其做了适配):
+额外地,你可以在 `theme` 选项中指定多个主题:
+```yaml
+shiki:
+ theme:
+ light: one-light
+ dark: one-dark-pro
+ # ...
+```
+在 [Dual Themes](https://shiki.style/guide/dual-themes) 中查看如何切换多个主题。
+
+### 转换器使用示例
+如果你想标记某些行,你可以使用 Hexo 的代码块标签插件(本插件对其做了适配):
```markdown
{% codeblock lang:rust mark:2 %}
fn main() {
@@ -81,7 +92,7 @@ transformers:
- name: transformerNotationHighlight
option:
classActiveLine: marked # 与 Hexo 的代码块标签标记行的类相同,默认值:highlighted
- classActivePre: '' # 默认值:has-highlighted
+ classActivePre: "" # 默认值:has-highlighted
```
并在你的代码块中添加一些注释:
````markdown
@@ -93,26 +104,17 @@ fn main() {
````
结果与 Hexo 的代码块标签插件相同。
-额外地,你可以在 `theme` 选项中指定多个主题:
-```yaml
-shiki:
- theme:
- light: one-light
- dark: one-dark-pro
- # ...
-```
-在 [Dual Themes](https://shiki.style/guide/dual-themes) 中查看如何切换多个主题。
-
## Bugs
### mathjax
如果你正在使用 [hexo-filter-mathjax](https://github.com/next-theme/hexo-filter-mathjax) 或其他任意在本地使用 mathjax 渲染数学公式的插件,在渲染包含代码块且开启 mathjax 渲染的文章时可能会出现 `Error: Can't find handler for document`。这是 mathjax 的问题,mathjax 的 LiteDOM adaptor 无法解析复杂的 HTML 片段。
#### 解决方法
-
以 hexo-filter-mathjax 插件为例,修改源代码中的[这一行](https://github.com/next-theme/hexo-filter-mathjax/blob/20dc61352f8cf4d19425ad1833eb72b467c212ef/index.js#L20C3-L20C40):
```js
- data.content = mathjax(data.content);
-+ data.content = data.content.replace(/\\[\(\[].*?\\[\)\]]<\/span>/gs, mathjax);
++ data.content = data.content.replace(
++ /\\[\(\[].*?\\[\)\]]<\/span>/gs,
++ mathjax);
```
这可以避免对那些复杂的 HTML 片段进行渲染导致的 `Can't find handler for document` 错误。