Merge pull request #168 from zeldigas/feature/GH-162_kroki_asciidoc

Kroki for asciidoc

CHANGELOG.md

@@ -10,6 +10,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ### Added
 
 - Check for conflict of published page with pages parent (#142)
+- Support for Kroki in asciidoc files via `kroki-extension` (#162)
 
 ### Changed
 

convert/pom.xml

@@ -99,6 +99,12 @@
             <version>${asciidoctorj-diagram.version}</version>
             <scope>runtime</scope>
         </dependency>
+        <dependency>
+            <groupId>com.github.zeldigas.confluence</groupId>
+            <artifactId>gem-kroki</artifactId>
+            <version>1.0.0</version>
+            <scope>runtime</scope>
+        </dependency>
         <!--common libraries-->
 
         <dependency>

convert/src/test/kotlin/com/github/zeldigas/text2confl/convert/asciidoc/RenderingOfDiagramsTest.kt

@@ -1,7 +1,11 @@
 package com.github.zeldigas.text2confl.convert.asciidoc
 
+import assertk.all
 import assertk.assertThat
+import assertk.assertions.endsWith
+import assertk.assertions.hasSize
 import assertk.assertions.isEqualTo
+import assertk.assertions.startsWith
 import com.github.zeldigas.text2confl.convert.Attachment
 import com.github.zeldigas.text2confl.convert.AttachmentCollector
 import com.github.zeldigas.text2confl.convert.AttachmentsRegistry
@@ -16,7 +20,7 @@ import kotlin.io.path.div
 internal class RenderingOfDiagramsTest : RenderingTestBase() {
 
     @Test
-    fun `Code block is replaced with image for registered diagram generator`(@TempDir tempDir: Path) {
+    fun `Code block is replaced with image for registered asciidoc diagram generator`(@TempDir tempDir: Path) {
         val parser = AsciidocParser(
             AsciidoctorConfiguration(
                 workdir = tempDir.resolve("out").also { it.createDirectories() },
@@ -66,4 +70,63 @@ internal class RenderingOfDiagramsTest : RenderingTestBase() {
             """.trimIndent()
             )
     }
+
+    @Test
+    fun `Code block is replaced with image for registered kroki diagram generator`(@TempDir tempDir: Path) {
+        val parser = AsciidocParser(
+            AsciidoctorConfiguration(
+                workdir = tempDir.resolve("out").also { it.createDirectories() },
+                libsToLoad = listOf("asciidoctor-kroki"),
+                loadBundledMacros = false,
+                attributes = mapOf(
+                    "kroki-fetch-diagram" to "true",
+                    "outdir" to (tempDir / "out").toString(),
+                    "imagesoutdir" to (tempDir / "out").toString()
+                )
+            )
+        )
+        val registry = AttachmentsRegistry()
+        val result = toHtml(
+            """
+            [plantuml,auth-protocol,png]
+            ....
+            Alice -> Bob: Authentication Request
+            Bob --> Alice: Authentication Response
+            
+            Alice -> Bob: Another authentication Request
+            Alice <-- Bob: another authentication Response
+            ....
+            """.trimIndent(),
+            attachmentsCollector = AsciidocAttachmentCollector(
+                tempDir / "test.adoc", AttachmentCollector(
+                    ReferenceProvider.fromDocuments(
+                        tempDir, mapOf(
+                            tempDir / "test.adoc" to PageHeader("Test", emptyMap())
+                        )
+                    ),
+                    registry
+                ),
+                tempDir / "out"
+            ),
+            parser = parser
+        )
+
+        println(result)
+
+        assertThat(registry.collectedAttachments).hasSize(1)
+
+        val (key, attachment) = registry.collectedAttachments.entries.first()
+        assertThat(key).all {
+            startsWith("auth-protocol")
+            endsWith(".png")
+        }
+        assertThat(attachment).isEqualTo(
+            Attachment.fromLink(key, tempDir / "out" / key)
+        )
+        assertThat(result).isEqualToConfluenceFormat(
+            """
+            <p><ac:image ac:alt="auth-protocol"><ri:attachment ri:filename="$key" /></ac:image></p>
+            """.trimIndent()
+        )
+    }
 }

core/src/main/kotlin/com/github/zeldigas/text2confl/core/config/DirectoryConfig.kt

@@ -4,6 +4,7 @@ import com.github.zeldigas.text2confl.convert.EditorVersion
 import com.github.zeldigas.text2confl.convert.asciidoc.AsciidoctorConfiguration
 import com.github.zeldigas.text2confl.convert.markdown.*
 import com.github.zeldigas.text2confl.core.upload.ChangeDetector
+import java.net.URI
 import java.nio.file.Path
 import kotlin.io.path.Path
 import kotlin.io.path.createTempDirectory
@@ -95,23 +96,42 @@ data class AsciidocParams(
     val attributes: Map<String, Any?> = emptyMap(),
     val tempDir: Boolean = false,
     val baseDir: String = ".asciidoc",
+    val kroki: KrokiDiagramsParameters = KrokiDiagramsParameters()
 ) {
     fun toConfig(docsDir: Path): AsciidoctorConfiguration {
         val baseDir = if (tempDir) createTempDirectory() else docsDir / baseDir
+
         return AsciidoctorConfiguration(
             libsToLoad = gems + diagrams.let {
                 when (it) {
                     AsciidocDiagrams.None -> emptyList()
                     AsciidocDiagrams.Diagrams -> listOf("asciidoctor-diagram")
+                    AsciidocDiagrams.Kroki -> listOf("asciidoctor-kroki")
                 }
             },
             loadBundledMacros = bundledMacros,
-            attributes = attributes,
+            attributes = diagramAttributes(diagrams) + attributes,
             workdir = baseDir
         )
     }
+
+    private fun diagramAttributes(diagrams: AsciidocDiagrams): Map<String, Any?> {
+        if (diagrams != AsciidocDiagrams.Kroki) return emptyMap()
+
+        return buildMap {
+            kroki.server?.let { put("kroki-server-url", it.toString()) }
+            kroki.defaultFormat?.let { put("kroki-default-format", it) }
+            put("kroki-fetch-diagram", "${kroki.fetch}")
+        }
+    }
 }
 
 enum class AsciidocDiagrams {
-    None, Diagrams
+    None, Diagrams, Kroki
 }
+
+data class KrokiDiagramsParameters(
+    val server: URI? = null,
+    val fetch: Boolean = true,
+    val defaultFormat: String? = null
+)

core/src/test/kotlin/com/github/zeldigas/text2confl/core/config/DirectoryConfigTest.kt

@@ -3,12 +3,14 @@ package com.github.zeldigas.text2confl.core.config
 import assertk.assertThat
 import assertk.assertions.isEqualTo
 import com.github.zeldigas.text2confl.convert.EditorVersion
+import com.github.zeldigas.text2confl.convert.asciidoc.AsciidoctorConfiguration
 import com.github.zeldigas.text2confl.convert.markdown.*
 import com.github.zeldigas.text2confl.core.upload.ChangeDetector
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.io.TempDir
 import java.net.URI
 import java.nio.file.Path
+import kotlin.io.path.Path
 import kotlin.io.path.writeText
 
 class DirectoryConfigTest {
@@ -77,9 +79,71 @@ class DirectoryConfigTest {
                     bundledMacros = false,
                     attributes = mapOf("toclevels" to 5),
                     tempDir = true,
-                    baseDir = "b"
+                    baseDir = "b",
+                    kroki = KrokiDiagramsParameters(
+                        server = URI.create("https://example.org"),
+                        fetch = false,
+                        defaultFormat = "png"
+                    )
                 )
             )
         )
     }
+
+    @Test
+    fun `Conversion of directory inputs to asciidoctor parameters for asciidoctor diagrams`() {
+        val dirAsciidoc = AsciidocParams(
+            gems = listOf("extra"),
+            diagrams = AsciidocDiagrams.Diagrams,
+            bundledMacros = true,
+            attributes = mapOf("toclevels" to 5),
+            tempDir = false,
+            baseDir = "test",
+            kroki = KrokiDiagramsParameters(
+                server = URI.create("https://example.org"),
+                fetch = true,
+                defaultFormat = "png"
+            )
+        )
+
+        val baseDir = Path(".")
+        assertThat(dirAsciidoc.toConfig(baseDir)).isEqualTo(AsciidoctorConfiguration(
+            libsToLoad = listOf("extra", "asciidoctor-diagram"),
+            loadBundledMacros = true,
+            attributes = mapOf(
+                "toclevels" to 5
+            ),
+            workdir = baseDir.resolve(Path("test"))
+        ))
+    }
+
+    @Test
+    fun `Conversion of directory inputs to asciidoctor parameters for kroki diagrams`() {
+        val dirAsciidoc = AsciidocParams(
+            gems = listOf("extra"),
+            diagrams = AsciidocDiagrams.Kroki,
+            bundledMacros = true,
+            attributes = mapOf("toclevels" to 5),
+            tempDir = false,
+            baseDir = "test",
+            kroki = KrokiDiagramsParameters(
+                server = URI.create("https://example.org"),
+                fetch = true,
+                defaultFormat = "png"
+            )
+        )
+
+        val baseDir = Path(".")
+        assertThat(dirAsciidoc.toConfig(baseDir)).isEqualTo(AsciidoctorConfiguration(
+            libsToLoad = listOf("extra", "asciidoctor-kroki"),
+            loadBundledMacros = true,
+            attributes = mapOf(
+                "kroki-server-url" to "https://example.org",
+                "kroki-default-format" to "png",
+                "kroki-fetch-diagram" to "true",
+                "toclevels" to 5
+            ),
+            workdir = baseDir.resolve(Path("test"))
+        ))
+    }
 }

core/src/test/resources/data/.text2confl.yml

@@ -55,3 +55,7 @@ asciidoc:
     toclevels: 5
   temp-dir: true
   base-dir: b
+  kroki:
+    server: https://example.org
+    fetch: false
+    default-format: png

docs/configuration-reference.md

@@ -84,14 +84,17 @@ asciidoc:
     plantuml-format: png
 ```
 
-| Parameter      | Default value | Description                                                                                                                                  |
-|----------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------|
-| diagrams       | `Diagrams`    | How to generate diagrams. The only option now is `Diagrams` that activates `asciidoctor-diagrams`                                            |
-| bundled-macros | `true`        | Enables [asciidoctor macros for Confluence](./storage-formats/asciidoc/confluence-specific.adoc)                                             |
-| attributes     | emtpy map     | Section where you can specify key-value pairs. All provided pairs will be passed to Asciidoc as attributes.                                  | 
-| gems           | empty list    | Additional ruby gems to _require_. Mentioned gems must be on classpath, packaged as jar files (like `asciidoctor-diagram`)                   | 
-| temp-dir       | false         | If temporary directory should be used to store all generated content                                                                         | 
-| base-dir       | `.asciidoc`   | Working directory where all generated content is stored if `temp-dir` option is not enabled. Directory is resolved relative to document root | 
+| Parameter            | Default value | Description                                                                                                                                  |
+|----------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| diagrams             | `Diagrams`    | How to generate diagrams. You can use `Diagrams` that activates `asciidoctor-diagrams` or `Kroki` to rely on `asciidoctor-kroki`             |
+| kroki.server         | not specified | Sets url of kroki server to use via `kroki-server-url`                                                                                       |
+| kroki.fetch          | `true`        | If Kroki-generated diagrams should be attached as files to page. This sets `kroki-fetch-diagram` attribute                                   |
+| kroki.default-format | not specified | Sets `kroki-default-format` variable.                                                                                                        |
+| bundled-macros       | `true`        | Enables [asciidoctor macros for Confluence](./storage-formats/asciidoc/confluence-specific.adoc)                                             |
+| attributes           | emtpy map     | Section where you can specify key-value pairs. All provided pairs will be passed to Asciidoc as attributes.                                  | 
+| gems                 | empty list    | Additional ruby gems to _require_. Mentioned gems must be on classpath, packaged as jar files (like `asciidoctor-diagram`)                   | 
+| temp-dir             | false         | If temporary directory should be used to store all generated content                                                                         | 
+| base-dir             | `.asciidoc`   | Working directory where all generated content is stored if `temp-dir` option is not enabled. Directory is resolved relative to document root | 
 
 ### Modifications check strategies
 

docs/storage-formats/asciidoc/diagrams.adoc

@@ -1,19 +1,74 @@
 = AsciiDoc - diagrams
-:keywords: supported-format,markdown
+:keywords: supported-format,asciidoc
 :toc: preamble
 
-For AsciiDoc *text2confl* relies on native diagrams support provided by link:https://docs.asciidoctor.org/diagram-extension/latest/[`asciidoctor-diagram` extension].
+*text2confl* supports two asciidoc-native diagrams extensions:
+
+. link:https://docs.asciidoctor.org/diagram-extension/latest/[`asciidoctor-diagram` extension].
+. link:https://github.com/asciidoctor/asciidoctor-kroki[`asciidoctor-kroki` extension].
+
+Approach for diagrams generation is controlled by
+
+[source,yaml]
+----
+asciidoc:
+  diagrams: Diagrams / Kroki / None
+----
+
+== Using `asciidoctor-diagram`
+
+`asciidoctor-diagram` support is enabled by default.
 
 That means that you have access to dozens of diagram formats as long as tools that can generate them is available on machine where *text2confl* works.
 
 NOTE: *text2confl* Docker image by default contains only `plantuml`.
 If you need any other diagram type, you can create derivative image with it.
 
+List of supported diagrams and macro names: https://docs.asciidoctor.org/diagram-extension/latest/diagram_types/a2s/
+
 Generated diagrams are attached to page like a regular files.
 
+== Using `asciidoctor-kroki`
+
+`asciidoctor-kroki` support can be enabled by explicitly setting diagram provider via `.text2confl.yml` file:
+
+[source,yaml]
+----
+asciidoc:
+  diagrams: Kroki
+  kroki:
+    server: ... # <1>
+    format: png # <2>
+    fetch: true/false # <3>
+----
+
+<1> `server` specifies custom Kroki server
+<2> `format` set's default format for generated diagrams
+<3> `fetch` setting to `false` will put a links to Kroki server instead of attaching diagram files to page
+
+Generated diagrams are attached to page like a regular files or put as an image links to Kroki server.
+
+You can find details about available options in xref:../../configuration-reference.md#asciidoc-configuration-options[configuration reference]
+
+List of supported diagrams and macro names: https://github.com/asciidoctor/asciidoctor-kroki/?tab=readme-ov-file#supported-diagram-types
+
+=== Additional customizations for Kroki
+
+You can customize kroki extension via `asciidoc.attributes` section in config with all link:https://github.com/asciidoctor/asciidoctor-kroki/?tab=readme-ov-file#configuration[supported attributes]:
+
+[source,yaml]
+----
+asciidoc:
+  attributes:
+----
+
+== Disabling diagram extensions
+
+If you want
+
 == Adding diagrams to page
 
-As link:https://docs.asciidoctor.org/diagram-extension/latest/blocks/[official AsciiDoc documentations] says, diagrams can be either put inline similar to code block or included from file using per diagram type macro.
+With both link:https://docs.asciidoctor.org/diagram-extension/latest/blocks/[asciidoctor-diagram] and link:https://github.com/asciidoctor/asciidoctor-kroki/?tab=readme-ov-file#usage[asciidoctor-kroki], diagrams can be either put inline similar to code block or included from file using per diagram type macro.
 
 With block or macro attributes, you can control name of generated file, file format and diagram-specific features.
 
@@ -38,10 +93,18 @@ include::_assets/example.adoc[tag=diagram]
 |===
 | AsciiDoc | Confluence
 
-|`+plantuml::_assets/test.puml[format=png]+`
-| plantuml::_assets/test.puml[format=png]
+|`+plantuml::_assets/test.puml[target=test,format=png]+`
+| plantuml::{docdir}/_assets/test.puml[target=test,format=png]
 |===
 
+[WARNING]
+.asciidoctor-kroki file imports
+====
+Until link:https://github.com/asciidoctor/asciidoctor-kroki/issues/446[file resolution issue] is not fixed, Kroki extension will fail to resolve files properly when you use relative paths.
+
+There is a workaround for this - add `+{docdir}+` to macro target: `+plantuml::{docdir}/_assets/test.puml[target=test,format=png]+`
+====
+
 == Location where diagrams are generated
 
 By default, generated diagrams are saved in `.asciidoc` directory under documents root.
@@ -52,7 +115,7 @@ This is configurable with the following parameters in `.text2confl.yml` file
 ----
 asciidoc:
   attributes:
-    plantuml-format: png
+    baseDir: .asciidoc
 ----
 
 You can find details about available options in xref:../../configuration-reference.md#asciidoc-configuration-options[configuration reference]