Restructure the project to utilize included builds (#3174)

* Refactor and simplify artifact publishing
* Update Gradle to 8.4
* Refactor and simplify convention plugins and build scripts

Fixes #3132

---------

Co-authored-by: Adam <897017+aSemy@users.noreply.github.com>
Co-authored-by: Oleg Yukhnevich <whyoleg@gmail.com>

24 files changed, 1397 insertions, 0 deletions

diff --git a/dokka-subprojects/plugin-templating/README.md b/dokka-subprojects/plugin-templating/README.md
new file mode 100644
index 00000000..92eee3e2
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/README.md
@@ -0,0 +1,4 @@
+# Templating plugin
+
+Templating plugin is used internally by Dokka and HTML format in particular to help handle substitution
+commands, resolve relative links and process templates.
diff --git a/dokka-subprojects/plugin-templating/api/plugin-templating.api b/dokka-subprojects/plugin-templating/api/plugin-templating.api
new file mode 100644
index 00000000..aedd8ef3
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/api/plugin-templating.api
@@ -0,0 +1,185 @@
+public abstract class org/jetbrains/dokka/allModulesPage/templates/BaseJsonNavigationTemplateProcessingStrategy : org/jetbrains/dokka/templates/TemplateProcessingStrategy {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun canProcess (Ljava/io/File;)Z
+	public fun finish (Ljava/io/File;)V
+	public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext;
+	public abstract fun getNavigationFileNameWithoutExtension ()Ljava/lang/String;
+	public abstract fun getPath ()Ljava/lang/String;
+	public fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z
+}
+
+public final class org/jetbrains/dokka/allModulesPage/templates/PackageListProcessingStrategy : org/jetbrains/dokka/templates/TemplateProcessingStrategy {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun finish (Ljava/io/File;)V
+	public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext;
+	public fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z
+}
+
+public final class org/jetbrains/dokka/allModulesPage/templates/PagesSearchTemplateStrategy : org/jetbrains/dokka/allModulesPage/templates/BaseJsonNavigationTemplateProcessingStrategy {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public final fun getDokkaContext ()Lorg/jetbrains/dokka/plugability/DokkaContext;
+	public fun getNavigationFileNameWithoutExtension ()Ljava/lang/String;
+	public fun getPath ()Ljava/lang/String;
+}
+
+public final class org/jetbrains/dokka/templates/AddToNavigationCommandHandler : org/jetbrains/dokka/templates/CommandHandler {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun canHandle (Lorg/jetbrains/dokka/base/templating/Command;)Z
+	public fun finish (Ljava/io/File;)V
+	public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext;
+	public fun handleCommand (Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V
+	public fun handleCommandAsComment (Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V
+	public fun handleCommandAsTag (Lorg/jetbrains/dokka/base/templating/Command;Lorg/jsoup/nodes/Element;Ljava/io/File;Ljava/io/File;)V
+}
+
+public abstract interface class org/jetbrains/dokka/templates/CommandHandler {
+	public abstract fun canHandle (Lorg/jetbrains/dokka/base/templating/Command;)Z
+	public abstract fun finish (Ljava/io/File;)V
+	public abstract fun handleCommand (Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V
+	public abstract fun handleCommandAsComment (Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V
+	public abstract fun handleCommandAsTag (Lorg/jetbrains/dokka/base/templating/Command;Lorg/jsoup/nodes/Element;Ljava/io/File;Ljava/io/File;)V
+}
+
+public final class org/jetbrains/dokka/templates/CommandHandler$DefaultImpls {
+	public static fun finish (Lorg/jetbrains/dokka/templates/CommandHandler;Ljava/io/File;)V
+	public static fun handleCommand (Lorg/jetbrains/dokka/templates/CommandHandler;Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V
+	public static fun handleCommandAsComment (Lorg/jetbrains/dokka/templates/CommandHandler;Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V
+	public static fun handleCommandAsTag (Lorg/jetbrains/dokka/templates/CommandHandler;Lorg/jetbrains/dokka/base/templating/Command;Lorg/jsoup/nodes/Element;Ljava/io/File;Ljava/io/File;)V
+}
+
+public final class org/jetbrains/dokka/templates/DefaultMultiModuleTemplateProcessor : org/jetbrains/dokka/templates/MultiModuleTemplateProcessor {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext;
+	public fun process (Lorg/jetbrains/dokka/pages/RootPageNode;)V
+}
+
+public final class org/jetbrains/dokka/templates/DefaultSubmoduleTemplateProcessor : org/jetbrains/dokka/templates/SubmoduleTemplateProcessor {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun process (Ljava/util/List;)Lorg/jetbrains/dokka/templates/TemplatingResult;
+}
+
+public final class org/jetbrains/dokka/templates/DirectiveBasedHtmlTemplateProcessingStrategy : org/jetbrains/dokka/templates/TemplateProcessingStrategy {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun finish (Ljava/io/File;)V
+	public final fun handleCommandAsComment (Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V
+	public final fun handleCommandAsTag (Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V
+	public fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z
+}
+
+public final class org/jetbrains/dokka/templates/FallbackTemplateProcessingStrategy : org/jetbrains/dokka/templates/TemplateProcessingStrategy {
+	public fun <init> ()V
+	public fun finish (Ljava/io/File;)V
+	public fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z
+}
+
+public abstract interface class org/jetbrains/dokka/templates/MultiModuleTemplateProcessor : org/jetbrains/dokka/templates/TemplateProcessor {
+	public abstract fun process (Lorg/jetbrains/dokka/pages/RootPageNode;)V
+}
+
+public final class org/jetbrains/dokka/templates/PathToRootSubstitutor : org/jetbrains/dokka/templates/Substitutor {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun trySubstitute (Lorg/jetbrains/dokka/templates/TemplatingContext;Lkotlin/text/MatchResult;)Ljava/lang/String;
+}
+
+public abstract interface class org/jetbrains/dokka/templates/SubmoduleTemplateProcessor : org/jetbrains/dokka/templates/TemplateProcessor {
+	public abstract fun process (Ljava/util/List;)Lorg/jetbrains/dokka/templates/TemplatingResult;
+}
+
+public final class org/jetbrains/dokka/templates/SubstitutionCommandHandler : org/jetbrains/dokka/templates/CommandHandler {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun canHandle (Lorg/jetbrains/dokka/base/templating/Command;)Z
+	public fun finish (Ljava/io/File;)V
+	public fun handleCommand (Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V
+	public fun handleCommandAsComment (Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V
+	public fun handleCommandAsTag (Lorg/jetbrains/dokka/base/templating/Command;Lorg/jsoup/nodes/Element;Ljava/io/File;Ljava/io/File;)V
+}
+
+public abstract interface class org/jetbrains/dokka/templates/Substitutor {
+	public abstract fun trySubstitute (Lorg/jetbrains/dokka/templates/TemplatingContext;Lkotlin/text/MatchResult;)Ljava/lang/String;
+}
+
+public abstract interface class org/jetbrains/dokka/templates/TemplateProcessingStrategy {
+	public abstract fun finish (Ljava/io/File;)V
+	public abstract fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z
+}
+
+public final class org/jetbrains/dokka/templates/TemplateProcessingStrategy$DefaultImpls {
+	public static fun finish (Lorg/jetbrains/dokka/templates/TemplateProcessingStrategy;Ljava/io/File;)V
+}
+
+public abstract interface class org/jetbrains/dokka/templates/TemplateProcessor {
+}
+
+public final class org/jetbrains/dokka/templates/TemplatingContext {
+	public fun <init> (Ljava/io/File;Ljava/io/File;Ljava/util/List;Lorg/jetbrains/dokka/base/templating/Command;)V
+	public final fun component1 ()Ljava/io/File;
+	public final fun component2 ()Ljava/io/File;
+	public final fun component3 ()Ljava/util/List;
+	public final fun component4 ()Lorg/jetbrains/dokka/base/templating/Command;
+	public final fun copy (Ljava/io/File;Ljava/io/File;Ljava/util/List;Lorg/jetbrains/dokka/base/templating/Command;)Lorg/jetbrains/dokka/templates/TemplatingContext;
+	public static synthetic fun copy$default (Lorg/jetbrains/dokka/templates/TemplatingContext;Ljava/io/File;Ljava/io/File;Ljava/util/List;Lorg/jetbrains/dokka/base/templating/Command;ILjava/lang/Object;)Lorg/jetbrains/dokka/templates/TemplatingContext;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getBody ()Ljava/util/List;
+	public final fun getCommand ()Lorg/jetbrains/dokka/base/templating/Command;
+	public final fun getInput ()Ljava/io/File;
+	public final fun getOutput ()Ljava/io/File;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class org/jetbrains/dokka/templates/TemplatingPlugin : org/jetbrains/dokka/plugability/DokkaPlugin {
+	public fun <init> ()V
+	public final fun getAddToNavigationCommandHandler ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getDefaultMultiModuleTemplateProcessor ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getDefaultSubmoduleTemplateProcessor ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getDirectiveBasedCommandHandlers ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
+	public final fun getDirectiveBasedHtmlTemplateProcessingStrategy ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getFallbackProcessingStrategy ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getMultimoduleTemplateProcessor ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
+	public final fun getPackageListProcessingStrategy ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getPagesSearchTemplateStrategy ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getPathToRootSubstitutor ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getProjectNameSubstitutor ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getReplaceVersionCommandHandler ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getSourcesetDependencyProcessingStrategy ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getSubmoduleTemplateProcessor ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
+	public final fun getSubstitutionCommandHandler ()Lorg/jetbrains/dokka/plugability/Extension;
+	public final fun getSubstitutor ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
+	public final fun getTemplateProcessingStrategy ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
+}
+
+public final class org/jetbrains/dokka/templates/TemplatingResult {
+	public fun <init> ()V
+	public fun <init> (Ljava/util/List;)V
+	public synthetic fun <init> (Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun component1 ()Ljava/util/List;
+	public final fun copy (Ljava/util/List;)Lorg/jetbrains/dokka/templates/TemplatingResult;
+	public static synthetic fun copy$default (Lorg/jetbrains/dokka/templates/TemplatingResult;Ljava/util/List;ILjava/lang/Object;)Lorg/jetbrains/dokka/templates/TemplatingResult;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getModules ()Ljava/util/List;
+	public fun hashCode ()I
+	public final fun plus (Lorg/jetbrains/dokka/templates/TemplatingResult;)Lorg/jetbrains/dokka/templates/TemplatingResult;
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class templates/ProjectNameSubstitutor : org/jetbrains/dokka/templates/Substitutor {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun trySubstitute (Lorg/jetbrains/dokka/templates/TemplatingContext;Lkotlin/text/MatchResult;)Ljava/lang/String;
+}
+
+public final class templates/ReplaceVersionCommandHandler : org/jetbrains/dokka/templates/CommandHandler {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun canHandle (Lorg/jetbrains/dokka/base/templating/Command;)Z
+	public fun finish (Ljava/io/File;)V
+	public fun handleCommand (Lorg/jsoup/nodes/Element;Lorg/jetbrains/dokka/base/templating/Command;Ljava/io/File;Ljava/io/File;)V
+	public fun handleCommandAsComment (Lorg/jetbrains/dokka/base/templating/Command;Ljava/util/List;Ljava/io/File;Ljava/io/File;)V
+	public fun handleCommandAsTag (Lorg/jetbrains/dokka/base/templating/Command;Lorg/jsoup/nodes/Element;Ljava/io/File;Ljava/io/File;)V
+}
+
+public final class templates/SourcesetDependencyProcessingStrategy : org/jetbrains/dokka/templates/TemplateProcessingStrategy {
+	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public fun finish (Ljava/io/File;)V
+	public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext;
+	public fun process (Ljava/io/File;Ljava/io/File;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaModuleDescription;)Z
+}
+
diff --git a/dokka-subprojects/plugin-templating/build.gradle.kts b/dokka-subprojects/plugin-templating/build.gradle.kts
new file mode 100644
index 00000000..e92e7b50
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/build.gradle.kts
@@ -0,0 +1,30 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import dokkabuild.overridePublicationArtifactId
+
+plugins {
+    id("dokkabuild.kotlin-jvm")
+    id("dokkabuild.publish-jvm")
+}
+
+overridePublicationArtifactId("templating-plugin")
+
+dependencies {
+    compileOnly(projects.dokkaSubprojects.dokkaCore)
+
+    api(libs.jsoup)
+
+    implementation(projects.dokkaSubprojects.pluginBase)
+
+    implementation(kotlin("reflect"))
+    implementation(libs.kotlinx.coroutines.core)
+
+    testImplementation(kotlin("test"))
+    testImplementation(libs.junit.jupiterParams)
+
+    testImplementation(projects.dokkaSubprojects.pluginBaseTestUtils)
+    testImplementation(projects.dokkaSubprojects.coreTestApi)
+    testImplementation(libs.kotlinx.html)
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/JsonElementBasedTemplateProcessingStrategy.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/JsonElementBasedTemplateProcessingStrategy.kt
new file mode 100644
index 00000000..8c6cee03
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/JsonElementBasedTemplateProcessingStrategy.kt
@@ -0,0 +1,67 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.allModulesPage.templates
+
+import org.jetbrains.dokka.DokkaConfiguration.DokkaModuleDescription
+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
+
+public abstract class BaseJsonNavigationTemplateProcessingStrategy(
+    public val context: DokkaContext
+) : TemplateProcessingStrategy {
+    public abstract val navigationFileNameWithoutExtension: String
+    public abstract val path: String
+
+    private val fragments = ConcurrentHashMap<String, List<SearchRecord>>()
+
+    public open fun canProcess(file: File): Boolean =
+        file.extension == "json" && file.nameWithoutExtension == navigationFileNameWithoutExtension
+
+    override fun process(input: File, output: File, moduleContext: DokkaModuleDescription?): Boolean {
+        val canProcess = canProcess(input)
+        if (canProcess) {
+            runCatching { parseJson<AddToSearch>(input.readText()) }.getOrNull()?.let { command ->
+                moduleContext?.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).mkdirs()
+            output.resolve("$path/$navigationFileNameWithoutExtension.json").writeText(content)
+        }
+    }
+
+    private fun fallbackToCopy(input: File, output: File) {
+        context.logger.warn("Falling back to just copying ${input.name} file even though it should have been processed")
+        input.copyTo(output)
+    }
+
+    private fun SearchRecord.withResolvedLocation(moduleName: String): SearchRecord =
+        copy(location = "$moduleName/$location")
+
+}
+
+public class PagesSearchTemplateStrategy(
+    public val dokkaContext: DokkaContext
+) : BaseJsonNavigationTemplateProcessingStrategy(dokkaContext) {
+    override val navigationFileNameWithoutExtension: String = "pages"
+    override val path: String = "scripts"
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/PackageListProcessingStrategy.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/PackageListProcessingStrategy.kt
new file mode 100644
index 00000000..4da45e3f
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/allModulesPage/templates/PackageListProcessingStrategy.kt
@@ -0,0 +1,56 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.allModulesPage.templates
+
+import org.jetbrains.dokka.DokkaConfiguration.DokkaModuleDescription
+import org.jetbrains.dokka.base.renderers.PackageListService
+import org.jetbrains.dokka.base.resolvers.shared.PackageList
+import org.jetbrains.dokka.base.resolvers.shared.PackageList.Companion.PACKAGE_LIST_NAME
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.templates.TemplateProcessingStrategy
+import java.io.File
+
+public class PackageListProcessingStrategy(
+    public val context: DokkaContext
+) : TemplateProcessingStrategy {
+    private val fragments = mutableSetOf<PackageList>()
+
+    private fun canProcess(file: File, moduleContext: DokkaModuleDescription?): Boolean =
+            file.extension.isBlank() && file.nameWithoutExtension == PACKAGE_LIST_NAME && moduleContext != null
+
+    override fun process(input: File, output: File, moduleContext: DokkaModuleDescription?): Boolean {
+        val canProcess = canProcess(input, moduleContext)
+        if (canProcess) {
+            val packageList = PackageList.load(input.toURI().toURL(), 8, true)
+            val moduleFilename = moduleContext?.name?.let { "$it/" }
+            packageList?.copy(
+                    modules = mapOf(moduleContext?.name.orEmpty() to packageList.modules.getOrDefault(PackageList.SINGLE_MODULE_NAME, emptySet())),
+                    locations = packageList.locations.entries.associate { it.key to "$moduleFilename${it.value}" }
+            )?.let { fragments.add(it) } ?: fallbackToCopy(input, output)
+        }
+        return canProcess
+    }
+
+    override fun finish(output: File) {
+        if (fragments.isNotEmpty()) {
+            val linkFormat = fragments.first().linkFormat
+
+            if (!fragments.all { it.linkFormat == linkFormat }) {
+                context.logger.error("Link format is inconsistent between modules: " + fragments.joinToString { it.linkFormat.formatName } )
+            }
+
+            val locations: Map<String, String> = fragments.map { it.locations }.fold(emptyMap()) { acc, el -> acc + el }
+            val modules: Map<String, Set<String>> = fragments.map { it.modules }.fold(emptyMap()) { acc, el -> acc + el }
+            val mergedPackageList = PackageListService.renderPackageList(locations, modules, linkFormat.formatName, linkFormat.linkExtension)
+            output.mkdirs()
+            output.resolve(PACKAGE_LIST_NAME).writeText(mergedPackageList)
+        }
+    }
+
+    private fun fallbackToCopy(input: File, output: File) {
+        context.logger.warn("Falling back to just copying ${input.name} file even though it should have been processed")
+        input.copyTo(output)
+    }
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandHandler.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandHandler.kt
new file mode 100644
index 00000000..78c6c684
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandHandler.kt
@@ -0,0 +1,62 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+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
+
+public class AddToNavigationCommandHandler(
+    public val context: DokkaContext
+) : CommandHandler {
+    private val navigationFragments = ConcurrentHashMap<String, Element>()
+
+    override fun handleCommandAsTag(command: Command, body: Element, 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()] = body }
+    }
+
+    override fun canHandle(command: Command): Boolean = 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())
+                )
+            }
+        }
+    }
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/CommandHandler.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/CommandHandler.kt
new file mode 100644
index 00000000..c06d52c3
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/CommandHandler.kt
@@ -0,0 +1,25 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.base.templating.Command
+import org.jsoup.nodes.Element
+import org.jsoup.nodes.Node
+import java.io.File
+
+
+public interface CommandHandler  {
+    @Deprecated("This was renamed to handleCommandAsTag", ReplaceWith("handleCommandAsTag(command, element, input, output)"))
+    public fun handleCommand(element: Element, command: Command, input: File, output: File) { }
+
+    @Suppress("DEPRECATION")
+    public fun handleCommandAsTag(command: Command, body: Element, input: File, output: File) {
+        handleCommand(body, command, input, output)
+    }
+    public fun handleCommandAsComment(command: Command, body: List<Node>, input: File, output: File) { }
+    public fun canHandle(command: Command): Boolean
+    public fun finish(output: File) {}
+}
+
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/DirectiveBasedTemplateProcessing.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/DirectiveBasedTemplateProcessing.kt
new file mode 100644
index 00000000..c36f2834
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/DirectiveBasedTemplateProcessing.kt
@@ -0,0 +1,102 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.base.renderers.html.TEMPLATE_COMMAND_BEGIN_BORDER
+import org.jetbrains.dokka.base.renderers.html.TEMPLATE_COMMAND_END_BORDER
+import org.jetbrains.dokka.base.renderers.html.TEMPLATE_COMMAND_SEPARATOR
+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.Comment
+import org.jsoup.nodes.Element
+import org.jsoup.nodes.Node
+import org.jsoup.nodes.TextNode
+import java.io.File
+import java.nio.file.Files
+
+public class DirectiveBasedHtmlTemplateProcessingStrategy(private val context: DokkaContext) : TemplateProcessingStrategy {
+
+    private val directiveBasedCommandHandlers =
+        context.plugin<TemplatingPlugin>().query { directiveBasedCommandHandlers }
+
+    override fun process(input: File, output: File, moduleContext: DokkaConfiguration.DokkaModuleDescription?): 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 {
+                handleCommandAsTag(it, parseJson(it.attr("data")), input, output)
+            }
+            extractCommandsFromComments(document) { command, body  ->
+                val bodyTrimed =
+                    body.dropWhile { node -> (node is TextNode && node.isBlank).also { if (it) node.remove() } }
+                        .dropLastWhile { node -> (node is TextNode && node.isBlank).also { if (it) node.remove() } }
+                handleCommandAsComment(command, bodyTrimed, input, output)
+            }
+
+            Files.write(output.toPath(), listOf(document.outerHtml()))
+            true
+        } else false
+
+    public fun handleCommandAsTag(element: Element, command: Command, input: File, output: File) {
+        traverseHandlers(command) { handleCommandAsTag(command, element, input, output) }
+    }
+
+    public fun handleCommandAsComment(command: Command, body: List<Node>, input: File, output: File) {
+        traverseHandlers(command) { handleCommandAsComment(command, body, input, output) }
+    }
+
+    private fun traverseHandlers(command: Command, action: CommandHandler.() -> Unit)  {
+        val handlers = directiveBasedCommandHandlers.filter { it.canHandle(command) }
+        if (handlers.isEmpty())
+            context.logger.warn("Unknown templating command $command")
+        else
+            handlers.forEach(action)
+    }
+
+    private fun extractCommandsFromComments(
+        node: Node,
+        startFrom: Int = 0,
+        handler: (command: Command, body: List<Node>) -> Unit
+    ) {
+        val nodes: MutableList<Node> = mutableListOf()
+        var lastStartBorder: Comment? = null
+        var firstStartBorder: Comment? = null
+        for (index in startFrom until node.childNodeSize()) {
+            when (val currentChild = node.childNode(index)) {
+                is Comment -> if (currentChild.data.startsWith(TEMPLATE_COMMAND_BEGIN_BORDER)) {
+                    lastStartBorder = currentChild
+                    firstStartBorder = firstStartBorder ?: currentChild
+                    nodes.clear()
+                } else if (lastStartBorder != null && currentChild.data.startsWith(TEMPLATE_COMMAND_END_BORDER)) {
+                    lastStartBorder.remove()
+                    val cmd = lastStartBorder.data
+                        .removePrefix("$TEMPLATE_COMMAND_BEGIN_BORDER$TEMPLATE_COMMAND_SEPARATOR")
+                        .let { parseJson<Command>(it) }
+
+                    handler(cmd, nodes)
+                    currentChild.remove()
+                    extractCommandsFromComments(node, firstStartBorder?.siblingIndex() ?: 0, handler)
+                    return
+                } else {
+                    if (lastStartBorder != null) nodes.add(currentChild)
+                }
+                else -> {
+                    extractCommandsFromComments(currentChild, handler = handler)
+                    if (lastStartBorder != null) nodes.add(currentChild)
+                }
+            }
+        }
+    }
+
+    override fun fin