diff --git a/README.md b/README.md index 40e8af4..a084ce0 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,11 @@ A hexo plugin to use [Shiki](https://github.com/shikijs/shiki) as code block hig Hexo v7.0.0+ is required. ## Features -- Render code block with Shiki like Hexo default highlighter. -- Support dual or more themes. +- Use [Shiki](https://github.com/shikijs/shiki) to render code blocks, and the format is similar to Hexo's default code highlighting (so you don't need to make significant changes to the theme you are currently using). +- Support switching between multiple themes (you need to write the corresponding styles and scripts yourself). - Support custom language. +- Support custom theme. +- Support transformers in [@shikijs/transformers](https://shiki.style/packages/transformers). ## Installation and Configuration First, install the plugin: @@ -29,6 +31,11 @@ shiki: theme: github-dark # default: one-dark-pro line_number: true # default: false ``` +and use +```shell +hexo clean && hexo generate +``` +to enjoy code highlighting powered by Shiki. ## Configuration Options The complete configuration is as follows: @@ -41,13 +48,16 @@ shiki: pre_style: true # Preserve the style of the
 tag, i.e., the theme's `background-color`. 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.
-    - "transformerNotationDiff" # You can omit name and option when no settings are required, directly using the string.
-    - name: transformerNotationFocus # When additional option are required, please explicitly set name and option.
-      option: # Options for the transformer, please check the transformer's source code to get the list of supported options
-      # Source code of transformers: https://github.com/shikijs/shiki/tree/main/packages/transformers/src/transformers
-        classActiveLine: focused
-        classActivePre: has-focused
+  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.
+      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
+        exampleOption1: exampleValue1
+        exampleOption2: exampleValue2
   additional:
     themes: # List of the TextMate theme json to be added.
       - path/to/theme.json
@@ -58,6 +68,33 @@ 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):
+```markdown
+{% codeblock lang:rust mark:2 %}
+fn main() {
+    println!("Hello, world!");
+}
+{% endcodeblock %}
+```
+
+But if you want to mark some lines in backtick code blocks, you can use transformer:
+```yaml
+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
+```
+and add some comment to your code block:
+````markdown
+```rust
+fn main() {
+    println!("Hello, world!"); // [!code highlight]
+}
+```
+````
+The result is the same as the Hexo code block tag plugin.
+
 Additionally, you can specify multiple themes in the `theme` option:
 ```yaml
 shiki:
diff --git a/README_zh-CN.md b/README_zh-CN.md
index b5582c7..b609398 100644
--- a/README_zh-CN.md
+++ b/README_zh-CN.md
@@ -8,9 +8,11 @@
 需要 Hexo v7.0.0+。
 
 ## 功能
-- 使用 Shiki 渲染代码块,类似于 Hexo 默认的高亮器。
-- 支持双主题或更多主题。
+- 使用 [Shiki](https://github.com/shikijs/shiki) 渲染代码块,且与 Hexo 默认的代码高亮渲染的格式相似(因此你不需要对你现在使用的主题做很大的修改)。
+- 支持多主题切换(需要自行编写对应的样式与脚本)。
 - 支持自定义语言。
+- 支持自定义主题。
+- 支持 [@shikijs/transformers](https://shiki.style/packages/transformers) 中的转换器。
 
 ## 安装与配置
 首先,安装本插件:
@@ -28,6 +30,11 @@ syntax_highlighter: shiki
 shiki:
   theme: one-dark-pro
 ```
+并使用
+```shell
+hexo clean && hexo generate
+```
+来享受由 Shiki 提供的代码高亮功能。
 
 ## 配置项
 完整配置如下:
@@ -40,15 +47,18 @@ shiki:
   pre_style: true # 保留 
 标签的样式,即主题的 `background-color`。
   default_color: light # 仅在同时使用多个主题时生效。默认值:light
   css_variable_prefix: --shiki- # 仅在同时使用多个主题时生效。默认值:--shiki-
-  transformers: # 需要启用的转换器列表。请参阅 https://shiki.style/packages/transformers 以获取支持的转换器列表。
-    - "transformerNotationDiff" # 不需要设置选项时,可省略 name 与 option,直接使用字符串。
-    - name: transformerNotationFocus # 需要设置选项时,请显式设置 name 与 option。
-      option: # 转换器的选项,请查看转换器的源码以获取支持的选项列表
+  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
-        classActiveLine: focused
-        classActivePre: has-focused
+        exampleOption1: exampleValue1
+        exampleOption2: exampleValue2
   additional:
     themes: # 要添加的主题的 TextMate 主题 json 列表。
+      - path/to/theme.json
     langs: # 要添加的语言的 TextMate 语法 json 列表。
       - path/to/lang_grammar.json
     lang_alias: # 语言的别名列表。
@@ -56,6 +66,33 @@ shiki:
       your_alias2: lang_name2
 ```
 
+例如,如果你想标记某些行,你可以使用 Hexo 的代码块标签插件(本插件对其做了适配):
+```markdown
+{% codeblock lang:rust mark:2 %}
+fn main() {
+    println!("Hello, world!");
+}
+{% endcodeblock %}
+```
+
+但是,如果你想在反引号代码块中标记某些行,你可以使用转换器:
+```yaml
+transformers:
+  - name: transformerNotationHighlight
+    option:
+      classActiveLine: marked # 与 Hexo 的代码块标签标记行的类相同,默认值:highlighted
+      classActivePre: '' # 默认值:has-highlighted
+```
+并在你的代码块中添加一些注释:
+````markdown
+```rust
+fn main() {
+    println!("Hello, world!"); // [!code highlight]
+}
+```
+````
+结果与 Hexo 的代码块标签插件相同。
+
 额外地,你可以在 `theme` 选项中指定多个主题:
 ```yaml
 shiki:
@@ -64,7 +101,7 @@ shiki:
     dark: one-dark-pro
     # ...
 ```
-在 [Dual Themes](https://shiki.style/guide/dual-themes)     中查看如何切换多个主题。
+在 [Dual Themes](https://shiki.style/guide/dual-themes) 中查看如何切换多个主题。
 
 ## Bugs
 ### mathjax
@@ -81,7 +118,7 @@ shiki:
 
 #### 相关 Issues
 - [Error in applying html the markdown file #26](https://github.com/next-theme/hexo-filter-mathjax/issues/26)
-- [ Can't find handler for document #265 ](https://github.com/mathjax/MathJax-src/issues/265)
+- [Can't find handler for document #265](https://github.com/mathjax/MathJax-src/issues/265)
 
 ## 感谢
 本插件基于