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>

15 files changed, 709 insertions, 0 deletions

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 finish(output: File) {
+        directiveBasedCommandHandlers.forEach { it.finish(output) }
+    }
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/FallbackTemplateProcessingStrategy.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/FallbackTemplateProcessingStrategy.kt
new file mode 100644
index 00000000..a76d8eae
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/FallbackTemplateProcessingStrategy.kt
@@ -0,0 +1,16 @@
+/*
+ * 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 java.io.File
+
+public class FallbackTemplateProcessingStrategy : TemplateProcessingStrategy {
+
+    override fun process(input: File, output: File, moduleContext: DokkaConfiguration.DokkaModuleDescription?): Boolean {
+        if (input != output) input.copyTo(output, overwrite = true)
+        return true
+    }
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/PathToRootSubstitutor.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/PathToRootSubstitutor.kt
new file mode 100644
index 00000000..2ba290cf
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/PathToRootSubstitutor.kt
@@ -0,0 +1,20 @@
+/*
+ * 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.PathToRootSubstitutionCommand
+import org.jetbrains.dokka.base.templating.SubstitutionCommand
+import org.jetbrains.dokka.plugability.DokkaContext
+import java.io.File
+
+public 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
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ProjectNameSubstitutor.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ProjectNameSubstitutor.kt
new file mode 100644
index 00000000..9b22f31b
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ProjectNameSubstitutor.kt
@@ -0,0 +1,19 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package templates
+
+import org.jetbrains.dokka.base.templating.ProjectNameSubstitutionCommand
+import org.jetbrains.dokka.base.templating.SubstitutionCommand
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.templates.Substitutor
+import org.jetbrains.dokka.templates.TemplatingContext
+
+public class ProjectNameSubstitutor(
+    private val dokkaContext: DokkaContext
+) : Substitutor {
+
+    override fun trySubstitute(context: TemplatingContext<SubstitutionCommand>, match: MatchResult): String? =
+        dokkaContext.configuration.moduleName.takeIf { context.command is ProjectNameSubstitutionCommand }
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ReplaceVersionCommandHandler.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ReplaceVersionCommandHandler.kt
new file mode 100644
index 00000000..28820278
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/ReplaceVersionCommandHandler.kt
@@ -0,0 +1,31 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package templates
+
+import org.jetbrains.dokka.base.templating.Command
+import org.jetbrains.dokka.base.templating.ReplaceVersionsCommand
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.templates.CommandHandler
+import org.jsoup.nodes.Element
+import org.jsoup.nodes.TextNode
+import java.io.File
+
+public class ReplaceVersionCommandHandler(
+    private val context: DokkaContext
+) : CommandHandler {
+
+    override fun canHandle(command: Command): Boolean = command is ReplaceVersionsCommand
+
+    override fun handleCommandAsTag(command: Command, body: Element, input: File, output: File) {
+        val parent = body.parent()
+        if (parent != null) {
+            val position = body.elementSiblingIndex()
+            body.remove()
+
+            context.configuration.moduleVersion?.takeIf { it.isNotEmpty() }
+                ?.let { parent.insertChildren(position, TextNode(it)) }
+        }
+    }
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SourcesetDependencyProcessingStrategy.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SourcesetDependencyProcessingStrategy.kt
new file mode 100644
index 00000000..38a08eea
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SourcesetDependencyProcessingStrategy.kt
@@ -0,0 +1,40 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package templates
+
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.base.templating.AddToSourcesetDependencies
+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
+
+private typealias Entry = Map<String, List<String>>
+
+public class SourcesetDependencyProcessingStrategy(
+    public val context: DokkaContext
+) : TemplateProcessingStrategy {
+    private val fileName = "sourceset_dependencies.js"
+    private val fragments = ConcurrentHashMap<String, Entry>()
+
+    override fun finish(output: File) {
+        if (fragments.isNotEmpty()) {
+            val content = fragments.values.fold(emptyMap<String, List<String>>()) { acc, e -> acc + e }
+                .let { "sourceset_dependencies = '${toJsonString(it)}'" }
+            output.resolve("scripts").mkdirs()
+            output.resolve("scripts/$fileName").writeText(content)
+        }
+    }
+
+    override fun process(input: File, output: File, moduleContext: DokkaConfiguration.DokkaModuleDescription?): Boolean =
+        input.takeIf { it.name == fileName }
+            ?.runCatching { parseJson<AddToSourcesetDependencies>(input.readText()) }
+            ?.getOrNull()
+            ?.also { (moduleName, content) ->
+                fragments += (moduleName to content)
+            } != null
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandHandler.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandHandler.kt
new file mode 100644
index 00000000..0c030439
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandHandler.kt
@@ -0,0 +1,71 @@
+/*
+ * 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.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
+
+public class SubstitutionCommandHandler(context: DokkaContext) : CommandHandler {
+
+    override fun handleCommandAsTag(command: Command, body: Element, input: File, output: File) {
+        command as SubstitutionCommand
+        val childrenCopy = body.children().toList()
+        substitute(childrenCopy, TemplatingContext(input, output, childrenCopy, command))
+
+        val position = body.elementSiblingIndex()
+        val parent = body.parent()
+        body.remove()
+
+        parent?.insertChildren(position, childrenCopy)
+    }
+
+    override fun handleCommandAsComment(command: Command, body: List<Node>, input: File, output: File) {
+        command as SubstitutionCommand
+        substitute(body, TemplatingContext(input, output, body, command))
+    }
+
+    override fun canHandle(command: Command): Boolean = command is SubstitutionCommand
+
+    override fun finish(output: File) { }
+
+    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(elements: List<Node>, commandContext: TemplatingContext<SubstitutionCommand>) {
+        val regex = commandContext.command.pattern.toRegex()
+        elements.forEach { it.traverseToSubstitute(regex, commandContext) }
+    }
+
+    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)
+    }
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/Substitutor.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/Substitutor.kt
new file mode 100644
index 00000000..4dc4d353
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/Substitutor.kt
@@ -0,0 +1,11 @@
+/*
+ * 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.SubstitutionCommand
+
+public fun interface Substitutor {
+    public fun trySubstitute(context: TemplatingContext<SubstitutionCommand>, match: MatchResult): String?
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplateProcessor.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplateProcessor.kt
new file mode 100644
index 00000000..762e3c8b
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplateProcessor.kt
@@ -0,0 +1,104 @@
+/*
+ * 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 kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.runBlocking
+import org.jetbrains.dokka.DokkaConfiguration.DokkaModuleDescription
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.base.templating.Command
+import org.jetbrains.dokka.model.withDescendants
+import org.jetbrains.dokka.pages.RootPageNode
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.plugin
+import org.jetbrains.dokka.plugability.query
+import org.jetbrains.dokka.plugability.querySingle
+import org.jsoup.nodes.Node
+import java.io.File
+
+public interface TemplateProcessor
+
+public interface SubmoduleTemplateProcessor : TemplateProcessor {
+    public fun process(modules: List<DokkaModuleDescription>): TemplatingResult
+}
+
+public interface MultiModuleTemplateProcessor : TemplateProcessor {
+    public fun process(generatedPagesTree: RootPageNode)
+}
+
+public interface TemplateProcessingStrategy {
+    public fun process(input: File, output: File, moduleContext: DokkaModuleDescription?): Boolean
+    public fun finish(output: File) {}
+}
+
+public class DefaultSubmoduleTemplateProcessor(
+    private val context: DokkaContext,
+) : SubmoduleTemplateProcessor {
+
+    private val strategies: List<TemplateProcessingStrategy> =
+        context.plugin<TemplatingPlugin>().query { templateProcessingStrategy }
+
+    private val configuredModulesPaths =
+            context.configuration.modules.associate { it.sourceOutputDirectory.absolutePath to it.name }
+
+    override fun process(modules: List<DokkaModuleDescription>): TemplatingResult {
+        return runBlocking(Dispatchers.Default) {
+            coroutineScope {
+                modules.fold(TemplatingResult()) { acc, module ->
+                    acc + module.sourceOutputDirectory.visit(context.configuration.outputDir.resolve(module.relativePathToOutputDirectory), module)
+                }
+            }
+        }
+    }
+
+    private suspend fun File.visit(target: File, module: DokkaModuleDescription, acc: TemplatingResult = TemplatingResult()): TemplatingResult =
+        coroutineScope {
+            val source = this@visit
+            if (source.isDirectory) {
+                target.mkdirs()
+                val files = source.list().orEmpty()
+                val accWithSelf = configuredModulesPaths[source.absolutePath]
+                    ?.takeIf { files.firstOrNull { !it.startsWith(".") } != null }
+                    ?.let { acc.copy(modules = acc.modules + it) }
+                    ?: acc
+
+                files.fold(accWithSelf) { acc, path ->
+                    source.resolve(path).visit(target.resolve(path), module, acc)
+                }
+            } else {
+                strategies.first { it.process(source, target, module) }
+                acc
+            }
+        }
+}
+
+public class DefaultMultiModuleTemplateProcessor(
+    public val context: DokkaContext,
+) : MultiModuleTemplateProcessor {
+    private val strategies: List<TemplateProcessingStrategy> =
+        context.plugin<TemplatingPlugin>().query { templateProcessingStrategy }
+
+    private val locationProviderFactory = context.plugin<DokkaBase>().querySingle { locationProviderFactory }
+
+    override fun process(generatedPagesTree: RootPageNode) {
+        val locationProvider = locationProviderFactory.getLocationProvider(generatedPagesTree)
+        generatedPagesTree.withDescendants().mapNotNull { pageNode -> locationProvider.resolve(pageNode)?.let { File(it) } }
+            .forEach { location -> strategies.first { it.process(location, location, null) } }
+    }
+}
+
+public data class TemplatingContext<out T : Command>(
+    val input: File,
+    val output: File,
+    val body: List<Node>,
+    val command: T,
+)
+
+public data class TemplatingResult(val modules: List<String> = emptyList()) {
+    public operator fun plus(rhs: TemplatingResult): TemplatingResult {
+        return TemplatingResult((modules + rhs.modules).distinct())
+    }
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplatingPlugin.kt b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplatingPlugin.kt
new file mode 100644
index 00000000..8a2e5a2a
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/kotlin/org/jetbrains/dokka/templates/TemplatingPlugin.kt
@@ -0,0 +1,80 @@
+/*
+ * 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.allModulesPage.templates.PackageListProcessingStrategy
+import org.jetbrains.dokka.allModulesPage.templates.PagesSearchTemplateStrategy
+import org.jetbrains.dokka.plugability.*
+import templates.ProjectNameSubstitutor
+import templates.ReplaceVersionCommandHandler
+import templates.SourcesetDependencyProcessingStrategy
+
+@Suppress("unused")
+public class TemplatingPlugin : DokkaPlugin() {
+
+    public val submoduleTemplateProcessor: ExtensionPoint<SubmoduleTemplateProcessor> by extensionPoint()
+    public val multimoduleTemplateProcessor: ExtensionPoint<MultiModuleTemplateProcessor> by extensionPoint()
+    public val templateProcessingStrategy: ExtensionPoint<TemplateProcessingStrategy> by extensionPoint()
+    public val directiveBasedCommandHandlers: ExtensionPoint<CommandHandler> by extensionPoint()
+    public val substitutor: ExtensionPoint<Substitutor> by extensionPoint()
+
+    public val defaultSubmoduleTemplateProcessor: Extension<SubmoduleTemplateProcessor, *, *> by extending {
+        submoduleTemplateProcessor providing ::DefaultSubmoduleTemplateProcessor
+    }
+
+    public val defaultMultiModuleTemplateProcessor: Extension<MultiModuleTemplateProcessor, *, *> by extending {
+        multimoduleTemplateProcessor providing ::DefaultMultiModuleTemplateProcessor
+    }
+
+    public val directiveBasedHtmlTemplateProcessingStrategy: Extension<TemplateProcessingStrategy, *, *> by extending {
+        templateProcessingStrategy providing ::DirectiveBasedHtmlTemplateProcessingStrategy order {
+            before(fallbackProcessingStrategy)
+        }
+    }
+
+    public val sourcesetDependencyProcessingStrategy: Extension<TemplateProcessingStrategy, *, *> by extending {
+        templateProcessingStrategy providing ::SourcesetDependencyProcessingStrategy order {
+            before(fallbackProcessingStrategy)
+        }
+    }
+
+    public val pagesSearchTemplateStrategy: Extension<TemplateProcessingStrategy, *, *> by extending {
+        templateProcessingStrategy providing ::PagesSearchTemplateStrategy order {
+            before(fallbackProcessingStrategy)
+        }
+    }
+
+    public val packageListProcessingStrategy: Extension<TemplateProcessingStrategy, *, *> by extending {
+        templateProcessingStrategy providing ::PackageListProcessingStrategy order {
+            before(fallbackProcessingStrategy)
+        }
+    }
+
+    public val fallbackProcessingStrategy: Extension<TemplateProcessingStrategy, *, *> by extending {
+        templateProcessingStrategy with FallbackTemplateProcessingStrategy()
+    }
+
+    public val pathToRootSubstitutor: Extension<Substitutor, *, *> by extending {
+        substitutor providing ::PathToRootSubstitutor
+    }
+
+    public val projectNameSubstitutor: Extension<Substitutor, *, *> by extending {
+        substitutor providing ::ProjectNameSubstitutor
+    }
+
+    public val addToNavigationCommandHandler: Extension<CommandHandler, *, *> by extending {
+        directiveBasedCommandHandlers providing ::AddToNavigationCommandHandler
+    }
+    public val substitutionCommandHandler: Extension<CommandHandler, *, *> by extending {
+        directiveBasedCommandHandlers providing ::SubstitutionCommandHandler
+    }
+    public val replaceVersionCommandHandler: Extension<CommandHandler, *, *> by extending {
+        directiveBasedCommandHandlers providing ::ReplaceVersionCommandHandler
+    }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
+}
diff --git a/dokka-subprojects/plugin-templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin b/dokka-subprojects/plugin-templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin
new file mode 100644
index 00000000..e6771ac5
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin
@@ -0,0 +1,5 @@
+#
+# Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+#
+
+org.jetbrains.dokka.templates.TemplatingPlugin