Revise documentation (#2728)

Co-authored-by: Sarah Haggarty <sarahhaggarty@users.noreply.github.com>

9 files changed, 4010 insertions, 0 deletions

diff --git a/docs/topics/dokka-get-started.md b/docs/topics/dokka-get-started.md
new file mode 100644
index 00000000..df4ab7e5
--- /dev/null
+++ b/docs/topics/dokka-get-started.md
@@ -0,0 +1,95 @@
+[//]: # (title: Get started)
+
+Below you can find simple instructions to help you get started with Dokka.
+
+<tabs group="build-script">
+<tab title="Gradle Kotlin DSL" group-key="kotlin">
+
+Apply the Gradle plugin for Dokka in the root build script of your project:
+
+```kotlin
+plugins {
+    id("org.jetbrains.dokka") version "%dokkaVersion%"
+}
+```
+
+When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need 
+to apply the Gradle plugin within subprojects as well:
+
+```kotlin
+subprojects {
+    apply(plugin = "org.jetbrains.dokka")
+}
+```
+
+To generate documentation, run the following Gradle tasks:
+
+* `dokkaHtml` for single-project builds
+* `dokkaHtmlMultiModule` for multi-project builds
+
+By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`.
+
+To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
+
+</tab>
+<tab title="Gradle Groovy DSL" group-key="groovy">
+
+Apply the Gradle plugin for Dokka in the root build script of your project:
+
+```groovy
+plugins {
+    id 'org.jetbrains.dokka' version '%dokkaVersion%'
+}
+```
+
+When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need
+to apply the Gradle plugin within subprojects as well:
+
+```groovy
+subprojects {
+    apply plugin: 'org.jetbrains.dokka'
+}
+```
+
+To generate documentation, run the following Gradle tasks:
+
+* `dokkaHtml` for single-project builds
+* `dokkaHtmlMultiModule` for multi-project builds
+
+By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`.
+
+To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
+
+</tab>
+<tab title="Maven" group-key="mvn">
+
+Add the Maven plugin for Dokka to the `plugins` section of your POM file:
+
+```xml
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.jetbrains.dokka</groupId>
+            <artifactId>dokka-maven-plugin</artifactId>
+            <version>%dokkaVersion%</version>
+            <executions>
+                <execution>
+                    <phase>pre-site</phase>
+                    <goals>
+                        <goal>dokka</goal>
+                    </goals>
+                </execution>
+            </executions>
+        </plugin>
+    </plugins>
+</build>
+```
+
+To generate documentation, run the `dokka:dokka` goal.
+
+By default, the output directory is set to `target/dokka`.
+
+To learn more about using Dokka with Maven, see [Maven](dokka-maven.md).
+
+</tab>
+</tabs>
diff --git a/docs/topics/dokka-introduction.md b/docs/topics/dokka-introduction.md
new file mode 100644
index 00000000..cc5cef78
--- /dev/null
+++ b/docs/topics/dokka-introduction.md
@@ -0,0 +1,28 @@
+[//]: # (title: Introduction)
+
+Dokka is an API documentation engine for Kotlin.
+
+Just like Kotlin itself, Dokka supports mixed-language projects. It understands Kotlin's
+[KDoc comments](https://kotlinlang.org/docs/kotlin-doc.html#kdoc-syntax) and Java's 
+[Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html).
+
+Dokka can generate documentation in multiple formats, including its own modern [HTML format](dokka-html.md),
+multiple flavors of [Markdown](dokka-markdown.md), and Java's [Javadoc HTML](dokka-javadoc.md).
+
+Here are some libraries that use Dokka for their API reference documentation:
+
+* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/)
+* [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html)
+* [Hexagon](https://hexagonkt.com/api/index.html)
+* [Ktor](https://api.ktor.io/)
+* [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown)
+
+You can run Dokka using [Gradle](dokka-gradle.md), [Maven](dokka-maven.md) or from the [command line](dokka-cli.md). It is also
+[highly pluggable](dokka-plugins.md).
+
+See [Get started](dokka-get-started.md) to take your first steps in using Dokka.
+
+## Community
+
+Dokka has a dedicated `#dokka` channel in [Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up)
+where you can chat about Dokka, its plugins and how to develop them, as well as get in touch with maintainers.
diff --git a/docs/topics/dokka-plugins.md b/docs/topics/dokka-plugins.md
new file mode 100644
index 00000000..5d3501ac
--- /dev/null
+++ b/docs/topics/dokka-plugins.md
@@ -0,0 +1,278 @@
+[//]: # (title: Dokka plugins)
+
+Dokka was built from the ground up to be easily extensible and highly customizable, which allows the community
+to implement plugins for missing or very specific features that are not provided out of the box.
+
+Dokka plugins range anywhere from supporting other programming language sources to exotic output formats. You can add
+support for your own KDoc tags or annotations, teach Dokka how to render different DSLs that are found in KDoc
+descriptions, visually redesign Dokka's pages to be seamlessly integrated into your company's website, integrate it
+with other tools and so much more. 
+
+If you want to learn how to create Dokka plugins, see 
+[Developer guides](https://kotlin.github.io/dokka/%dokkaVersion%/developer_guide/introduction/).
+
+## Apply Dokka plugins
+
+Dokka plugins are published as separate artifacts, so to apply a Dokka plugin you only need to add it as a dependency.
+From there, the plugin extends Dokka by itself - no further action is needed.
+
+> Plugins that use the same extension points or work in a similar way can interfere with each other.
+> This may lead to visual bugs, general undefined behaviour or even failed builds. However, it should not lead to 
+> concurrency issues since Dokka does not expose any mutable data structures or objects.
+>
+> If you notice problems like this, it's a good idea to check which plugins are applied and what they do.
+> 
+{type="note"}
+
+Let's have a look at how you can apply the [mathjax plugin](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax)
+to your project:
+
+<tabs group="build-script">
+<tab title="Kotlin" group-key="kotlin">
+
+The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply plugins universally or
+for a specific output format only.
+
+```kotlin
+dependencies {
+    // Is applied universally
+    dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:%dokkaVersion%")
+
+    // Is applied for the single-module dokkaHtml task only
+    dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%")
+
+    // Is applied for HTML format in multi-project builds
+    dokkaHtmlPartialPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%")
+}
+```
+
+> When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply Dokka plugins within
+> subprojects as well as in their parent project.
+>
+{type="note"}
+
+</tab>
+<tab title="Groovy" group-key="groovy">
+
+The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply Dokka plugins universally or
+for a specific output format only.
+
+```groovy
+dependencies {
+    // Is applied universally
+    dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin:%dokkaVersion%'
+
+    // Is applied for the single-module dokkaHtml task only
+    dokkaHtmlPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%'
+
+    // Is applied for HTML format in multi-project builds
+    dokkaHtmlPartialPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%'
+}
+```
+
+> When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply Dokka plugins within
+> subprojects as well as in their parent project.
+>
+{type="note"}
+
+</tab>
+<tab title="Maven" group-key="mvn">
+
+```xml
+<plugin>
+    <groupId>org.jetbrains.dokka</groupId>
+    <artifactId>dokka-maven-plugin</artifactId>
+    ...
+    <configuration>
+        <dokkaPlugins>
+            <plugin>
+                <groupId>org.jetbrains.dokka</groupId>
+                <artifactId>mathjax-plugin</artifactId>
+                <version>%dokkaVersion%</version>
+            </plugin>
+        </dokkaPlugins>
+    </configuration>
+</plugin>
+```
+
+</tab>
+<tab title="CLI" group-key="cli">
+
+If you are using the [CLI](dokka-cli.md) runner with [command line options](dokka-cli.md#run-with-command-line-options), 
+Dokka plugins should be passed as `.jar` files to `-pluginsClasspath`:
+
+```Shell
+java -jar dokka-cli-%dokkaVersion%.jar \
+     -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./mathjax-plugin-%dokkaVersion%.jar" \
+     ...
+```
+
+If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), Dokka plugins should be specified under 
+`pluginsClasspath`.
+
+```json
+{
+  ...
+  "pluginsClasspath": [
+    "./dokka-base-%dokkaVersion%.jar",
+    "...",
+    "./mathjax-plugin-%dokkaVersion%.jar"
+  ],
+  ...
+}
+```
+
+</tab>
+</tabs>
+
+## Configure Dokka plugins
+
+Dokka plugins can also have configuration options of their own. To see which options are available, consult
+the documentation of the plugins you are using. 
+
+Let's have a look at how you can configure the `DokkaBase` plugin, which is responsible for generating [HTML](dokka-html.md)
+documentation, by adding a custom image to the assets (`customAssets` option), by adding custom style sheets
+(`customStyleSheets` option), and by modifying the footer message (`footerMessage` option):
+
+<tabs group="build-script">
+<tab title="Kotlin" group-key="kotlin">
+
+Gradle's Kotlin DSL allows for type-safe plugin configuration. This is achievable by adding the plugin's artifact to 
+the classpath dependencies in the `buildscript` block, and then importing plugin and configuration classes:
+
+```kotlin
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.dokka.base.DokkaBaseConfiguration
+
+buildscript {
+    dependencies {
+        classpath("org.jetbrains.dokka:dokka-base:%dokkaVersion%")
+    }
+}
+
+tasks.withType<DokkaTask>().configureEach {
+    pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
+        customAssets = listOf(file("my-image.png"))
+        customStyleSheets = listOf(file("my-styles.css"))
+        footerMessage = "(c) 2022 MyOrg"
+    }
+}
+```
+
+Alternatively, plugins can be configured via JSON. With this method, no additional dependencies are needed.
+
+```kotlin
+import org.jetbrains.dokka.gradle.DokkaTask
+
+tasks.withType<DokkaTask>().configureEach {
+    val dokkaBaseConfiguration = """
+    {
+      "customAssets": ["${file("assets/my-image.png")}"],
+      "customStyleSheets": ["${file("assets/my-styles.css")}"],
+      "footerMessage": "(c) 2022 MyOrg"
+    }
+    """
+    pluginsMapConfiguration.set(
+        mapOf(
+            // fully qualified plugin name to json configuration
+            "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration
+        )
+    )
+}
+```
+
+</tab>
+<tab title="Groovy" group-key="groovy">
+
+```groovy
+import org.jetbrains.dokka.gradle.DokkaTask
+
+tasks.withType(DokkaTask.class) {
+    String dokkaBaseConfiguration = """
+    {
+      "customAssets": ["${file("assets/my-image.png")}"],
+      "customStyleSheets": ["${file("assets/my-styles.css")}"],
+      "footerMessage": "(c) 2022 MyOrg"
+    }
+    """
+    pluginsMapConfiguration.set(
+            // fully qualified plugin name to json configuration
+            ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration]
+    )
+}
+```
+
+</tab>
+<tab title="Maven" group-key="mvn">
+
+```xml
+<plugin>
+    <groupId>org.jetbrains.dokka</groupId>
+    <artifactId>dokka-maven-plugin</artifactId>
+    ...
+    <configuration>
+        <pluginsConfiguration>
+            <!-- Fully qualified plugin name -->
+            <org.jetbrains.dokka.base.DokkaBase>
+                <!-- Options by name -->
+                <customAssets>
+                    <asset>${project.basedir}/my-image.png</asset>
+                </customAssets>
+                <customStyleSheets>
+                    <stylesheet>${project.basedir}/my-styles.css</stylesheet>
+                </customStyleSheets>
+                <footerMessage>(c) MyOrg 2022 Maven</footerMessage>
+            </org.jetbrains.dokka.base.DokkaBase>
+        </pluginsConfiguration>
+    </configuration>
+</plugin>
+```
+
+</tab>
+<tab title="CLI" group-key="cli">
+
+If you are using the [CLI](dokka-cli.md) runner with [command line options](dokka-cli.md#run-with-command-line-options),
+use the `-pluginsConfiguration` option that accepts JSON configuration in the form of `fullyQualifiedPluginName=json`.
+
+If you need to configure multiple plugins, you can pass multiple values separated by `^^`.
+
+```Bash
+java -jar dokka-cli-%dokkaVersion%.jar \
+     ...
+     -pluginsConfiguration "org.jetbrains.dokka.base.DokkaBase={\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg CLI\"}"
+```
+
+If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), there exists a similar
+`pluginsConfiguration` array that accepts JSON configuration in `values`.
+
+```json
+{
+  "moduleName": "Dokka Example",
+  "pluginsConfiguration": [
+    {
+      "fqPluginName": "org.jetbrains.dokka.base.DokkaBase",
+      "serializationFormat": "JSON",
+      "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\"}"
+    }
+  ]
+}
+```
+
+</tab>
+</tabs>
+
+## Notable plugins
+
+Here are some notable Dokka plugins that you might find useful:
+
+| **Name**                                                                                                  | **Description**                                                                                              |
+|-----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
+| [Android documentation plugin](https://github.com/Kotlin/dokka/tree/master/plugins/android-documentation) | Improves the documentation experience on Android                                                             |
+| [Versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning)                       | Adds version selector and helps to organize documentation for different versions of your application/library |
+| [MermaidJS HTML plugin](https://github.com/glureau/dokka-mermaid)                                         | Renders [MermaidJS](https://mermaid-js.github.io/mermaid/#/) diagrams and visualizations found in KDocs      |
+| [Mathjax HTML plugin](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax)                        | Pretty prints mathematics found in KDocs                                                                     |
+| [Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java)               | Renders Kotlin signatures as seen from Java's perspective                                                    |
+
+If you are a Dokka plugin author and would like to add your plugin to this list, get in touch with maintainers
+via [Slack](dokka-introduction.md#community) or [GitHub](https://github.com/Kotlin/dokka/).
\ No newline at end of file
diff --git a/docs/topics/formats/dokka-html.md b/docs/topics/formats/dokka-html.md
new file mode 100644
index 00000000..dd81b2d9
--- /dev/null
+++ b/docs/topics/formats/dokka-html.md
@@ -0,0 +1,282 @@
+[//]: # (title: HTML)
+
+HTML is Dokka's default and recommended output format. You can see an example of the final result by browsing documentation
+for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/).
+
+## Generate HTML documentation
+
+HTML as an output format is supported by all runners. To generate HTML documentation, follow these steps depending on 
+your build tool or runner:
+
+* For [Gradle](dokka-gradle.md#generate-documentation), run `dokkaHtml` or `dokkaHtmlMultiModule` tasks.
+* For [Maven](dokka-maven.md#generate-documentation), run the `dokka:dokka` goal.
+* For [CLI runner](dokka-cli.md#generate-documentation), run with HTML dependencies set.
+
+> HTML pages generated by this format need to be hosted on a web server in order to render everything correctly.
+>
+> You can use any free static site hosting service, such as
+> [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages).
+>
+> Locally, you can use the [built-in IntelliJ web server](https://www.jetbrains.com/help/idea/php-built-in-web-server.html).
+>
+{type="note"}
+
+## Configuration
+
+HTML format is Dokka's base format, so it is configurable through `DokkaBase` and `DokkaBaseConfiguration`
+classes:
+
+<tabs group="build-script">
+<tab title="Kotlin" group-key="kotlin">
+
+Via type-safe Kotlin DSL:
+
+```kotlin
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.dokka.base.DokkaBaseConfiguration
+
+buildscript {
+    dependencies {
+        classpath("org.jetbrains.dokka:dokka-base:%dokkaVersion%")
+    }
+}
+
+tasks.withType<DokkaTask>().configureEach {
+    pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
+        customAssets = listOf(file("my-image.png"))
+        customStyleSheets = listOf(file("my-styles.css"))
+        footerMessage = "(c) 2022 MyOrg"
+        separateInheritedMembers = false
+        templatesDir = file("dokka/templates")
+        mergeImplicitExpectActualDeclarations = false
+    }
+}
+```
+
+Via JSON:
+
+```kotlin
+import org.jetbrains.dokka.gradle.DokkaTask
+
+tasks.withType<DokkaTask>().configureEach {
+    val dokkaBaseConfiguration = """
+    {
+      "customAssets": ["${file("assets/my-image.png")}"],
+      "customStyleSheets": ["${file("assets/my-styles.css")}"],
+      "footerMessage": "(c) 2022 MyOrg",
+      "separateInheritedMembers": false,
+      "templatesDir": "${file("dokka/templates")}",
+      "mergeImplicitExpectActualDeclarations": false
+    }
+    """
+    pluginsMapConfiguration.set(
+        mapOf(
+            // fully qualified plugin name to json configuration
+            "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration
+        )
+    )
+}
+```
+
+</tab>
+<tab title="Groovy" group-key="groovy">
+
+```groovy
+import org.jetbrains.dokka.gradle.DokkaTask
+
+tasks.withType(DokkaTask.class) {
+    String dokkaBaseConfiguration = """
+    {
+      "customAssets": ["${file("assets/my-image.png")}"],
+      "customStyleSheets": ["${file("assets/my-styles.css")}"],
+      "footerMessage": "(c) 2022 MyOrg"
+      "separateInheritedMembers": false,
+      "templatesDir": "${file("dokka/templates")}",
+      "mergeImplicitExpectActualDeclarations": false
+    }
+    """
+    pluginsMapConfiguration.set(
+            // fully qualified plugin name to json configuration
+            ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration]
+    )
+}
+```
+
+</tab>
+<tab title="Maven" group-key="mvn">
+
+```xml
+<plugin>
+    <groupId>org.jetbrains.dokka</groupId>
+    <artifactId>dokka-maven-plugin</artifactId>
+    ...
+    <configuration>
+        <pluginsConfiguration>
+            <!-- Fully qualified plugin name -->
+            <org.jetbrains.dokka.base.DokkaBase>
+                <!-- Options by name -->
+                <customAssets>
+                    <asset>${project.basedir}/my-image.png</asset>
+                </customAssets>
+                <customStyleSheets>
+                    <stylesheet>${project.basedir}/my-styles.css</stylesheet>
+                </customStyleSheets>
+                <footerMessage>(c) MyOrg 2022 Maven</footerMessage>
+                <separateInheritedMembers>false</separateInheritedMembers>
+                <templatesDir>${project.basedir}/dokka/templates</templatesDir>
+                <mergeImplicitExpectActualDeclarations>false</mergeImplicitExpectActualDeclarations>
+            </org.jetbrains.dokka.base.DokkaBase>
+        </pluginsConfiguration>
+    </configuration>
+</plugin>
+```
+
+</tab>
+<tab title="CLI" group-key="cli">
+
+Via [command line options](dokka-cli.md#run-with-command-line-options):
+
+```Bash
+java -jar dokka-cli-%dokkaVersion%.jar \
+     ...
+     -pluginsConfiguration "org.jetbrains.dokka.base.DokkaBase={\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\", \"separateInheritedMembers\": false, \"templatesDir\": \"dokka/templates\", \"mergeImplicitExpectActualDeclarations\": false}
+"
+```
+
+Via [JSON configuration](dokka-cli.md#run-with-json-configuration):
+
+```json
+{
+  "moduleName": "Dokka Example",
+  "pluginsConfiguration": [
+    {
+      "fqPluginName": "org.jetbrains.dokka.base.DokkaBase",
+      "serializationFormat": "JSON",
+      "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\", \"separateInheritedMembers\": false, \"templatesDir\": \"dokka/templates\", \"mergeImplicitExpectActualDeclarations\": false}"
+    }
+  ]
+}
+```
+
+</tab>
+</tabs>
+
+### Configuration options
+
+The table below contains all of the possible configuration options and their purpose.
+
+| **Option**                              | **Description**                                                                                                                                                                                                                                                                               |
+|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `customAssets`                          | List of paths for image assets to be bundled with documentation. The image assets can have any file extension. For more information, see [Customizing assets](#customize-assets).                                                                                                             |
+| `customStyleSheets`                     | List of paths for `.css` stylesheets to be bundled with documentation and used for rendering. For more information, see [Customizing styles](#customize-styles).                                                                                                                              |
+| `templatesDir`                          | Path to the directory containing custom HTML templates. For more information, see [Templates](#templates).                                                                                                                                                                                    |
+| `footerMessage`                         | The text displayed in the footer.                                                                                                                                                                                                                                                             |
+| `separateInheritedMembers`              | This is a boolean option. If set to `true`, Dokka renders properties/functions and inherited properties/inherited functions separately. This is disabled by default.                                                                                                                          |
+| `mergeImplicitExpectActualDeclarations` | This is a boolean option. If set to `true`, Dokka merges declarations that are not declared as [expect/actual](https://kotlinlang.org/docs/multiplatform-connect-to-apis.html), but have the same fully qualified name. This can be useful for legacy codebases. This is disabled by default. |
+
+For more information about configuring Dokka plugins, see [Configuring Dokka plugins](dokka-plugins.md#configure-dokka-plugins).
+
+## Customization
+
+To help you add your own look and feel to your documentation, the HTML format supports a number of customization options.
+
+### Customize styles
+
+You can use your own stylesheets by using the `customStyleSheets`
+[configuration option](#configuration). These are applied to every page.
+
+It's also possible to override Dokka's default stylesheets by providing files with the same name:
+
+| **Stylesheet name**  | **Description**                                                    |
+|----------------------|--------------------------------------------------------------------|
+| `style.css`          | Main stylesheet, contains most of the styles used across all pages |
+| `logo-styles.css`    | Header logo styling                                                |
+| `prism.css`          | Styles for [PrismJS](https://prismjs.com/) syntax highlighter      |
+| `jetbrains-mono.css` | Font styling                                                       |
+
+The source code for all of Dokka's stylesheets is
+[available on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/styles).
+
+### Customize assets
+
+You can provide your own images to be bundled with documentation by using the `customAssets`
+[configuration option](#configuration). 
+
+These files are copied to the `<output>/images` directory.
+
+It's possible to override Dokka's images and icons by providing files with the same name. The most
+useful and relevant one being `logo-icon.svg`, which is the image that's used in the header. The rest is mostly icons.
+
+You can find all images used by Dokka on 
+[GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/images).
+
+### Change the logo
+
+To customize the logo, you can begin by [providing your own asset](#customize-assets) for `logo-icon.svg`.
+
+If you don't like how it looks, or you want to use a `.png` file instead of the default `.svg` file,
+you can [override the `logo-styles.css` stylesheet](#customize-styles) to customize it.
+
+For an example of how to do this, see our
+[custom format example project](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle/dokka-customFormat-example).
+
+### Modify the footer
+
+You can modify text in the footer by using the `footerMessage` [configuration option](#configuration).
+
+### Templates
+
+Dokka provides the ability to modify [FreeMarker](https://freemarker.apache.org/) templates used for generating 
+documentation pages.
+
+You can change the header completely, add your own banners/menus/search, load analytics, change body styling and so on.
+
+Dokka uses the following templates:
+
+| **Template**                      | **Description**                                                                                                       |
+|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| `base.ftl`                        | Defines the general design of all pages to be rendered.                                                               |
+| `includes/header.ft`              | The page header that by default contains the logo, version, source set selector, light/dark theme switch, and search. |
+| `includes/footer.ft`              | The page footer that contains the `footerMessage` [configuration option](#configuration) and copyright.               |
+| `includes/page_metadata.ft`       | Metadata used within `<head>` container.                                                                              |
+| `includes/source_set_selector.ft` | [The source set](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) selector in the header. |
+
+The base template is `base.ftl` and it includes all of the remaining listed templates. You can find the source code for all of Dokka's templates
+[on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/templates).
+
+You can override any template by using the `templatesDir` [configuration option](#configuration). Dokka searches
+for the exact template names within the given directory. If it fails to find user-defined templates, it uses the
+default templates.
+
+#### Variables
+
+The following variables are available inside all templates:
+
+| **Variable**       | **Description**                                                                                                                                                                                    |
+|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `${pageName}`      | The page name                                                                                                                                                                                      |
+| `${footerMessage}` | The text which is set by the `footerMessage` [configuration option](#configuration)                                                                                                                |
+| `${sourceSets}`    | A nullable list of [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) for multi-platform pages. Each item has `name`, `platform`, and `filter` properties. |
+| `${projectName}`   | The project name. It's available only within the `template_cmd` directive.                                                                                                                         |
+| `${pathToRoot}`    | The path to root from the current page. It's useful for locating assets and is available only within the `template_cmd` directive.                                                                 |
+
+Variables `projectName` and `pathToRoot` are available only within the `template_cmd` directive as they require more
+context and thus they need to be resolved at later stages by the [MultiModule](dokka-gradle.md#multi-project-builds) task:
+
+```html
+<@template_cmd name="projectName">
+   <span>${projectName}</span>
+</@template_cmd>
+```
+
+#### Directives
+
+You can also use the following Dokka-defined [directives](https://freemarker.apache.org/docs/ref_directive_userDefined.html):
+
+| **Variable**    | **Description**                                                                                                                                                                              |
+|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `<@content/>`   | The main page content.                                                                                                                                                                       |
+| `<@resources/>` | Resources such as scripts and stylesheets.                                                                                                                                                   |
+| `<@version/>`   | The module version taken from configuration. If the [versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) is applied, it is replaced with a version navigator. |
+
diff --git a/docs/topics/formats/dokka-javadoc.md b/docs/topics/formats/dokka-javadoc.md
new file mode 100644
index 00000000..4781afcb
--- /dev/null
+++ b/docs/topics/formats/dokka-javadoc.md
@@ -0,0 +1,93 @@
+[//]: # (title: Javadoc)
+
+> The Javadoc output format is still in Alpha so you may find bugs and experience migration issues when using it. 
+> Successful integration with tools that accept Java's Javadoc HTML as input is not guaranteed.
+> **You use it at your own risk.**
+>
+{type="warning"}
+
+Dokka's Javadoc output format is a lookalike of Java's
+[Javadoc HTML format](https://docs.oracle.com/en/java/javase/19/docs/api/index.html). 
+
+It tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation
+or an exact copy.
+
+![Screenshot of javadoc output format](javadoc-format-example.png){height=750}
+
+All Kotlin code and signatures are rendered as seen from Java's perspective. This is achieved with our
+[Kotlin as Java Dokka plugin](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java), which comes bundled and
+applied by default for this format.
+
+The Javadoc output format is implemented as a [Dokka plugin](dokka-plugins.md), and it is maintained by the Dokka team.
+It is open source and you can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc).
+
+## Generate Javadoc documentation
+
+> The Javadoc format does not support multiplatform projects.
+>
+{type="warning"}
+
+
+<tabs group="build-script">
+<tab title="Gradle" group-key="kotlin">
+
+The [Gradle plugin for Dokka](dokka-gradle.md) comes with the Javadoc output format included. You can use the following tasks:
+
+| **Task**                | **Description**                                                                                                                                                                                              |
+|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `dokkaJavadoc`          | Generates Javadoc documentation for a single project.                                                                                                                                                        |
+| `dokkaJavadocCollector` | A [`Collector`](dokka-gradle.md#collector-tasks) task created only for parent projects in multi-project builds. It calls `dokkaJavadoc` for every subproject and merges all outputs into a single virtual project. |
+
+The `javadoc.jar` file can be generated separately. For more information, see [Building `javadoc.jar`](dokka-gradle.md#build-javadoc-jar).
+
+</tab>
+<tab title="Maven" group-key="groovy">
+
+The [Maven plugin for Dokka](dokka-maven.md) comes with the Javadoc output format built in. You can generate documentation
+by using the following goals:
+
+| **Goal**           | **Description**                                                              |
+|--------------------|------------------------------------------------------------------------------|
+| `dokka:javadoc`    | Generates documentation in Javadoc format                                    |
+| `dokka:javadocJar` | Generates a `javadoc.jar` file that contains documentation in Javadoc format |
+
+
+</tab>
+<tab title="CLI" group-key="cli">
+
+Since the Javadoc output format is a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to 
+download the plugin's [JAR file](https://mvnrepository.com/artifact/org.jetbrains.dokka/javadoc-plugin/%dokkaVersion%).
+
+The Javadoc output format has two dependencies that you need to provide as additional JAR files:
+
+* [kotlin-as-java plugin](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin/%dokkaVersion%)
+* [korte-jvm](https://mvnrepository.com/artifact/com.soywiz.korlibs.korte/korte-jvm/3.3.0)
+
+Via [command line options](dokka-cli.md#run-with-command-line-options):
+
+```Bash
+java -jar dokka-cli-%dokkaVersion%.jar \
+     -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./javadoc-plugin-%dokkaVersion%.jar" \
+     ...
+```
+
+Via [JSON configuration](dokka-cli.md#run-with-json-configuration):
+
+```json
+{
+  ...
+  "pluginsClasspath": [
+    "./dokka-base-%dokkaVersion%.jar",
+    "...",