plugins: initial javascript based plugin (#1518)

Author: MykolaGolubyev

znai-core/src/main/java/org/testingisdocumenting/znai/extensions/javascript/JavascriptFunctionIncludePlugin.java

@@ -0,0 +1,88 @@
+/*
+ * 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.extensions.javascript;
+
+import org.testingisdocumenting.znai.core.ComponentsRegistry;
+import org.testingisdocumenting.znai.extensions.PluginParams;
+import org.testingisdocumenting.znai.extensions.PluginResult;
+import org.testingisdocumenting.znai.extensions.include.IncludePlugin;
+import org.testingisdocumenting.znai.parser.ParserHandler;
+import org.testingisdocumenting.znai.search.SearchScore;
+import org.testingisdocumenting.znai.search.SearchText;
+import org.testingisdocumenting.znai.utils.CollectionUtils;
+
+import java.nio.file.Path;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.StringJoiner;
+
+public class JavascriptFunctionIncludePlugin implements IncludePlugin {
+    private String functionName;
+    private Map<String, Object> args;
+
+    @Override
+    public String id() {
+        return "javascript-function";
+    }
+
+    @Override
+    public IncludePlugin create() {
+        return new JavascriptFunctionIncludePlugin();
+    }
+
+    @Override
+    public PluginResult process(ComponentsRegistry componentsRegistry,
+                                ParserHandler parserHandler,
+                                Path markupPath,
+                                PluginParams pluginParams) {
+        functionName = pluginParams.getFreeParam();
+        if (functionName == null || functionName.isEmpty()) {
+            throw new IllegalArgumentException("javascript function name must be provided as a free param," +
+                    " e.g. :include-javascript-function: myFunction");
+        }
+
+        args = pluginParams.getOpts().toMap();
+
+        return PluginResult.docElement("JavascriptFunction", CollectionUtils.createMap(
+                "functionName", functionName,
+                "args", args));
+    }
+
+    @Override
+    public List<SearchText> textForSearch() {
+        StringJoiner joiner = new StringJoiner(" ");
+        joiner.add(functionName);
+        collectSearchableValues(args, joiner);
+
+        return List.of(SearchScore.STANDARD.text(joiner.toString()));
+    }
+
+    private static void collectSearchableValues(Object value, StringJoiner joiner) {
+        if (value == null) {
+            return;
+        }
+
+        if (value instanceof Map) {
+            ((Map<?, ?>) value).values().forEach(v -> collectSearchableValues(v, joiner));
+        } else if (value instanceof Collection) {
+            ((Collection<?>) value).forEach(v -> collectSearchableValues(v, joiner));
+        } else {
+            joiner.add(value.toString());
+        }
+    }
+}

znai-core/src/main/resources/META-INF/services/org.testingisdocumenting.znai.extensions.include.IncludePlugin

@@ -22,3 +22,4 @@ org.testingisdocumenting.znai.extensions.api.ApiParametersIncludePlugin
 org.testingisdocumenting.znai.extensions.toc.PageTocIncludePlugin
 org.testingisdocumenting.znai.extensions.json.JsonIncludePlugin
 org.testingisdocumenting.znai.extensions.ocaml.OcamlCommentIncludePlugin
+org.testingisdocumenting.znai.extensions.javascript.JavascriptFunctionIncludePlugin

znai-core/src/test/groovy/org/testingisdocumenting/znai/extensions/javascript/JavascriptFunctionIncludePluginTest.groovy

@@ -0,0 +1,56 @@
+/*
+ * 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.extensions.javascript
+
+import org.testingisdocumenting.znai.extensions.include.PluginsTestUtils
+import org.testingisdocumenting.znai.search.SearchScore
+import org.junit.Test
+
+import static org.testingisdocumenting.webtau.Matchers.code
+import static org.testingisdocumenting.webtau.Matchers.throwException
+
+class JavascriptFunctionIncludePluginTest {
+    @Test
+    void "should pass function name and args to JavascriptFunction doc element"() {
+        def elements = process('themeBox {title: "hello", size: 50}')
+        elements.should == [[type: 'JavascriptFunction',
+                             functionName: 'themeBox',
+                             args: [title: 'hello', size: 50]]]
+    }
+
+    @Test
+    void "should fail when function name is missing"() {
+        code {
+            process('')
+        } should throwException(~/javascript function name must be provided as a free param/)
+    }
+
+    @Test
+    void "should contribute function name and args values to search text"() {
+        def plugin = PluginsTestUtils.processAndGetIncludePlugin(
+                ':include-javascript-function: themeBox {title: "hello world", count: 42, tags: ["alpha", "beta"]}')
+
+        def searchText = plugin.textForSearch()
+        searchText.size().should == 1
+        searchText[0].score.should == SearchScore.STANDARD
+        searchText[0].text.should == 'themeBox hello world 42 alpha beta'
+    }
+
+    private static List<Map<String, ?>> process(params) {
+        return PluginsTestUtils.processInclude(":include-javascript-function: $params")*.toMap()
+    }
+}

znai-docs/znai/configuration/extensions.md

@@ -0,0 +1,81 @@
+Add `extensions.json` next to your `toc` file to inject custom CSS, JavaScript,
+or HTML into the generated site. This is how you bring in your own stylesheets,
+load scripts used by the [javascript plugin](plugins/javascript-plugin),
+embed tracking snippets, or ship extra static files along with the docs.
+
+```json {title: "extensions.json"}
+{
+  "cssResources": ["custom.css"],
+  "jsResources": ["custom.js"],
+  "htmlResources": ["custom.html"],
+  "htmlHeadResources": ["tracking.html"]
+}
+```
+
+All paths are resolved relative to your documentation root (the directory that
+holds the `toc` file).
+
+# cssResources
+
+List of CSS files to load on every page.
+
+```json
+{
+  "cssResources": ["custom.css", "plugins/javascript/theme-box.css"]
+}
+```
+
+Note: a file named `style.css` placed next to `toc` is picked up automatically,
+no need to list it here. See [Styling](configuration/styling).
+
+# jsResources
+
+List of JavaScript files to load on every page. Use this to register
+custom functions for the [javascript plugin](plugins/javascript-plugin).
+
+```json
+{
+  "jsResources": ["custom.js", "plugins/javascript/theme-box.js"]
+}
+```
+
+# htmlResources
+
+List of HTML snippets injected into the `<body>` of every page — useful for
+widgets, chat bubbles, or any markup that needs to live alongside the rendered
+content.
+
+```json
+{
+  "htmlResources": ["custom.html"]
+}
+```
+
+# htmlHeadResources
+
+List of HTML snippets injected into the `<head>` of every page. Common use
+cases are analytics tags, preconnect hints, or extra `<meta>` entries.
+
+```json
+{
+  "htmlHeadResources": ["tracking.html"]
+}
+```
+
+Note: a file named `tracking.html` placed next to `toc` is picked up
+automatically.
+
+# additionalFilesToDeploy
+
+List of extra files to copy into the deploy output. Use this for assets
+referenced by your custom CSS/JS that znai would not otherwise discover —
+fonts, icons, supporting JSON, and so on.
+
+```json
+{
+  "additionalFilesToDeploy": ["fonts/Inter.woff2", "data/config.json"]
+}
+```
+
+Note: for broader file/directory copying, see
+[additional files](deployment/additional-files).

znai-docs/znai/extensions.json

@@ -1,6 +1,6 @@
 {
-  "cssResources": ["custom.css"],
-  "jsResources": ["custom.js"],
+  "cssResources": ["custom.css", "plugins/javascript/theme-box.css"],
+  "jsResources": ["custom.js", "plugins/javascript/theme-box.js"],
   "htmlResources": ["custom.html"],
   "htmlHeadResources": ["tracking.html"]
 }