Repository: kestra-io/kestra
Issue: Warning on documentation are not rendered 
Labels: bug

see [here](https://kestra.io/plugins/core/tasks/states/io.kestra.core.tasks.states.set)

Issue comments:
would a multiline string work here? if so I'll add a PR

```
@Schema(
    title = "Set a state in the state store.",
    description = """
    Values will be added or modified for a given key:
    * If you provide a new key, the new key will be added
    * If you provide an existing key, the existing value for that key will be overwritten.
    
    ::alert{type="warning"}
    This method is not thread-safe. When many concurrent executions are trying to set a value for the same key, there is no ACID guarantee for such write operations.
    ::
    """
)
```
I think it's unrelated and we only have to remove that [lign](https://github.com/kestra-io/kestra/blob/3e1da9df6783d7b448c5d49556a0c50fba74c5e3/core/src/main/java/io/kestra/core/docs/DocumentationGenerator.java#L264), but seems weird, no need to dig
Thanks. In that case, for now, I'll add a PR to remove those warning boxes, they don't seem to be mission-critical to communicate the intent :) I'll make important parts bold to keep the important message highlighted.
was a good chance to fix wording anyway https://github.com/kestra-io/kestra/pull/1903/files 
@tchiotludo 

> I think it's unrelated and we only have to remove that [lign](https://github.com/kestra-io/kestra/blob/3e1da9df6783d7b448c5d49556a0c50fba74c5e3/core/src/main/java/io/kestra/core/docs/DocumentationGenerator.java#L264), but seems weird, no need to dig

No, if you do this you will avoid displaying it in the UI.

Let me explain what I think happen.
When we move the website to the new framework, the standard markdown alert block `::: warning [...] :::` was not supported anymore so we replace them with `::alert{type=warning} [...] :: `
Then this new format didn't work on the UI markdown view, so we replace them back from the API to the standard makrdown alert.
It works.
But at some point, it stop working on the website, I have the feeling that the website which previously load the content from the documentation generation commands now load it from the plugin API. If it's the case the replacement should move to the UI (or be done only based on a boolean).

Removing the replacement will make the doc good on the website but wrong on the UI.
we just need to align them (ui & website) to have a common language 
WDYT about just not using alert/info blocks in the plugin docs? this might be a lazy approach but they are really not needed. We can highlight something in bold to highlight important information or add a ⚠️ emoji 

in the other PR I removed all alerts from plugins, they are no more left if https://github.com/kestra-io/kestra/pull/1903 gets merged and the problem would be solved

> we just need to align them (ui & website) to have a common language

It would be better, I tried to support standard markdown alert bloc on the website without success that's why I ends up with this hack.

We use this kind of block for deprecated task so it's important to have them @anna-geller 
gotcha - I'll remove "closes" mark then

Pull request review comments:

Patch that resolved the issue:
diff --git a/core/src/main/java/io/kestra/core/docs/DocumentationGenerator.java b/core/src/main/java/io/kestra/core/docs/DocumentationGenerator.java
index fc48b92d46..59b9f53de5 100644
--- a/core/src/main/java/io/kestra/core/docs/DocumentationGenerator.java
+++ b/core/src/main/java/io/kestra/core/docs/DocumentationGenerator.java
@@ -260,10 +260,6 @@ public static <T> String render(String templateName, Map<String, Object> vars) t
         Pattern pattern = Pattern.compile("`\\{\\{(.*?)\\}\\}`", Pattern.MULTILINE);
         renderer = pattern.matcher(renderer).replaceAll("<code v-pre>{{ $1 }}</code>");
 
-        // alert
-        renderer = renderer.replaceAll("\n::alert\\{type=\"(.*)\"\\}\n", "\n::: $1\n");
-        renderer = renderer.replaceAll("\n::\n", "\n:::\n");
-
         return renderer;
     }
 }
diff --git a/webserver/src/main/java/io/kestra/webserver/controllers/PluginController.java b/webserver/src/main/java/io/kestra/webserver/controllers/PluginController.java
index 2857a56544..a9be02ca7e 100644
--- a/webserver/src/main/java/io/kestra/webserver/controllers/PluginController.java
+++ b/webserver/src/main/java/io/kestra/webserver/controllers/PluginController.java
@@ -10,6 +10,7 @@
 import io.kestra.core.plugins.RegisteredPlugin;
 import io.kestra.core.services.PluginService;
 import io.micronaut.cache.annotation.Cacheable;
+import io.micronaut.core.annotation.NonNull;
 import io.micronaut.http.HttpResponse;
 import io.micronaut.http.MutableHttpResponse;
 import io.micronaut.http.annotation.Controller;
@@ -95,7 +96,7 @@ public MutableHttpResponse<DocumentationWithSchema> inputSchemas(
 
         return HttpResponse.ok()
             .body(new DocumentationWithSchema(
-                DocumentationGenerator.render(classInputDocumentation),
+                alertReplacement(DocumentationGenerator.render(classInputDocumentation)),
                 new Schema(
                     classInputDocumentation.getPropertiesSchema(),
                     null,
@@ -164,7 +165,7 @@ public HttpResponse<DocumentationWithSchema> pluginDocumentation(
             allProperties
         );
 
-        var doc = DocumentationGenerator.render(classPluginDocumentation);
+        var doc = alertReplacement(DocumentationGenerator.render(classPluginDocumentation));
 
         return HttpResponse.ok()
             .body(new DocumentationWithSchema(
@@ -196,4 +197,10 @@ protected ClassPluginDocumentation<?> pluginDocumentation(List<RegisteredPlugin>
 
         return ClassPluginDocumentation.of(jsonSchemaGenerator, registeredPlugin, cls, allProperties ? null : baseCls);
     }
+
+    private String alertReplacement(@NonNull String original) {
+        // we need to replace the NuxtJS ::alert{type=} :: with the more standard ::: warning :::
+        return original.replaceAll("\n::alert\\{type=\"(.*)\"\\}\n", "\n::: $1\n")
+            .replaceAll("\n::\n", "\n:::\n");
+    }
 }


Test patch:
diff --git a/core/src/test/java/io/kestra/core/docs/DocumentationGeneratorTest.java b/core/src/test/java/io/kestra/core/docs/DocumentationGeneratorTest.java
index 3629dd2f48..5ef990b854 100644
--- a/core/src/test/java/io/kestra/core/docs/DocumentationGeneratorTest.java
+++ b/core/src/test/java/io/kestra/core/docs/DocumentationGeneratorTest.java
@@ -7,6 +7,7 @@
 import io.kestra.core.tasks.debugs.Return;
 import io.kestra.core.tasks.flows.Dag;
 import io.kestra.core.tasks.flows.Flow;
+import io.kestra.core.tasks.states.Set;
 import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
 import jakarta.inject.Inject;
 import org.junit.jupiter.api.Test;
@@ -131,6 +132,20 @@ void echo() throws IOException {
         assertThat(render, containsString("- \uD83D\uDD12 Deprecated"));
     }
 
+    @Test
+    void state() throws IOException {
+        PluginScanner pluginScanner = new PluginScanner(ClassPluginDocumentationTest.class.getClassLoader());
+        RegisteredPlugin scan = pluginScanner.scan();
+        Class<Set> set = scan.findClass(Set.class.getName()).orElseThrow();
+
+        ClassPluginDocumentation<? extends Task> doc = ClassPluginDocumentation.of(jsonSchemaGenerator, scan, set, Task.class);
+
+        String render = DocumentationGenerator.render(doc);
+
+        assertThat(render, containsString("Set"));
+        assertThat(render, containsString("::alert{type=\"warning\"}\n"));
+    }
+
     @Test
     void pluginDoc() throws Exception {
         PluginScanner pluginScanner = new PluginScanner(ClassPluginDocumentationTest.class.getClassLoader());
diff --git a/webserver/src/test/java/io/kestra/webserver/controllers/PluginControllerTest.java b/webserver/src/test/java/io/kestra/webserver/controllers/PluginControllerTest.java
index 7d438002b9..b325ed2780 100644
--- a/webserver/src/test/java/io/kestra/webserver/controllers/PluginControllerTest.java
+++ b/webserver/src/test/java/io/kestra/webserver/controllers/PluginControllerTest.java
@@ -108,6 +108,21 @@ void docs() throws URISyntaxException {
         });
     }
 
+    @Test
+    void docWithAlert() throws URISyntaxException {
+        Helpers.runApplicationContext((applicationContext, embeddedServer) -> {
+            RxHttpClient client = RxHttpClient.create(embeddedServer.getURL());
+
+            DocumentationWithSchema doc = client.toBlocking().retrieve(
+                HttpRequest.GET("/api/v1/plugins/io.kestra.core.tasks.states.Set"),
+                DocumentationWithSchema.class
+            );
+
+            assertThat(doc.getMarkdown(), containsString("io.kestra.core.tasks.states.Set"));
+            assertThat(doc.getMarkdown(), containsString("::: warning\n"));
+        });
+    }
+
 
     @SuppressWarnings("unchecked")
     @Test