Kotlin Help

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.

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.

Let's have a look at how you can apply the mathjax plugin to your project:

The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply plugins universally or for a specific output format only.

dependencies { // Is applied universally dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:1.7.20") // Is applied for the single-module dokkaHtml task only dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20") // Is applied for HTML format in multi-project builds dokkaHtmlPartialPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20") }

The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply Dokka plugins universally or for a specific output format only.

dependencies { // Is applied universally dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin:1.7.20' // Is applied for the single-module dokkaHtml task only dokkaHtmlPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20' // Is applied for HTML format in multi-project builds dokkaHtmlPartialPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20' }
<plugin> <groupId>org.jetbrains.dokka</groupId> <artifactId>dokka-maven-plugin</artifactId> ... <configuration> <dokkaPlugins> <plugin> <groupId>org.jetbrains.dokka</groupId> <artifactId>mathjax-plugin</artifactId> <version>1.7.20</version> </plugin> </dokkaPlugins> </configuration> </plugin>

If you are using the CLI runner with command line options, Dokka plugins should be passed as .jar files to -pluginsClasspath:

java -jar dokka-cli-1.7.20.jar \ -pluginsClasspath "./dokka-base-1.7.20.jar;...;./mathjax-plugin-1.7.20.jar" \ ...

If you are using JSON configuration, Dokka plugins should be specified under pluginsClasspath.

{ ... "pluginsClasspath": [ "./dokka-base-1.7.20.jar", "...", "./mathjax-plugin-1.7.20.jar" ], ... }

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 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):

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:

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:1.7.20") } } 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.

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 ) ) }
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] ) }
<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>

If you are using the CLI runner 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 ^^.

java -jar dokka-cli-1.7.20.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, there exists a similar pluginsConfiguration array that accepts JSON configuration in values.

{ "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\"}" } ] }

Notable plugins

Here are some notable Dokka plugins that you might find useful:

Name

Description

Android documentation plugin

Improves the documentation experience on Android

Versioning plugin

Adds version selector and helps to organize documentation for different versions of your application/library

MermaidJS HTML plugin

Renders MermaidJS diagrams and visualizations found in KDocs

Mathjax HTML plugin

Pretty prints mathematics found in KDocs

Kotlin as Java plugin

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 or GitHub.

Dokka devX survey

Last modified: 27 January 2023