plugins: user json based plugins (#1519)

Author: MykolaGolubyev

znai-core/src/main/java/org/testingisdocumenting/znai/extensions/Plugins.java

@@ -23,17 +23,20 @@
 import org.testingisdocumenting.znai.utils.ServiceLoaderUtils;
 
 import java.util.Collection;
+import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.Set;
 
 import static java.util.stream.Collectors.joining;
-import static java.util.stream.Collectors.toMap;
 
 public class Plugins {
     private static final Map<String, Plugin> includePluginsById = discoverIncludePlugins();
     private static final Map<String, Plugin> fencePluginsById = discoverFencePlugins();
     private static final Map<String, Plugin> inlineCodePluginsById = discoverInlinedCodePlugins();
 
+    private static final Set<String> builtInIncludeIds = Set.copyOf(includePluginsById.keySet());
+    private static final Set<String> builtInFenceIds = Set.copyOf(fencePluginsById.keySet());
+
     private static final PluginsTracker pluginsTracker = new PluginsTracker();
 
     public static Map<String, ?> buildStatsMap() {
@@ -74,6 +77,35 @@ public static InlinedCodePlugin inlinedCodePluginById(String id) {
                 pluginsTracker.inlineCodePlugins.createParamsTracker(id));
     }
 
+    public static void registerUserPlugin(Plugin plugin) {
+        if (plugin instanceof IncludePlugin) {
+            registerUserPlugin(includePluginsById, builtInIncludeIds, plugin);
+        } else if (plugin instanceof FencePlugin) {
+            registerUserPlugin(fencePluginsById, builtInFenceIds, plugin);
+        } else {
+            throw new IllegalArgumentException("unsupported plugin type: " + plugin.getClass().getCanonicalName());
+        }
+    }
+
+    public static void removeUserPlugin(String id) {
+        if (builtInIncludeIds.contains(id) || builtInFenceIds.contains(id)) {
+            throw new IllegalStateException("cannot remove built-in plugin <" + id + ">");
+        }
+
+        includePluginsById.remove(id);
+        fencePluginsById.remove(id);
+    }
+
+    private static void registerUserPlugin(Map<String, Plugin> plugins, Set<String> builtInIds, Plugin plugin) {
+        String id = plugin.id();
+        if (builtInIds.contains(id)) {
+            throw new IllegalStateException("plugin with id <" + id + "> is already registered: " +
+                    plugins.get(id).getClass().getCanonicalName());
+        }
+
+        plugins.put(id, plugin);
+    }
+
     private static Plugin pluginById(Map<String, Plugin> plugins, String id) {
         final Plugin plugin = plugins.get(id);
         if (plugin == null) {
@@ -99,10 +131,13 @@ private static Map<String, Plugin> discoverInlinedCodePlugins() {
     private static <E extends Plugin> Map<String, Plugin> discoverPlugins(Class<E> pluginType) {
         final Set<E> list = ServiceLoaderUtils.load(pluginType);
 
-        final Map<String, Plugin> byId = list.stream().collect(toMap(Plugin::id, p -> p));
-        if (byId.size() < list.size()) {
-            throw new IllegalStateException("multiple plugins with the same id are detected. full list: \n" +
-                renderListOfPlugins(list));
+        final Map<String, Plugin> byId = new LinkedHashMap<>();
+        for (E plugin : list) {
+            Plugin prev = byId.put(plugin.id(), plugin);
+            if (prev != null) {
+                throw new IllegalStateException("multiple plugins with the same id are detected. full list: \n" +
+                        renderListOfPlugins(list));
+            }
         }
 
         return byId;

znai-core/src/main/java/org/testingisdocumenting/znai/resources/LocalResourcesResolver.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2026 znai maintainers
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.testingisdocumenting.znai.resources;
+
+import java.nio.file.Path;
+
+public interface LocalResourcesResolver extends ResourcesResolver {
+    void setCurrentFilePath(Path currentFilePath);
+
+    Path getCurrentFilePath();
+}

znai-core/src/main/java/org/testingisdocumenting/znai/resources/MultipleLocalLocationsResourceResolver.java

@@ -27,7 +27,7 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
-public class MultipleLocalLocationsResourceResolver implements ResourcesResolver {
+public class MultipleLocalLocationsResourceResolver implements LocalResourcesResolver {
     private final TableOfContents toc;
     private final Path docRootPath;
     private final List<Path> lookupPaths;
@@ -98,7 +98,13 @@ private Stream<Path> allLocationsStream(String path) {
         return Stream.concat(relativeToCurrent, Stream.concat(absoluteLocation, lookedUpInLocations)).distinct();
     }
 
+    @Override
     public void setCurrentFilePath(Path currentFilePath) {
         this.currentFilePath.set(currentFilePath);
     }
+
+    @Override
+    public Path getCurrentFilePath() {
+        return currentFilePath.get();
+    }
 }

znai-core/src/main/java/org/testingisdocumenting/znai/template/TextTemplate.java

@@ -28,12 +28,13 @@
 import static freemarker.template.Configuration.VERSION_2_3_23;
 
 public class TextTemplate {
+    private static final Configuration SHARED_CONFIGURATION = new Configuration(VERSION_2_3_23);
+
     private final Template template;
 
     public TextTemplate(String templateName, String templateText) {
-        Configuration cfg = new Configuration(VERSION_2_3_23);
         try {
-            template = new Template(templateName, new StringReader(templateText), cfg);
+            template = new Template(templateName, new StringReader(templateText), SHARED_CONFIGURATION);
         } catch (IOException e) {
             throw new RuntimeException(e);
         }

znai-core/src/test/groovy/org/testingisdocumenting/znai/parser/TestResourceResolver.groovy

@@ -17,7 +17,7 @@
 
 package org.testingisdocumenting.znai.parser
 
-import org.testingisdocumenting.znai.resources.ResourcesResolver
+import org.testingisdocumenting.znai.resources.LocalResourcesResolver
 import org.testingisdocumenting.znai.utils.ResourceUtils
 
 import javax.imageio.ImageIO
@@ -26,8 +26,9 @@ import java.nio.file.Path
 import java.nio.file.Paths
 import java.util.stream.Stream
 
-class TestResourceResolver implements ResourcesResolver {
+class TestResourceResolver implements LocalResourcesResolver {
     private Path root
+    private Path currentFilePath
 
     TestResourceResolver(Path root) {
         this.root = root.toAbsolutePath()
@@ -88,4 +89,14 @@ class TestResourceResolver implements ResourcesResolver {
     boolean isLocalFile(String path) {
         return ResourceUtils.resourceStream(path) != null
     }
+
+    @Override
+    void setCurrentFilePath(Path currentFilePath) {
+        this.currentFilePath = currentFilePath
+    }
+
+    @Override
+    Path getCurrentFilePath() {
+        return currentFilePath
+    }
 }

znai-docs/znai/extensions.json

@@ -2,5 +2,6 @@
   "cssResources": ["custom.css", "plugins/javascript/theme-box.css"],
   "jsResources": ["custom.js", "plugins/javascript/theme-box.js"],
   "htmlResources": ["custom.html"],
-  "htmlHeadResources": ["tracking.html"]
+  "htmlHeadResources": ["tracking.html"],
+  "plugins": ["plugins/themed-box-plugin.json", "plugins/custom-fence-block-plugin.json"]
 }