define and implement support for znai extension jars

[antoinell]

Objective of znai extension jars

Java developers should be able to create jar files containing both the Java and Javascript support necessary to render one or several znai plugins.

What are znai plugins

A znai plugin is a particular markdown syntax extension specific to znai.

As an example, the JsonIncludePlugin documented at Json#Title allows to include a json file in a markdown document with this syntax - the parameters between curly braces here are optional.

:include-json: book-store.json {include: "$..book[0,1]", title: "Books"}

znai ships currently with 355 such plugins.

How does znai discover internally such plugins

Using the ServiceLoader API which is part of the JDK ( Java Development Kit ), znai loads the list of available plugins from files packaged in znai's distribution inside META-INF/services. These files are

• org.testingisdocumenting.znai.extensions.fence.FencePlugin
• org.testingisdocumenting.znai.extensions.include.IncludePlugin
• org.testingisdocumenting.znai.extensions.inlinedcode.InlinedCodePlugin

The content of each file is a flat list of fully qualified class names such as org.testingisdocumenting.znai.extensions.json.JsonIncludePlugin.

What is there in the java implementation of a znai plugin

The code of a znai plugin consists of methods listing or consuming the possible parameters of a plugin, and methods used to render the plugin.
The API is different depending on the particular type of plugin.

What would be a znai extension

A znai extension would be a jar file containing

one or several of the files META-INF/services

• org.testingisdocumenting.znai.extensions.fence.FencePlugin
• org.testingisdocumenting.znai.extensions.include.IncludePlugin
• org.testingisdocumenting.znai.extensions.inlinedcode.InlinedCodePlugin

resources :

• META-INF/znai/javascript-files.txt
• META-INF/znai/css-files.txt

The file META-INF/znai/javascript-files.txt would contain a flat list of resources of JavaScript resources to load.

example

META-INF/znai/js/extension1/somename.js
META-INF/zna/js/extension2/somename2.js

When running the maven goals znai:preview or znai:build or the equivalent with the CLI, the generated index page would load the javascript files. The java implementation of the extensions will be loaded by znai the same way that znai loads its own plugins.

[MykolaGolubyev]

Hello!
Thank you for the detailed proposal.

I wonder if Plugin could expose requiredResources method with default implementation that returns empty stream.
Then we can check if the plugin was actually called. There is TrackingPlugin implementation I think. And then only for plugins that actually were used we can add required resources.
I want this to be applied to Mermaid plugin as it adds quite a lot of javascript to the bundle even if not used.
what do you think?

[antoinell]

Let me see how fast I can get something up and running.
We could have the plugins define in java the js/css/... resources that they require but since roll down creates fancy names and that you cannot change these names without breaking the application at runtime in practice we will have to write the exact names of the js resources in another file during the build process.
The requiredResources idea sounds nice though.
It would help me though if we could get a release with the current build system even though mermaid adds a lot of javascript. Is it a huge problem at runtime ? Does the browser get encumbered by the mermaid related javascript for documents which do not contain mermaid diagrams ?