Skip to content

Commit 21f18c6

Browse files
committed
docs: update readme
1 parent 5d7c4a0 commit 21f18c6

1 file changed

Lines changed: 93 additions & 93 deletions

File tree

README.md

Lines changed: 93 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@
4444
- 无需主题适配即可使用的功能:
4545
- [代码高亮处理器](#代码高亮处理器)(仅全量版可用)
4646
- 需要主题适配的 Finder API:
47-
- [文章字数统计 API](#文章字数统计-api)
47+
- [文章字数统计 API(单篇/全站)](#文章字数统计-api)
4848
- [HTML 内容字数统计 API](#html-内容字数统计-api)
4949
- [代码高亮 API](#代码高亮-api)(仅全量版可用)
5050

@@ -212,12 +212,6 @@ ERROR - JavetException: Javet library is not loaded because <null>
212212
- [问题一解决方案](#问题一解决方案)
213213
- [TODO](#todo)
214214
- [文档目录](#文档目录)
215-
- [处理器文档](#处理器文档)
216-
- [代码高亮处理器](#代码高亮处理器)
217-
- [特点](#特点)
218-
- [配置选项](#配置选项)
219-
- [支持的主题](#支持的主题)
220-
- [补充说明](#补充说明)
221215
- [Finder API 文档](#finder-api-文档)
222216
- [文档类型定义](#文档类型定义)
223217
- [插件本体信息相关 API](#插件本体信息相关-api)
@@ -228,98 +222,19 @@ ERROR - JavetException: Javet library is not loaded because <null>
228222
- [HTML 内容字数统计 API](#html-内容字数统计-api)
229223
- [渲染 API](#渲染-api)
230224
- [代码高亮 API](#代码高亮-api)
225+
- [处理器文档](#处理器文档)
226+
- [代码高亮处理器](#代码高亮处理器)
227+
- [特点](#特点)
228+
- [配置选项](#配置选项)
229+
- [支持的主题](#支持的主题)
230+
- [补充说明](#补充说明)
231231
- [下载和安装](#下载和安装)
232232
- [稳定版](#稳定版)
233233
- [开发版](#开发版)
234234
- [下载步骤](#下载步骤)
235235
- [开发指南/贡献指南](#开发指南贡献指南)
236236
- [许可证](#许可证)
237237

238-
## 处理器文档
239-
240-
### 代码高亮处理器
241-
242-
插件提供了自动化的代码高亮处理器,无需在模板中手动调用,即可对文章和页面内容中的代码块进行语法高亮渲染。
243-
244-
此功能通过 Shiki.js 渲染,仅在[全量版](#版本说明)中可用。
245-
246-
#### 特点
247-
248-
- 双主题支持:
249-
- 可同时渲染浅色和深色主题,便于主题切换
250-
- 语言自动检测:
251-
-`class` 属性中提取语言标识(如 `language-java``lang-python`
252-
- 容错处理:
253-
- 渲染失败时保持原始代码块不变
254-
- 默认自动渲染范围:
255-
- 处理器会自动处理以下页面内容并在页面 `head` 注入自定义 CSS 样式:
256-
- 文章内容 (`post`)
257-
- 页面内容 (`page`)
258-
- 性能说明:
259-
- 命中缓存时响应速度极快(微秒级),首次渲染需要 1-3 秒初始化 JS 环境
260-
- 批量处理策略:
261-
- 智能分组:根据 V8 引擎池大小动态分配任务(例如 14 个任务 + 5 个引擎 → 5 组,每组 2-3 个任务)
262-
- 并行执行:多个任务组并行处理,充分利用多核性能
263-
- 批量渲染:同一组内的任务在单个引擎中通过一次 JS 通信批量处理,减少引擎切换开销
264-
- 优先缓存:先检查缓存,只对未命中的请求进行实际渲染
265-
- 缓存策略:
266-
- LRU + TTL 双重策略:最多缓存 10,000 个代码块,每个条目 24 小时自动过期
267-
- 智能去重:相同代码内容+语言+主题的重复渲染会自动去重,避免重复计算
268-
- 缓存键:基于代码内容的 SHA-256 哈希值,避免长代码占用过多内存
269-
270-
#### 配置选项
271-
272-
- 自动渲染: 启用之后会自动渲染文章和单页中的代码块。注:Finder API 渲染不受此配置项影响。
273-
- 自定义注入 CSS 样式:启用自动渲染时将在页面 head 注入样式以优化 Shiki 渲染效果,默认值提供了边距调整/行号显示/基于媒体查询的明暗切换功能。
274-
- 额外注入规则: 指定额外的页面路径规则,支持通配符。
275-
- 默认包含: `/moments/**`, `/docs/**`
276-
- 支持自定义路径,如 `/custom/**`
277-
- 明暗双倍渲染模式切换:
278-
- 单主题模式:
279-
- 主题: 选择单个代码高亮主题
280-
- 双主题模式:
281-
- 亮色主题: 浅色模式使用的主题
282-
- 暗色主题: 深色模式使用的主题
283-
- 亮色主题代码块类名: 浅色代码块的 CSS 类名
284-
- 暗色主题代码块类名: 深色代码块的 CSS 类名
285-
286-
#### 支持的主题
287-
288-
插件内置了 118 个 Shiki 主题,包括:
289-
290-
- GitHub Light/Dark 系列
291-
- One Light/Dark Pro
292-
- Nord, Dracula, Monokai
293-
- Material Theme 系列
294-
- Catppuccin 系列
295-
296-
完整主题列表: 请在 Halo 管理后台的插件设置页面查看所有可用主题。或前往[官方文档](https://shiki.zhcndoc.com/themes)在线预览。
297-
298-
#### 补充说明
299-
300-
- 工作原理:
301-
1. 内容处理阶段:在内容渲染时,处理器会扫描 HTML 中的 `<pre><code>` 结构
302-
2. 语言检测:从 `class` 属性中提取语言标识(如 `language-java``lang-python`
303-
```html
304-
<!-- 标准 Markdown 格式 -->
305-
<pre><code class="language-java">public class Hello { }</code></pre>
306-
307-
<!-- 简写格式 -->
308-
<pre><code class="lang-python">print("Hello World")</code></pre>
309-
310-
<!-- 直接在 pre 标签上指定 -->
311-
<pre class="language-javascript"><code>console.log("Hello");</code></pre>
312-
```
313-
3. 主题应用:根据配置应用相应的 Shiki 主题进行高亮
314-
4. 样式注入:在页面头部注入配置的 CSS
315-
- 错误处理:
316-
- 不支持的语言/主题会被跳过渲染
317-
- 渲染失败时保留原始格式
318-
- 性能说明:
319-
- 使用 V8 引擎池和异步处理,提升渲染效率
320-
- 补充说明:
321-
- 双主题模式会生成两个并列的 div 元素
322-
323238
## Finder API 文档
324239

325240
### 文档类型定义
@@ -643,7 +558,7 @@ extraApiRenderFinder.renderCodeHtml(htmlContent)
643558
**描述**
644559

645560
- 功能特性:
646-
-[处理器文档 - 代码高亮(通过 Shiki.js 渲染)](#代码高亮通过-shikijs-渲染) 中描述的功能特性一致。也受同样的配置项影响。
561+
-[处理器文档 - 代码高亮(通过 Shiki.js 渲染)](#代码高亮处理器) 中描述的功能特性一致。也受同样的配置项影响。
647562

648563
**使用示例**
649564

@@ -657,6 +572,91 @@ extraApiRenderFinder.renderCodeHtml(htmlContent)
657572
</div>
658573
```
659574

575+
## 处理器文档
576+
577+
### 代码高亮处理器
578+
579+
插件提供了自动化的代码高亮处理器,无需在模板中手动调用,即可对文章和页面内容中的代码块进行语法高亮渲染。
580+
581+
此功能通过 Shiki.js 渲染,仅在[全量版](#版本说明)中可用。
582+
583+
#### 特点
584+
585+
- 双主题支持:
586+
- 可同时渲染浅色和深色主题,便于主题切换
587+
- 语言自动检测:
588+
-`class` 属性中提取语言标识(如 `language-java``lang-python`
589+
- 容错处理:
590+
- 渲染失败时保持原始代码块不变
591+
- 默认自动渲染范围:
592+
- 处理器会自动处理以下页面内容并在页面 `head` 注入自定义 CSS 样式:
593+
- 文章内容 (`post`)
594+
- 页面内容 (`page`)
595+
- 性能说明:
596+
- 命中缓存时响应速度极快(微秒级),首次渲染需要 1-3 秒初始化 JS 环境
597+
- 批量处理策略:
598+
- 智能分组:根据 V8 引擎池大小动态分配任务(例如 14 个任务 + 5 个引擎 → 5 组,每组 2-3 个任务)
599+
- 并行执行:多个任务组并行处理,充分利用多核性能
600+
- 批量渲染:同一组内的任务在单个引擎中通过一次 JS 通信批量处理,减少引擎切换开销
601+
- 优先缓存:先检查缓存,只对未命中的请求进行实际渲染
602+
- 缓存策略:
603+
- LRU + TTL 双重策略:最多缓存 10,000 个代码块,每个条目 24 小时自动过期
604+
- 智能去重:相同代码内容+语言+主题的重复渲染会自动去重,避免重复计算
605+
- 缓存键:基于代码内容的 SHA-256 哈希值,避免长代码占用过多内存
606+
607+
#### 配置选项
608+
609+
- 自动渲染: 启用之后会自动渲染文章和单页中的代码块。注:Finder API 渲染不受此配置项影响。
610+
- 自定义注入 CSS 样式:启用自动渲染时将在页面 head 注入样式以优化 Shiki 渲染效果,默认值提供了边距调整/行号显示/基于媒体查询的明暗切换功能。
611+
- 额外注入规则: 指定额外的页面路径规则,支持通配符。
612+
- 默认包含: `/moments/**`, `/docs/**`
613+
- 支持自定义路径,如 `/custom/**`
614+
- 明暗双倍渲染模式切换:
615+
- 单主题模式:
616+
- 主题: 选择单个代码高亮主题
617+
- 双主题模式:
618+
- 亮色主题: 浅色模式使用的主题
619+
- 暗色主题: 深色模式使用的主题
620+
- 亮色主题代码块类名: 浅色代码块的 CSS 类名
621+
- 暗色主题代码块类名: 深色代码块的 CSS 类名
622+
623+
#### 支持的主题
624+
625+
插件内置了 118 个 Shiki 主题,包括:
626+
627+
- GitHub Light/Dark 系列
628+
- One Light/Dark Pro
629+
- Nord, Dracula, Monokai
630+
- Material Theme 系列
631+
- Catppuccin 系列
632+
633+
完整主题列表: 请在 Halo 管理后台的插件设置页面查看所有可用主题。或前往[官方文档](https://shiki.zhcndoc.com/themes)在线预览。
634+
635+
#### 补充说明
636+
637+
- 工作原理:
638+
1. 内容处理阶段:在内容渲染时,处理器会扫描 HTML 中的 `<pre><code>` 结构
639+
2. 语言检测:从 `class` 属性中提取语言标识(如 `language-java``lang-python`
640+
```html
641+
<!-- 标准 Markdown 格式 -->
642+
<pre><code class="language-java">public class Hello { }</code></pre>
643+
644+
<!-- 简写格式 -->
645+
<pre><code class="lang-python">print("Hello World")</code></pre>
646+
647+
<!-- 直接在 pre 标签上指定 -->
648+
<pre class="language-javascript"><code>console.log("Hello");</code></pre>
649+
```
650+
3. 主题应用:根据配置应用相应的 Shiki 主题进行高亮
651+
4. 样式注入:在页面头部注入配置的 CSS
652+
- 错误处理:
653+
- 不支持的语言/主题会被跳过渲染
654+
- 渲染失败时保留原始格式
655+
- 性能说明:
656+
- 使用 V8 引擎池和异步处理,提升渲染效率
657+
- 补充说明:
658+
- 双主题模式会生成两个并列的 div 元素
659+
660660
## 下载和安装
661661

662662
### 稳定版

0 commit comments

Comments
 (0)