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) ## 感谢 本插件基于