Add language exclusion support with explicit CSS overrides (#27)

Copilot · web-flow · commit dc5b3bcd79ff · 2026-02-10T08:43:05.000Z
Implements language exclusion for code blocks (e.g., mermaid, plantuml) to enable external rendering libraries. Without this, all code blocks get Shiki-wrapped and blurred, breaking diagram renderers. ## Changes ### Backend (Java) - **ShikiBasicConfig**: Added `excludedLanguages` configuration field - **ShikiPreTagProcessor**: Skip wrapping code blocks matching excluded languages (case-insensitive, supports `language-*` and `lang-*` prefixes) - **Constants**: Changed from static CSS to dynamic generation via `generatePreStyle(List<String>)` that applies blur universally then overrides for excluded languages: ```css pre:has(code) { filter: blur(10px); } pre:has(> code[class*="language-mermaid"]) { filter: none; } ``` - **ShikiHeadProcessor**: Convert excluded languages list to JSON array and pass to frontend ### Frontend (TypeScript) - **theme-lib/src/index.ts**: Added `extractLanguageCode()` and `shouldExclude()` helpers; updated `renderCodeBlock()` to accept optional `excludedLanguages` parameter and skip wrapping excluded code blocks ### Configuration - **settings.yaml**: Added multi-select field with common diagram languages (mermaid, plantuml, d2, graphviz, abc) ## Approach Replaced wrapper-based CSS selector (`shiki-code pre:has(code)`) with explicit attribute-based exclusions (`pre:has(> code[class*="language-mermaid"])`). This makes excluded languages visible in CSS and works independently of DOM structure. Frontend now mirrors backend exclusion logic, ensuring consistent behavior for extra path patterns (`/moments/**`, `/docs/**`) where backend processing doesn't run. ## Example ```yaml # Configuration excludedLanguages: - mermaid - plantuml ``` ```html  <pre><code class="language-mermaid">graph TD; A-->B;</code></pre>  <shiki-code> <pre><code class="language-javascript">const x = 1;</code></pre> </shiki-code> ```  <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>【新特性建议】高亮语言排除选项，例如排除 mermaid / plantuml</issue_title> > <issue_description>当使用 mermaid.js 相关的库渲染时，例如 [文本绘图插件](https://github.com/halo-sigs/plugin-text-diagram) 需要 mermaid 代码块元素没被其他 js 库进行过处理。否则，就会无法被正确渲染。 > > 其实前端的话，要排除 mermaid 高亮可以不需要 shiki 插件支持，只需要在编辑器使用 MarkdownIt 解析器渲染的时候，自定义 mermaid 代码块渲染的 html 标签使其不被 `<pre>` 标签包裹或者自定义 div 类名即可，这个在编辑器里就可以实现，目前也是如此实现的。 > > 但是，如果在编辑器里添加了 mermaid 代码块自定义的 html 转换逻辑，例如转换成 `<div class="language-mermaid">...` 这样的元素，而前端却没有对应的插件或 js 对相应 html 元素对其进行渲染就会怪怪的，在前端既不会渲染为对应的图，也不会以原始代码块的样式展示（因为原始代码块处理的选择器一般为 `pre>code`），而是光秃秃的 div 纯文本。 > 换言之，这种编辑器对 Markdown 代码块的自定义 HTML 转换逻辑，是需要对应前端渲染库支持的，两者是耦合的。 > > 然而，用 shiki 进行高亮语言排除会更加便捷。当没有插件或 js 渲染库支持时，就使用默认代码块渲染逻辑；当我们选择插件或 js 渲染库支持特定代码块时，我们在 shiki 中排除相应的高亮语言即可，这样两者就是解耦的。 > > 希望能考虑一下，谢谢大佬🙏 > > </issue_description> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > </comments> > </details>  - Fixes #26  --- ✨ Let Copilot coding agent [set things up for you](https://github.com/halo-sigs/plugin-shiki/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.
diff --git a/README.md b/README.md
@@ -34,9 +34,10 @@
 1. 基本设置
    1. 启用主题侧渲染： 关闭之后将不会在网站前台执行代码高亮渲染，适用于主题已经提供了代码高亮渲染的场景。
    2. 额外渲染规则：如果你想渲染其他页面中的代码块，可以在这里设置路径规则。
-   3. 风格：可选简单和 Mac 窗口，未来会提供更多 UI 风格。
-   4. 亮色主题：在主题的亮色模式下的代码高亮风格。
-   5. 暗色主题：在主题的暗色模式下的代码高亮风格，非必填，如果不填写则使用亮色主题。
+   3. 排除语言：排除指定语言的代码块不进行 Shiki 高亮渲染，适用于需要其他插件处理的特定语言（如 mermaid、plantuml 等）。排除的代码块将保留原始的 pre>code 结构，不被 shiki-code 元素包裹，便于其他 JavaScript 库或插件进行处理。
+   4. 风格：可选简单和 Mac 窗口，未来会提供更多 UI 风格。
+   5. 亮色主题：在主题的亮色模式下的代码高亮风格。
+   6. 暗色主题：在主题的暗色模式下的代码高亮风格，非必填，如果不填写则使用亮色主题。
 2. 编辑器设置
    1. 高亮主题：为 Halo 编辑器设置代码高亮风格。
 
diff --git a/src/main/java/run/halo/shiki/Constants.java b/src/main/java/run/halo/shiki/Constants.java
@@ -1,12 +1,41 @@
 package run.halo.shiki;
 
+import java.util.List;
+
 public class Constants {
-    static String PRE_STYLE = """
-            <style class="pjax" data-pjax>
-            pre:has(code) {
-                filter: blur(10px) !important;
-                padding: 1rem !important;
+    /**
+     * Generate CSS style to blur code blocks before rendering, with exceptions for excluded languages.
+     * 
+     * @param excludedLanguages list of language codes to exclude from blur effect (e.g., mermaid, plantuml)
+     * @return CSS style string wrapped in style tags
+     */
+    static String generatePreStyle(List<String> excludedLanguages) {
+        StringBuilder style = new StringBuilder();
+        style.append("<style class=\"pjax\" data-pjax>\n");
+        style.append("pre:has(code) {\n");
+        style.append("    filter: blur(10px) !important;\n");
+        style.append("    padding: 1rem !important;\n");
+        style.append("}\n");
+        
+        // Add CSS rules to remove blur for excluded languages
+        if (excludedLanguages != null && !excludedLanguages.isEmpty()) {
+            for (String lang : excludedLanguages) {
+                // Support both "language-" and "lang-" prefixes
+                style.append("pre:has(> code[class*=\"language-").append(lang).append("\"]),\n");
+                style.append("pre:has(> code[class*=\"lang-").append(lang).append("\"]) {\n");
+                style.append("    filter: none !important;\n");
+                style.append("}\n");
             }
-            </style>
-        """;
+        }
+        
+        style.append("</style>");
+        return style.toString();
+    }
+    
+    /**
+     * Deprecated: Use generatePreStyle(List<String>) instead.
+     * Kept for backward compatibility.
+     */
+    @Deprecated
+    static String PRE_STYLE = generatePreStyle(null);
 }
diff --git a/src/main/java/run/halo/shiki/ShikiBasicConfig.java b/src/main/java/run/halo/shiki/ShikiBasicConfig.java
@@ -19,4 +19,12 @@ public class ShikiBasicConfig {
     private String darkTheme;
 
     private String fontSize;
+
+    /**
+     * List of language codes to exclude from Shiki highlighting.
+     * Code blocks with these languages will maintain their original pre>code structure
+     * and can be processed by other plugins or JavaScript libraries.
+     * Examples: mermaid, plantuml, d2, graphviz
+     */
+    private List<String> excludedLanguages;
 }
diff --git a/src/main/java/run/halo/shiki/ShikiHeadProcessor.java b/src/main/java/run/halo/shiki/ShikiHeadProcessor.java
@@ -91,7 +91,18 @@ private String shikiExtraScript(ShikiBasicConfig basicConfig) {
         properties.setProperty("variant", basicConfig.getVariant());
         properties.setProperty("fontSize", basicConfig.getFontSize());
         properties.setProperty("version", pluginContext.getVersion());
-        properties.setProperty("style", Constants.PRE_STYLE);
+        properties.setProperty("style", Constants.generatePreStyle(basicConfig.getExcludedLanguages()));
+        
+        // Convert excludedLanguages list to JSON array string
+        String excludedLanguagesJson = "[]";
+        if (basicConfig.getExcludedLanguages() != null && !basicConfig.getExcludedLanguages().isEmpty()) {
+            excludedLanguagesJson = "[" + String.join(",", 
+                basicConfig.getExcludedLanguages().stream()
+                    .map(lang -> "'" + lang + "'")
+                    .toList()
+            ) + "]";
+        }
+        properties.setProperty("excludedLanguages", excludedLanguagesJson);
 
         return PROPERTY_PLACEHOLDER_HELPER.replacePlaceholders("""
             ${style}
@@ -102,15 +113,17 @@ private String shikiExtraScript(ShikiBasicConfig basicConfig) {
                     lightTheme: '${lightTheme}',
                     darkTheme: '${darkTheme}',
                     variant: '${variant}',
-                    fontSize: '${fontSize}'
+                    fontSize: '${fontSize}',
+                    excludedLanguages: ${excludedLanguages}
                 });
             })
             window.addEventListener('pjax:complete', () => {
                 renderCodeBlock({
                     lightTheme: '${lightTheme}',
                     darkTheme: '${darkTheme}',
                     variant: '${variant}',
-                    fontSize: '${fontSize}'
+                    fontSize: '${fontSize}',
+                    excludedLanguages: ${excludedLanguages}
                 });
             });
             </script>
diff --git a/src/main/java/run/halo/shiki/ShikiPostContentHandler.java b/src/main/java/run/halo/shiki/ShikiPostContentHandler.java
@@ -36,6 +36,7 @@ private static void processPreTag(PostContentContext contentContext,
         ShikiBasicConfig basicConfig) {
         var processedContent =
             ShikiPreTagProcessor.process(contentContext.getContent(), basicConfig);
-        contentContext.setContent(Constants.PRE_STYLE + processedContent);
+        var preStyle = Constants.generatePreStyle(basicConfig.getExcludedLanguages());
+        contentContext.setContent(preStyle + processedContent);
     }
 }
diff --git a/src/main/java/run/halo/shiki/ShikiPreTagProcessor.java b/src/main/java/run/halo/shiki/ShikiPreTagProcessor.java
@@ -4,6 +4,7 @@
 import org.jsoup.nodes.Document;
 import org.jsoup.nodes.Element;
 import org.jsoup.select.Elements;
+import java.util.List;
 
 public class ShikiPreTagProcessor {
     static String process(String content, ShikiBasicConfig basicConfig) {
@@ -14,6 +15,12 @@ static String process(String content, ShikiBasicConfig basicConfig) {
 
         // Process each pre element
         for (Element preElement : preElements) {
+            Element codeElement = preElement.selectFirst("code");
+            if (codeElement != null && shouldExclude(codeElement, basicConfig.getExcludedLanguages())) {
+                // Skip processing for excluded languages
+                continue;
+            }
+
             Element shikiCodeElement = new Element("shiki-code")
                 .attr("variant", basicConfig.getVariant())
                 .attr("light-theme", basicConfig.getLightTheme())
@@ -28,4 +35,39 @@ static String process(String content, ShikiBasicConfig basicConfig) {
 
         return doc.body().html();
     }
+
+    /**
+     * Check if the code element's language should be excluded from processing
+     */
+    private static boolean shouldExclude(Element codeElement, List<String> excludedLanguages) {
+        if (excludedLanguages == null || excludedLanguages.isEmpty()) {
+            return false;
+        }
+
+        String languageCode = extractLanguageCode(codeElement);
+        if (languageCode == null) {
+            return false;
+        }
+
+        // Check if the language is in the exclusion list (case-insensitive)
+        return excludedLanguages.stream()
+            .anyMatch(excluded -> excluded.equalsIgnoreCase(languageCode));
+    }
+
+    /**
+     * Extract language code from code element's class attribute
+     */
+    private static String extractLanguageCode(Element codeElement) {
+        String[] supportedPrefixes = {"language-", "lang-"};
+        
+        for (String className : codeElement.classNames()) {
+            for (String prefix : supportedPrefixes) {
+                if (className.startsWith(prefix)) {
+                    return className.substring(prefix.length()).toLowerCase();
+                }
+            }
+        }
+        
+        return null;
+    }
 }
diff --git a/src/main/java/run/halo/shiki/ShikiSinglePageContentHandler.java b/src/main/java/run/halo/shiki/ShikiSinglePageContentHandler.java
@@ -36,6 +36,7 @@ private static void processPreTag(SinglePageContentContext contentContext,
         ShikiBasicConfig basicConfig) {
         var processedContent =
             ShikiPreTagProcessor.process(contentContext.getContent(), basicConfig);
-        contentContext.setContent(Constants.PRE_STYLE + processedContent);
+        var preStyle = Constants.generatePreStyle(basicConfig.getExcludedLanguages());
+        contentContext.setContent(preStyle + processedContent);
     }
 }
diff --git a/src/main/resources/extensions/settings.yaml b/src/main/resources/extensions/settings.yaml
@@ -33,6 +33,29 @@ spec:
               value: /moments/**
             - label: Docsme 文档（/docs/**）
               value: /docs/**
+        - $formkit: select
+          label: 排除语言
+          if: $get(enabled).value
+          name: excludedLanguages
+          id: excludedLanguages
+          key: excludedLanguages
+          allowCreate: true
+          searchable: true
+          clearable: true
+          autoSelect: false
+          multiple: true
+          help: 排除指定语言的代码块不进行 Shiki 高亮渲染，适用于需要其他插件处理的特定语言（如 mermaid、plantuml 等）。排除的代码块将保留原始的 pre>code 结构，不被 shiki-code 元素包裹。
+          options:
+            - label: Mermaid
+              value: mermaid
+            - label: PlantUML
+              value: plantuml
+            - label: D2
+              value: d2
+            - label: Graphviz
+              value: graphviz
+            - label: ABC 乐谱
+              value: abc
         - $formkit: select
           if: $get(enabled).value
           name: variant
diff --git a/src/test/java/run/halo/shiki/ConstantsTest.java b/src/test/java/run/halo/shiki/ConstantsTest.java
@@ -0,0 +1,116 @@
+package run.halo.shiki;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Test for {@link Constants}
+ */
+class ConstantsTest {
+
+    @Test
+    void shouldGeneratePreStyleWithoutExcludedLanguages() {
+        String style = Constants.generatePreStyle(null);
+        
+        // Should contain pre:has(code) selector that applies to all code blocks
+        assertTrue(style.contains("pre:has(code)"),
+            "Style should contain 'pre:has(code)' selector");
+        
+        // Should contain the blur filter
+        assertTrue(style.contains("filter: blur(10px)"),
+            "Style should contain blur filter");
+        
+        // Should be wrapped in style tags
+        assertTrue(style.contains("<style") && style.contains("</style>"),
+            "Style should be wrapped in style tags");
+        
+        // Should not contain any language-specific exclusions
+        assertFalse(style.contains("language-mermaid"),
+            "Should not contain language-specific rules when no exclusions");
+    }
+
+    @Test
+    void shouldGeneratePreStyleWithExcludedLanguages() {
+        List<String> excludedLanguages = List.of("mermaid", "plantuml");
+        String style = Constants.generatePreStyle(excludedLanguages);
+        
+        // Should contain base blur rule
+        assertTrue(style.contains("pre:has(code)"),
+            "Style should contain base pre:has(code) selector");
+        assertTrue(style.contains("filter: blur(10px)"),
+            "Style should contain blur filter");
+        
+        // Should contain exclusion rules for mermaid
+        assertTrue(style.contains("language-mermaid"),
+            "Style should contain language-mermaid selector");
+        assertTrue(style.contains("lang-mermaid"),
+            "Style should contain lang-mermaid selector");
+        
+        // Should contain exclusion rules for plantuml
+        assertTrue(style.contains("language-plantuml"),
+            "Style should contain language-plantuml selector");
+        assertTrue(style.contains("lang-plantuml"),
+            "Style should contain lang-plantuml selector");
+        
+        // Exclusion rules should set filter to none (1 per language, not per prefix)
+        int filterNoneCount = countOccurrences(style, "filter: none");
+        assertEquals(2, filterNoneCount, 
+            "Should have 2 'filter: none' rules (1 per language, covering both prefixes)");
+    }
+
+    @Test
+    void shouldGeneratePreStyleWithSingleExcludedLanguage() {
+        List<String> excludedLanguages = List.of("mermaid");
+        String style = Constants.generatePreStyle(excludedLanguages);
+        
+        // Should contain exclusion rules for mermaid only
+        assertTrue(style.contains("language-mermaid"),
+            "Style should contain language-mermaid selector");
+        assertTrue(style.contains("lang-mermaid"),
+            "Style should contain lang-mermaid selector");
+        
+        // Should not contain plantuml
+        assertFalse(style.contains("plantuml"),
+            "Style should not contain plantuml when not excluded");
+        
+        // Should have 1 filter:none rule (covering both prefixes)
+        int filterNoneCount = countOccurrences(style, "filter: none");
+        assertEquals(1, filterNoneCount,
+            "Should have 1 'filter: none' rule for single language");
+    }
+
+    @Test
+    void shouldGeneratePreStyleWithEmptyExcludedList() {
+        String style = Constants.generatePreStyle(List.of());
+        
+        // Should work same as null
+        assertTrue(style.contains("pre:has(code)"));
+        assertTrue(style.contains("filter: blur(10px)"));
+        assertFalse(style.contains("filter: none"),
+            "Should not contain filter:none when exclusion list is empty");
+    }
+
+    @Test
+    void preStyleShouldHaveCorrectStructure() {
+        String style = Constants.generatePreStyle(null);
+        
+        // Verify it's a valid style tag with pjax class
+        assertTrue(style.contains("class=\"pjax\""),
+            "Style should have pjax class for compatibility");
+        assertTrue(style.contains("data-pjax"),
+            "Style should have data-pjax attribute");
+    }
+    
+    private int countOccurrences(String str, String substring) {
+        int count = 0;
+        int index = 0;
+        while ((index = str.indexOf(substring, index)) != -1) {
+            count++;
+            index += substring.length();
+        }
+        return count;
+    }
+}
diff --git a/src/test/java/run/halo/shiki/ShikiPreTagProcessorTest.java b/src/test/java/run/halo/shiki/ShikiPreTagProcessorTest.java
diff --git a/theme-lib/src/index.ts b/theme-lib/src/index.ts

Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,7 @@ private static void processPreTag(PostContentContext contentContext,`
`36`	`36`	`ShikiBasicConfig basicConfig) {`
`37`	`37`	`var processedContent =`
`38`	`38`	`ShikiPreTagProcessor.process(contentContext.getContent(), basicConfig);`
`39`		`- contentContext.setContent(Constants.PRE_STYLE + processedContent);`
	`39`	`+ var preStyle = Constants.generatePreStyle(basicConfig.getExcludedLanguages());`
	`40`	`+ contentContext.setContent(preStyle + processedContent);`
`40`	`41`	`}`
`41`	`42`	`}`