Versioning (#1654)

* Adding versioning mechanism for multimodule

* Versioning improvement

* Refactor configuration, add ordering

* Fix integration tests

* Change packages, unignore test

Co-authored-by: Marcin Aman <marcin.aman@gmail.com>

18 files changed, 791 insertions, 0 deletions

diff --git a/plugins/templating/build.gradle.kts b/plugins/templating/build.gradle.kts
new file mode 100644
index 00000000..6c160a9f
--- /dev/null
+++ b/plugins/templating/build.gradle.kts
@@ -0,0 +1,18 @@
+import org.jetbrains.registerDokkaArtifactPublication
+
+registerDokkaArtifactPublication("templating-plugin") {
+    artifactId = "templating-plugin"
+}
+
+dependencies {
+    implementation(project(":plugins:base"))
+
+    val coroutines_version: String by project
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutines_version")
+    implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.11.1")
+    val kotlinx_html_version: String by project
+    implementation("org.jetbrains.kotlinx:kotlinx-html-jvm:$kotlinx_html_version")
+
+    implementation("org.jsoup:jsoup:1.12.1")
+    testImplementation(project(":plugins:base:base-test-utils"))
+}
\ No newline at end of file
diff --git a/plugins/templating/src/main/kotlin/templates/AddToNavigationCommandHandler.kt b/plugins/templating/src/main/kotlin/templates/AddToNavigationCommandHandler.kt
new file mode 100644
index 00000000..3e7e1290
--- /dev/null
+++ b/plugins/templating/src/main/kotlin/templates/AddToNavigationCommandHandler.kt
@@ -0,0 +1,56 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.base.templating.AddToNavigationCommand
+import org.jetbrains.dokka.base.templating.Command
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jsoup.nodes.Attributes
+import org.jsoup.nodes.Element
+import org.jsoup.parser.Tag
+import java.io.File
+import java.nio.file.Files
+import java.util.concurrent.ConcurrentHashMap
+
+class AddToNavigationCommandHandler(val context: DokkaContext) : CommandHandler {
+    private val navigationFragments = ConcurrentHashMap<String, Element>()
+
+    override fun handleCommand(element: Element, command: Command, input: File, output: File) {
+        command as AddToNavigationCommand
+        context.configuration.modules.find { it.name == command.moduleName }
+            ?.relativePathToOutputDirectory
+            ?.relativeToOrSelf(context.configuration.outputDir)
+            ?.let { key -> navigationFragments[key.toString()] = element }
+    }
+
+    override fun canHandle(command: Command) = command is AddToNavigationCommand
+
+    override fun finish(output: File) {
+        if (navigationFragments.isNotEmpty()) {
+            val attributes = Attributes().apply {
+                put("class", "sideMenu")
+            }
+            val node = Element(Tag.valueOf("div"), "", attributes)
+            navigationFragments.entries.sortedBy { it.key }.forEach { (moduleName, command) ->
+                command.select("a").forEach { a ->
+                    a.attr("href")?.also { a.attr("href", "${moduleName}/${it}") }
+                }
+                command.childNodes().toList().forEachIndexed { index, child ->
+                    if (index == 0) {
+                        child.attr("id", "$moduleName-nav-submenu")
+                    }
+                    node.appendChild(child)
+                }
+            }
+
+            Files.write(output.resolve("navigation.html").toPath(), listOf(node.outerHtml()))
+            node.select("a").forEach { a ->
+                a.attr("href")?.also { a.attr("href", "../${it}") }
+            }
+            navigationFragments.keys.forEach {
+                Files.write(
+                    output.resolve(it).resolve("navigation.html").toPath(),
+                    listOf(node.outerHtml())
+                )
+            }
+        }
+    }
+}
\ No newline at end of file
diff --git a/plugins/templating/src/main/kotlin/templates/CommandHandler.kt b/plugins/templating/src/main/kotlin/templates/CommandHandler.kt
new file mode 100644
index 00000000..d72092a1
--- /dev/null
+++ b/plugins/templating/src/main/kotlin/templates/CommandHandler.kt
@@ -0,0 +1,11 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.base.templating.Command
+import org.jsoup.nodes.Element
+import java.io.File
+
+interface CommandHandler {
+    fun handleCommand(element: Element, command: Command, input: File, output: File)
+    fun canHandle(command: Command): Boolean
+    fun finish(output: File) {}
+}
\ No newline at end of file
diff --git a/plugins/templating/src/main/kotlin/templates/DirectiveBasedTemplateProcessing.kt b/plugins/templating/src/main/kotlin/templates/DirectiveBasedTemplateProcessing.kt
new file mode 100644
index 00000000..c3b9aa53
--- /dev/null
+++ b/plugins/templating/src/main/kotlin/templates/DirectiveBasedTemplateProcessing.kt
@@ -0,0 +1,41 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.base.templating.Command
+import org.jetbrains.dokka.base.templating.parseJson
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.plugin
+import org.jetbrains.dokka.plugability.query
+import org.jsoup.Jsoup
+import org.jsoup.nodes.Element
+import java.io.File
+import java.nio.file.Files
+
+class DirectiveBasedHtmlTemplateProcessingStrategy(private val context: DokkaContext) : TemplateProcessingStrategy {
+
+    private val directiveBasedCommandHandlers =
+        context.plugin<TemplatingPlugin>().query { directiveBasedCommandHandlers }
+
+    override fun process(input: File, output: File): Boolean =
+        if (input.isFile && input.extension == "html") {
+            val document = Jsoup.parse(input, "UTF-8")
+            document.outputSettings().indentAmount(0).prettyPrint(false)
+            document.select("dokka-template-command").forEach {
+                handleCommand(it, parseJson(it.attr("data")), input, output)
+            }
+            Files.write(output.toPath(), listOf(document.outerHtml()))
+            true
+        } else false
+
+    fun handleCommand(element: Element, command: Command, input: File, output: File) {
+        val handlers = directiveBasedCommandHandlers.filter { it.canHandle(command) }
+        if (handlers.isEmpty())
+            context.logger.warn("Unknown templating command $command")
+        else
+            handlers.forEach { it.handleCommand(element, command, input, output) }
+
+    }
+
+    override fun finish(output: File) {
+        directiveBasedCommandHandlers.forEach { it.finish(output) }
+    }
+}
diff --git a/plugins/templating/src/main/kotlin/templates/FallbackTemplateProcessingStrategy.kt b/plugins/templating/src/main/kotlin/templates/FallbackTemplateProcessingStrategy.kt
new file mode 100644
index 00000000..4e88c318
--- /dev/null
+++ b/plugins/templating/src/main/kotlin/templates/FallbackTemplateProcessingStrategy.kt
@@ -0,0 +1,13 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.plugability.DokkaContext
+import java.io.File
+import java.nio.file.Files
+
+class FallbackTemplateProcessingStrategy(dokkaContext: DokkaContext) : TemplateProcessingStrategy {
+
+    override fun process(input: File, output: File): Boolean {
+        if(input != output) input.copyTo(output, overwrite = true)
+        return true
+    }
+}
\ No newline at end of file
diff --git a/plugins/templating/src/main/kotlin/templates/JsonElementBasedTemplateProcessingStrategy.kt b/plugins/templating/src/main/kotlin/templates/JsonElementBasedTemplateProcessingStrategy.kt
new file mode 100644
index 00000000..a2d55209
--- /dev/null
+++ b/plugins/templating/src/main/kotlin/templates/JsonElementBasedTemplateProcessingStrategy.kt
@@ -0,0 +1,68 @@
+package org.jetbrains.dokka.allModulesPage.templates
+
+import org.jetbrains.dokka.base.renderers.html.SearchRecord
+import org.jetbrains.dokka.base.templating.AddToSearch
+import org.jetbrains.dokka.base.templating.parseJson
+import org.jetbrains.dokka.base.templating.toJsonString
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.templates.TemplateProcessingStrategy
+import java.io.File
+import java.util.concurrent.ConcurrentHashMap
+
+abstract class BaseJsonNavigationTemplateProcessingStrategy(val context: DokkaContext) : TemplateProcessingStrategy {
+    abstract val navigationFileNameWithoutExtension: String
+    abstract val path: String
+
+    private val fragments = ConcurrentHashMap<String, List<SearchRecord>>()
+
+    open fun canProcess(file: File): Boolean =
+        file.extension == "json" && file.nameWithoutExtension == navigationFileNameWithoutExtension
+
+    override fun process(input: File, output: File): Boolean {
+        val canProcess = canProcess(input)
+        if (canProcess) {
+            runCatching { parseJson<AddToSearch>(input.readText()) }.getOrNull()?.let { command ->
+                context.configuration.modules.find { it.name == command.moduleName }?.relativePathToOutputDirectory
+                    ?.relativeToOrSelf(context.configuration.outputDir)
+                    ?.let { key ->
+                        fragments[key.toString()] = command.elements
+                    }
+            } ?: fallbackToCopy(input, output)
+        }
+        return canProcess
+    }
+
+    override fun finish(output: File) {
+        if (fragments.isNotEmpty()) {
+            val content = toJsonString(fragments.entries.flatMap { (moduleName, navigation) ->
+                navigation.map { it.withResolvedLocation(moduleName) }
+            })
+            output.resolve("$path/$navigationFileNameWithoutExtension.json").writeText(content)
+
+            fragments.keys.forEach {
+                output.resolve(it).resolve("$path/$navigationFileNameWithoutExtension.json").writeText(content)
+            }
+        }
+    }
+
+    private fun fallbackToCopy(input: File, output: File) {
+        context.logger.warn("Falling back to just copying file for ${input.name} even thought it should process it")
+        input.copyTo(output)
+    }
+
+    private fun SearchRecord.withResolvedLocation(moduleName: String): SearchRecord =
+        copy(location = "$moduleName/$location")
+
+}
+
+class NavigationSearchTemplateStrategy(val dokkaContext: DokkaContext) :
+    BaseJsonNavigationTemplateProcessingStrategy(dokkaContext) {
+    override val navigationFileNameWithoutExtension: String = "navigation-pane"
+    override val path: String = "scripts"
+}
+
+class PagesSearchTemplateStrategy(val dokkaContext: DokkaContext) :
+    BaseJsonNavigationTemplateProcessingStrategy(dokkaContext) {
+    override val navigationFileNameWithoutExtension: String = "pages"
+    override val path: String = "scripts"
+}
\ No newline at end of file
diff --git a/plugins/templating/src/main/kotlin/templates/PathToRootSubstitutor.kt b/plugins/templating/src/main/kotlin/templates/PathToRootSubstitutor.kt
new file mode 100644
index 00000000..da81432e
--- /dev/null
+++ b/plugins/templating/src/main/kotlin/templates/PathToRootSubstitutor.kt
@@ -0,0 +1,14 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.base.templating.PathToRootSubstitutionCommand
+import org.jetbrains.dokka.base.templating.SubstitutionCommand
+import org.jetbrains.dokka.plugability.DokkaContext
+import java.io.File
+
+class PathToRootSubstitutor(private val dokkaContext: DokkaContext) : Substitutor {
+
+    override fun trySubstitute(context: TemplatingContext<SubstitutionCommand>, match: MatchResult): String? =
+        if (context.command is PathToRootSubstitutionCommand) {
+            context.output.toPath().parent.relativize(dokkaContext.configuration.outputDir.toPath()).toString().split(File.separator).joinToString(separator = "/", postfix = "/") { it }
+        } else null
+}
\ No newline at end of file
diff --git a/plugins/templating/src/main/kotlin/templates/SubstitutionCommandHandler.kt b/plugins/templating/src/main/kotlin/templates/SubstitutionCommandHandler.kt
new file mode 100644
index 00000000..c7b15137
--- /dev/null
+++ b/plugins/templating/src/main/kotlin/templates/SubstitutionCommandHandler.kt
@@ -0,0 +1,60 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.base.templating.Command
+import org.jetbrains.dokka.base.templating.SubstitutionCommand
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.plugin
+import org.jetbrains.dokka.plugability.query
+import org.jsoup.nodes.DataNode
+import org.jsoup.nodes.Element
+import org.jsoup.nodes.Node
+import org.jsoup.nodes.TextNode
+import java.io.File
+
+class SubstitutionCommandHandler(context: DokkaContext) : CommandHandler {
+
+    override fun handleCommand(element: Element, command: Command, input: File, output: File) {
+        command as SubstitutionCommand
+        substitute(element, TemplatingContext(input, output, element, command))
+    }
+
+    override fun canHandle(command: Command): Boolean = command is SubstitutionCommand
+
+    private val substitutors = context.plugin<TemplatingPlugin>().query { substitutor }
+
+    private fun findSubstitution(commandContext: TemplatingContext<SubstitutionCommand>, match: MatchResult): String =
+        substitutors.asSequence().mapNotNull { it.trySubstitute(commandContext, match) }.firstOrNull() ?: match.value
+
+    private fun substitute(element: Element, commandContext: TemplatingContext<SubstitutionCommand>) {
+        val regex = commandContext.command.pattern.toRegex()
+        element.children().forEach { it.traverseToSubstitute(regex, commandContext) }
+
+        val childrenCopy = element.children().toList()
+        val position = element.elementSiblingIndex()
+        val parent = element.parent()
+        element.remove()
+
+        parent.insertChildren(position, childrenCopy)
+    }
+
+    private fun Node.traverseToSubstitute(regex: Regex, commandContext: TemplatingContext<SubstitutionCommand>) {
+        when (this) {
+            is TextNode -> replaceWith(TextNode(wholeText.substitute(regex, commandContext)))
+            is DataNode -> replaceWith(DataNode(wholeData.substitute(regex, commandContext)))
+            is Element -> {
+                attributes().forEach { attr(it.key, it.value.substitute(regex, commandContext)) }
+                childNodes().forEach { it.traverseToSubstitute(regex, commandContext) }
+            }
+        }
+    }
+
+    private fun String.substitute(regex: Regex, commandContext: TemplatingContext<SubstitutionCommand>) = buildString {
+        var lastOffset = 0
+        regex.findAll(this@substitute).forEach { match ->
+            append(this@substitute, lastOffset, match.range.first)
+            append(findSubstitution(commandContext, match))
+            lastOffset = match.range.last + 1
+        }
+        append(this@substitute, lastOffset, this@substitute.length)
+    }
+}
\ No newline at end of file
diff --git a/plugins/templating/src/main/kotlin/templates/Substitutor.kt b/plugins/templating/src/main/kotlin/templates/Substitutor.kt
new file mode 100644
index 00000000..55463974
--- /dev/null
+++ b/plugins/templating/src/main/kotlin/templates/Substitutor.kt
@@ -0,0 +1,7 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.base.templating.SubstitutionCommand
+
+fun interface Substitutor {
+    fun trySubstitute(context: TemplatingContext<SubstitutionCommand>, match: MatchResult): String?
+}
\ No newline at end of file
diff --git a/plugins/templating/src/main/kotlin/templates/TemplateProcessor.kt b/plugins/templating/src/main/kotlin/templates/TemplateProcessor.kt
new file mode 100644
index 00000000..8fbd76b6
--- /dev/null
+++ b/plugins/templating/src/main/kotlin/templates/TemplateProcessor.kt
@@ -0,0 +1,56 @@
+package org.jetbrains.dokka.templates
+
+import kotlinx.coroutines.*
+import org.jetbrains.dokka.base.templating.Command
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.plugin
+import org.jetbrains.dokka.plugability.query
+import org.jsoup.nodes.Element
+import java.io.File
+
+interface TemplateProcessor {
+    fun process()
+}
+
+interface TemplateProcessingStrategy {
+    fun process(input: File, output: File): Boolean
+    fun finish(output: File) {}
+}
+
+class DefaultTemplateProcessor(
+    private val context: DokkaContext,
+): TemplateProcessor {
+
+    private val strategies: List<TemplateProcessingStrategy> = context.plugin<TemplatingPlugin>().query { templateProcessingStrategy }
+
+    override fun process() = runBlocking(Dispatchers.Default) {
+        coroutineScope {
+            context.configuration.modules.forEach {
+                launch {
+                    it.sourceOutputDirectory.visit(context.configuration.outputDir.resolve(it.relativePathToOutputDirectory))
+                }
+            }
+        }
+        strategies.map { it.finish(context.configuration.outputDir) }
+        Unit
+    }
+
+    private suspend fun File.visit(target: File): Unit = coroutineScope {
+        val source = this@visit
+        if (source.isDirectory) {
+           target.mkdir()
+           source.list()?.forEach {
+               launch { source.resolve(it).visit(target.resolve(it)) }
+           }
+        } else {
+            strategies.first { it.process(source, target) }
+        }
+    }
+}
+
+data class TemplatingContext<out T: Command>(
+    val input: File,
+    val output: File,
+    val element: Element,
+    val command: T,
+)
\ No newline at end of file
diff --git a/plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt b/plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt
new file mode 100644
index 00000000..29ca4904
--- /dev/null
+++ b/plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt
@@ -0,0 +1,50 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.allModulesPage.templates.NavigationSearchTemplateStrategy
+import org.jetbrains.dokka.allModulesPage.templates.PagesSearchTemplateStrategy
+import org.jetbrains.dokka.plugability.DokkaPlugin
+
+class TemplatingPlugin : DokkaPlugin() {
+
+    val templateProcessor by extensionPoint<TemplateProcessor>()
+    val templateProcessingStrategy by extensionPoint<TemplateProcessingStrategy>()
+    val directiveBasedCommandHandlers by extensionPoint<CommandHandler>()
+
+    val substitutor by extensionPoint<Substitutor>()
+
+    val defaultTemplateProcessor by extending {
+        templateProcessor providing ::DefaultTemplateProcessor
+    }
+
+    val directiveBasedHtmlTemplateProcessingStrategy by extending {
+        templateProcessingStrategy providing ::DirectiveBasedHtmlTemplateProcessingStrategy order {
+            before(fallbackProcessingStrategy)
+        }
+    }
+    val navigationSearchTemplateStrategy by extending {
+        templateProcessingStrategy providing ::NavigationSearchTemplateStrategy order {
+            before(fallbackProcessingStrategy)
+        }
+    }
+
+    val pagesSearchTemplateStrategy by extending {
+        templateProcessingStrategy providing ::PagesSearchTemplateStrategy order {
+            before(fallbackProcessingStrategy)
+        }
+    }
+
+    val fallbackProcessingStrategy by extending {
+        templateProcessingStrategy providing ::FallbackTemplateProcessingStrategy
+    }
+
+    val pathToRootSubstitutor by extending {
+        substitutor providing ::PathToRootSubstitutor
+    }
+
+    val addToNavigationCommandHandler by extending {
+        directiveBasedCommandHandlers providing ::AddToNavigationCommandHandler
+    }
+    val substitutionCommandHandler by extending {
+        directiveBasedCommandHandlers providing ::SubstitutionCommandHandler
+    }
+}
\ No newline at end of file
diff --git a/plugins/templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin b/plugins/templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin
new file mode 100644
index 00000000..38e2d1bf
--- /dev/null
+++ b/plugins/templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin
@@ -0,0 +1 @@
+org.jetbrains.dokka.templates.TemplatingPlugin
\ No newline at end of file
diff --git a/plugins/templating/src/test/kotlin/templates/AddToNavigationCommandResolutionTest.kt b/plugins/templating/src/test/kotlin/templates/AddToNavigationCommandResolutionTest.kt
new file mode 100644
index 00000000..19c940c2
--- /dev/null
+++ b/plugins/templating/src/test/kotlin/templates/AddToNavigationCommandResolutionTest.kt
@@ -0,0 +1,137 @@
+package org.jetbrains.dokka.templates
+
+import kotlinx.html.a
+import kotlinx.html.div
+import kotlinx.html.id
+import kotlinx.html.span
+import kotlinx.html.stream.createHTML
+import org.jetbrains.dokka.DokkaModuleDescriptionImpl
+import org.jetbrains.dokka.base.renderers.html.templateCommand
+import org.jetbrains.dokka.base.templating.AddToNavigationCommand
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.junit.Rule
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.params.ParameterizedTest
+import org.junit.jupiter.params.provider.ValueSource
+import org.junit.rules.TemporaryFolder
+import utils.assertHtmlEqualsIgnoringWhitespace
+
+class AddToNavigationCommandResolutionTest : TemplatingAbstractTest() {
+    @get:Rule
+    val folder: TemporaryFolder = TemporaryFolder()
+
+    @Test
+    fun `should substitute AddToNavigationCommand in root directory`() =
+        addToNavigationTest {
+            val output = folder.root.resolve("navigation.html").readText()
+            val expected = expectedOutput(
+                ModuleWithPrefix("module1"),
+                ModuleWithPrefix("module2")
+            )
+            assertHtmlEqualsIgnoringWhitespace(expected, output)
+        }
+
+    @ParameterizedTest
+    @ValueSource(strings = ["module1", "module2"])
+    fun `should substitute AddToNavigationCommand in modules directory`(moduleName: String) =
+        addToNavigationTest {
+            val output = folder.root.resolve(moduleName).resolve("navigation.html").readText()
+            val expected = expectedOutput(
+                ModuleWithPrefix("module1", ".."),
+                ModuleWithPrefix("module2", "..")
+            )
+            assertHtmlEqualsIgnoringWhitespace(expected, output)
+        }
+
+    private fun expectedOutput(vararg modulesWithPrefix: ModuleWithPrefix) = createHTML(prettyPrint = true)
+        .div("sideMenu") {
+            modulesWithPrefix.forEach { (moduleName, prefix) ->
+                val relativePrefix = prefix?.let { "$it/" } ?: ""
+                div("sideMenuPart") {
+                    id = "$moduleName-nav-submenu"
+                    div("overview") {
+                        a {
+                            href = "$relativePrefix$moduleName/module-page.html"
+                            span {
+                                +"module-$moduleName"
+                            }
+                        }
+                    }
+                    div("sideMenuPart") {
+                        id = "$moduleName-nav-submenu-0"
+                        div("overview") {
+                            a {
+                                href = "$relativePrefix$moduleName/$moduleName/package-page.html"
+                                span {
+                                    +"package-$moduleName"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+    private fun inputForModule(moduleName: String) = createHTML()
+        .templateCommand(AddToNavigationCommand(moduleName)) {
+            div("sideMenuPart") {
+                id = "$moduleName-nav-submenu"
+                div("overview") {
+                    a {
+                        href = "module-page.html"
+                        span {
+                            +"module-$moduleName"
+                        }
+                    }
+                }
+                div("sideMenuPart") {
+                    id = "$moduleName-nav-submenu-0"
+                    div("overview") {
+                        a {
+                            href = "$moduleName/package-page.html"
+                            span {
+                                +"package-$moduleName"
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+    private fun addToNavigationTest(test: (DokkaContext) -> Unit) {
+        folder.create()
+        val module1 = folder.newFolder("module1")
+        val module2 = folder.newFolder("module2")
+
+        val configuration = dokkaConfiguration {
+            modules = listOf(
+                DokkaModuleDescriptionImpl(
+                    name = "module1",
+                    relativePathToOutputDirectory = module1,
+                    includes = emptySet(),
+                    sourceOutputDirectory = module1,
+                ),
+                DokkaModuleDescriptionImpl(
+                    name = "module2",
+                    relativePathToOutputDirectory = module2,
+                    includes = emptySet(),
+                    sourceOutputDirectory = module2,
+                ),
+            )
+            this.outputDir = folder.root
+        }
+
+        val module1Navigation = module1.resolve("navigation.html")
+        module1Navigation.writeText(inputForModule("module1"))
+        val module2Navigation = module2.resolve("navigation.html")
+        module2Navigation.writeText(inputForModule("module2"))
+
+        testFromData(configuration, preserveOutputLocation = true) {
+            submoduleProcessingStage = { ctx ->
+                test(ctx)
+            }
+        }
+    }
+
+    private data class ModuleWithPrefix(val moduleName: String, val prefix: String? = null)
+}
\ No newline at end of file
diff --git a/plugins/templating/src/test/kotlin/templates/AddToSearchCommandResolutionTest.kt b/plugins/templating/src/test/kotlin/templates/AddToSearchCommandResolutionTest.kt
new file mode 100644
index 00000000..a962d524
--- /dev/null
+++ b/plugins/templating/src/test/kotlin/templates/AddToSearchCommandResolutionTest.kt
@@ -0,0 +1,89 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.DokkaModuleDescriptionImpl
+import org.jetbrains.dokka.base.renderers.html.SearchRecord
+import org.jetbrains.dokka.base.templating.AddToSearch
+import org.jetbrains.dokka.base.templating.parseJson
+import org.jetbrains.dokka.base.templating.toJsonString
+import org.junit.Rule
+import org.junit.jupiter.params.ParameterizedTest
+import org.junit.jupiter.params.provider.ValueSource
+import org.junit.rules.TemporaryFolder
+import java.io.File
+import kotlin.test.assertEquals
+
+class AddToSearchCommandResolutionTest : TemplatingAbstractTest() {
+    companion object {
+        val elements = listOf(
+            SearchRecord(name = "name1", location = "location1"),
+            SearchRecord(name = "name2", location = "location2")
+        )
+        val fromModule1 = AddToSearch(
+            moduleName = "module1",
+            elements = elements
+        )
+        val fromModule2 = AddToSearch(
+            moduleName = "module2",
+            elements = elements
+        )
+    }
+
+    @get:Rule
+    val folder: TemporaryFolder = TemporaryFolder()
+
+    @ParameterizedTest
+    @ValueSource(strings = ["navigation-pane.json", "pages.json"])
+    fun `should merge navigation templates`(fileName: String) {
+        val (module1Navigation, module2Navigation) = setupTestDirectoriesWithContent(fileName)
+
+        val outputDir = folder.root
+        val configuration = dokkaConfiguration {
+            modules = listOf(
+                DokkaModuleDescriptionImpl(
+                    name = "module1",
+                    relativePathToOutputDirectory = folder.root.resolve("module1"),
+                    includes = emptySet(),
+                    sourceOutputDirectory = folder.root.resolve("module1"),
+                ),
+                DokkaModuleDescriptionImpl(
+                    name = "module2",
+                    relativePathToOutputDirectory = folder.root.resolve("module2"),
+                    includes = emptySet(),
+                    sourceOutputDirectory = folder.root.resolve("module2"),
+                ),
+            )
+            this.outputDir = outputDir
+        }
+
+        testFromData(configuration, preserveOutputLocation = true) {
+            submoduleProcessingStage = { _ ->
+                val expected = elements.map { it.copy(location = "module1/${it.location}") } +
+                        elements.map { it.copy(location = "module2/${it.location}") }
+
+                val output =
+                    parseJson<List<SearchRecord>>(outputDir.resolve("scripts/${fileName}").readText())
+                assertEquals(expected, output.sortedBy { it.location })
+
+                val outputFromModule1 = parseJson<List<SearchRecord>>(module1Navigation.readText())
+                assertEquals(expected, outputFromModule1.sortedBy { it.location })
+
+                val outputFromModule2 = parseJson<List<SearchRecord>>(module2Navigation.readText())
+                assertEquals(expected, outputFromModule2.sortedBy { it.location })
+            }
+        }
+    }
+
+    private fun setupTestDirectoriesWithContent(fileName: String): List<File> {
+        folder.create()
+        val scriptsForModule1 = folder.newFolder("module1", "scripts")
+        val scriptsForModule2 = folder.newFolder("module2", "scripts")
+        folder.newFolder("scripts")
+
+        val module1Navigation = scriptsForModule1.resolve(fileName)
+        module1Navigation.writeText(toJsonString(fromModule1))
+        val module2Navigation = scriptsForModule2.resolve(fileName)
+        module2Navigation.writeText(toJsonString(fromModule2))
+
+        return listOf(module1Navigation, module2Navigation)
+    }
+}
\ No newline at end of file
diff --git a/plugins/templating/src/test/kotlin/templates/SubstitutionCommandResolutionTest.kt b/plugins/templating/src/test/kotlin/templates/SubstitutionCommandResolutionTest.kt
new file mode 100644
index 00000000..d7143f11
--- /dev/null
+++ b/plugins/templating/src/test/kotlin/templates/SubstitutionCommandResolutionTest.kt
@@ -0,0 +1,69 @@
+package org.jetbrains.dokka.templates
+
+import kotlinx.html.a
+import kotlinx.html.div
+import kotlinx.html.id
+import kotlinx.html.stream.createHTML
+import org.jetbrains.dokka.DokkaModuleDescriptionImpl
+import org.jetbrains.dokka.base.renderers.html.templateCommand
+import org.jetbrains.dokka.base.templating.PathToRootSubstitutionCommand
+import org.junit.Rule
+import org.junit.rules.TemporaryFolder
+import org.junit.jupiter.api.Test
+import utils.assertHtmlEqualsIgnoringWhitespace
+import java.io.File
+
+class SubstitutionCommandResolutionTest : TemplatingAbstractTest() {
+
+    @get:Rule
+    val folder: TemporaryFolder = TemporaryFolder()
+
+    @Test
+    fun `should handle PathToRootCommand`() {
+        val template = createHTML()
+            .templateCommand(PathToRootSubstitutionCommand(pattern = "###", default = "default")) {
+                a {
+                    href = "###index.html"
+                    div {
+                        id = "logo"
+                    }
+                }
+            }
+
+        val expected = createHTML().a {
+            href = "../index.html"
+            div {
+                id = "logo"
+            }
+        }
+
+        val testedFile = createDirectoriesAndWriteContent(template)
+
+        val configuration = dokkaConfiguration {
+            modules = listOf(
+                DokkaModuleDescriptionImpl(
+                    name = "module1",
+                    relativePathToOutputDirectory = folder.root.resolve("module1"),
+                    includes = emptySet(),
+                    sourceOutputDirectory = folder.root.resolve("module1"),
+                )
+            )
+            this.outputDir = folder.root
+        }
+
+        testFromData(configuration, preserveOutputLocation = true){
+            submoduleProcessingStage = {
+                assertHtmlEqualsIgnoringWhitespace(expected, testedFile.readText())
+            }
+        }
+    }
+
+    private fun createDirectoriesAndWriteContent(content: String): File {
+        folder.create()
+        val module1 = folder.newFolder("module1")
+        val module1Content = module1.resolve("index.html")
+        module1Content.writeText(content)
+        return module1Content
+    }
+
+}
\ No newline at end of file
diff --git a/plugins/templating/src/test/kotlin/templates/TemplatingDokkaTestGenerator.kt b/plugins/templating/src/test/kotlin/templates/TemplatingDokkaTestGenerator.kt
new file mode 100644
index 00000000..906fb1ea
--- /dev/null
+++ b/plugins/templating/src/test/kotlin/templates/TemplatingDokkaTestGenerator.kt
@@ -0,0 +1,63 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.CoreExtensions
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.DokkaGenerator
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.testApi.logger.TestLogger
+import org.jetbrains.dokka.testApi.testRunner.AbstractTest
+import org.jetbrains.dokka.testApi.testRunner.DokkaTestGenerator
+import org.jetbrains.dokka.testApi.testRunner.TestBuilder
+import org.jetbrains.dokka.testApi.testRunner.TestMethods
+import org.jetbrains.dokka.utilities.DokkaConsoleLogger
+import org.jetbrains.dokka.utilities.DokkaLogger
+
+class TemplatingDokkaTestGenerator(
+    configuration: DokkaConfiguration,
+    logger: DokkaLogger,
+    testMethods: TemplatingTestMethods,
+    additionalPlugins: List<DokkaPlugin> = emptyList()
+) : DokkaTestGenerator<TemplatingTestMethods>(
+    configuration,
+    logger,
+    testMethods,
+    additionalPlugins + TemplatingPlugin() + TestTemplatingPlugin()
+) {
+    override fun generate() = with(testMethods) {
+        val dokkaGenerator = DokkaGenerator(configuration, logger)
+
+        val context =
+            dokkaGenerator.initializePlugins(configuration, logger, additionalPlugins)
+
+        pluginsSetupStage(context)
+
+        val generation = context.single(CoreExtensions.generation) as TestTemplatingGeneration
+
+        generation.processSubmodules()
+        submoduleProcessingStage(context)
+    }
+
+}
+
+open class TemplatingTestMethods(
+    open val pluginsSetupStage: (DokkaContext) -> Unit,
+    open val submoduleProcessingStage: (DokkaContext) -> Unit,
+) : TestMethods
+
+class TemplatingTestBuilder : TestBuilder<TemplatingTestMethods>() {
+    var pluginsSetupStage: (DokkaContext) -> Unit = {}
+    var submoduleProcessingStage: (DokkaContext) -> Unit = {}
+
+    override fun build() = TemplatingTestMethods(
+        pluginsSetupStage,
+        submoduleProcessingStage,
+    )
+}
+
+abstract class TemplatingAbstractTest(logger: TestLogger = TestLogger(DokkaConsoleLogger)) :
+    AbstractTest<TemplatingTestMethods, TemplatingTestBuilder, TemplatingDokkaTestGenerator>(
+        ::TemplatingTestBuilder,
+        ::TemplatingDokkaTestGenerator,
+        logger,
+    )
diff --git a/plugins/templating/src/test/kotlin/templates/TestTemplatingGeneration.kt b/plugins/templating/src/test/kotlin/templates/TestTemplatingGeneration.kt
new file mode 100644
index 00000000..0a5bae4b
--- /dev/null
+++ b/plugins/templating/src/test/kotlin/templates/TestTemplatingGeneration.kt
@@ -0,0 +1,22 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.Timer
+import org.jetbrains.dokka.generation.Generation
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.plugin
+import org.jetbrains.dokka.plugability.querySingle
+
+class TestTemplatingGeneration(context: DokkaContext): Generation {
+
+    val templatingPlugin by lazy { context.plugin<TemplatingPlugin>() }
+
+    override fun Timer.generate() {
+        report("Processing submodules")
+        processSubmodules()
+    }
+
+    fun processSubmodules() =
+        templatingPlugin.querySingle { templateProcessor }.process()
+
+    override val generationName = "test template generation"
+}
\ No newline at end of file
diff --git a/plugins/templating/src/test/kotlin/templates/TestTemplatingPlugin.kt b/plugins/templating/src/test/kotlin/templates/TestTemplatingPlugin.kt
new file mode 100644
index 00000000..1ed961b8
--- /dev/null
+++ b/plugins/templating/src/test/kotlin/templates/TestTemplatingPlugin.kt
@@ -0,0 +1,16 @@
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.CoreExtensions
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.plugability.DokkaPlugin
+
+class TestTemplatingPlugin: DokkaPlugin() {
+
+    val dokkaBase by lazy { plugin<DokkaBase>() }
+
+    val allModulesPageGeneration by extending {
+        (CoreExtensions.generation
+                providing ::TestTemplatingGeneration
+                override dokkaBase.singleGeneration)
+    }
+}
\ No newline at end of file