update readme
This commit is contained in:
HPCesia
parent
c5f26c2248
commit
0a8d8e5b0b
55
README.md
55
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 <pre> 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:
|
||||
|
||||
@ -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 # 保留 <pre> 标签的样式，即主题的 `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)
|
||||
|
||||
## 感谢
|
||||
本插件基于
|
||||
|
||||
Loading…
Reference in New Issue
Block a user