JSON and template driven user defined plugins ```custom fence block title greet js function greet name console log hello name greet world ``` include themed box Capacity approaching threshold severity warning tags observability

List each plugin config under in extensions json Paths resolve relative to your documentation root like and plugins cssResources jsResources

is what you type after or as the fence language A config registers exactly one role if you need both an include and a fence variant of the same template write two configs that point at the same they take different special arguments vs anyway id themed box type include template plugins themed box plugin ftl arguments freeForm required true severity type string required true limitValuesTo info success warning tags type list of string limitValuesTo $plugins themed box tags json id include ftl freeForm fenceContent

Each entry under defines one parameter callers can pass or defaults to optional an inline array of allowed values or a reference to a JSON array file Omit it to accept any value of Unknown arguments type mismatches and values outside all fail the build with the same error reporting as built in plugins Limit Values From A File Point at a JSON array when the allowed set is owned elsewhere a team wide tag list regional names severity levels shared with another tool The path resolves relative to the plugin config first then falls back to znai s resource resolver so it works next to the next to on the lookup path or packaged in a jar arguments type number string list of number list of string list required false limitValuesTo $path to file json type limitValuesTo limitValuesTo demo theme observability latency deployment json toc

Two argument names are reserved the text right after the plugin id and before Use it for the single primary input a message an entity name a URL No needed it s always raw text Set to fail the build when the caller omits it defaults to optional the body of a fenced block only meaningful for fence plugins No needed the raw text is passed through untouched Always present by construction Both names skip the regular type validation freeForm type required true fenceContent type limitValuesTo

Templates are rendered with FreeMarker same as include template Every argument including and is a top level variable The output can be any markdown znai understands prose fenced code calls to other plugins This example wraps include javascript function and forwards and shrinking the surface area writers need to remember freeForm fenceContent include javascript function themeBox label $ freeForm severity $ severity tags <#list tags as tag> $ tag <#sep> < #list> title $ severity upper_case box title from template severity tags

themeBox Deploy finished in 4 minutes flat success deployment latency SUCCESS box title from template themeBox Capacity approaching threshold warning observability WARNING box title from template Omit a required argument or pass a tag missing from and the build stops with a descriptive error Arguments without accept any value of the declared handy for free text titles or counts include themed box Deploy finished in 4 minutes flat severity success tags deployment latency include themed box Capacity approaching threshold severity warning tags observability themed box tags json limitValuesTo type

Set to register a fenced block plugin The body comes through the special argument FreeMarker s escapes the body so it stays a valid JSON string when handed to another plugin s params block multi line bodies quotes and backslashes survive intact The fence marker is the plugin id not a language hint themeBox greet js function greet name console log hello name greet world The body reaches verbatim as the arg Any fence plugin can use this pattern to forward content to diagram renderers code annotators or other include plugins type fence fenceContent id custom fence block type fence template plugins custom fence block plugin ftl arguments fenceContent title type string include javascript function themeBox title $ title code snippet snippet $ fenceContent json_string json_string ```custom fence block title greet js function greet name console log hello name greet world ``` include javascript function snippet

The plugin config the template and any referenced files are treated as auxiliary files Edit any of them and znai regenerates the affected pages same contract as template includes and snippet files limitValuesTo

Values you pass to the plugin flow into znai s local search via the inner plugin s No extra work to make pages searchable by parameter content textForSearch

User defined plugins fit when you keep pasting the same include block with only a few values changed writers should pick from a constrained set an enum like a tag registry a snippet spans multiple plugins and you want one entry point that composes them consistently If the reuse is purely structural and needs no validation include template is enough on its own severity