Dokka Plugin

Dokka 的设计思想是易于扩展, 而且高度可定制化, 因此对于 Dokka 缺少的, 或者没有默认提供的细节功能, 社区开发者可以实现 plugin.

Dokka plugin 的范围很广, 包括支持其他编程语言的源代码, 到支持各种输出格式. 你可以对你自己的 KDoc tag 或注解添加支持, 教会 Dokka 如何输出 KDoc 描述中出现的各种的 DSL, 对 Dokka 页面的外观重新设计, 使其无缝的集成到你的公司的网站, 将 Dokka 与其他工具集成, 等等等等.

如果你想要学习如何创建 Dokka plugin, 请参见开发者指南.

应用 Dokka plugin

Dokka plugin 作为单独的 artifact 发布, 因此要应用一个 Dokka plugin, 你只需要将它添加为依赖项. 之后, plugin 会自行扩展 Dokka - 不需要你再进行更多工作.

我们来看看在你的项目中如何应用 mathjax plugin:

Gradle plugin for Dokka 会创建便利的依赖项配置, 你可以对全局应用 plugin, 或只对特定的输出格式应用 plugin.

plugins {
    id("org.jetbrains.dokka") version "2.2.0"
}

dependencies {
    dokkaPlugin("org.jetbrains.dokka:mathjax-plugin")
}

plugins {
    id 'org.jetbrains.dokka' version '2.2.0'
}

dependencies {
    dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin'
}

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <dokkaPlugins>
            <plugin>
                <groupId>org.jetbrains.dokka</groupId>
                <artifactId>mathjax-plugin</artifactId>
                <version>2.2.0</version>
            </plugin>
        </dokkaPlugins>
    </configuration>
</plugin>

如果你使用 CLI 运行器的命令行选项模式, Dokka plugin 应该以 .jar 文件的方式传递给 -pluginsClasspath:

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

如果你使用 JSON 配置模式, Dokka plugin 应该在 pluginsClasspath 之下指定.

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

配置 Dokka plugin

Dokka plugin 也可以带有它们自己的配置选项. 要查看有哪些选项可以使用, 请参考你使用的 plugin 的文档.

我们来看看如何配置内置的 HTML plugin, 我们向 assets 添加自定义的图片(使用 customAssets 选项), 添加自定义的样式表 (使用 customStyleSheets 选项), 修改页脚文字 (使用 footerMessage 选项):

要通过类型安全的方式配置 Dokka plugins, 请使用 dokka.pluginsConfiguration {} 代码段:

dokka {
    pluginsConfiguration.html {
        customAssets.from("logo.png")
        customStyleSheets.from("styles.css")
        footerMessage.set("(c) Your Company")
    }
}

关于 Dokka plugin 配置的例子, 请参见 Dokka 的 versioning plugin.

Dokka 允许你通过配置自定义 plugin 来扩展它的功能, 并修改文档生成过程.

dokka {
    pluginsConfiguration {
        html {
            customAssets.from("logo.png")
            customStyleSheets.from("styles.css")
            footerMessage.set("(c) Your Company")
        }
    }
}

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <pluginsConfiguration>
            <!-- plugin 的完整限定名称 -->
            <org.jetbrains.dokka.base.DokkaBase>
                <!-- 选项名称 -->
                <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>

如果你使用 CLI 运行器的命令行选项模式, 请使用 -pluginsConfiguration 选项来接受 JSON 配置, 选项值的格式是 fullyQualifiedPluginName=json.

如果你需要配置多个 plugin, 你可以传递多个值, 以 ^^ 分隔.

java -jar dokka-cli-2.2.0.jar \
     ...
     -pluginsConfiguration "org.jetbrains.dokka.base.DokkaBase={\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg CLI\"}"

如果你使用 JSON 配置, 也有类似的 pluginsConfiguration 数组, 在它的 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\"}"
    }
  ]
}

重要的 plugin

下面是一些重要的 Dokka plugin, 可能对你有用:

名称	描述
Android documentation plugin	改善 Android 上的文档体验
Versioning plugin	添加版本选择器, 帮助组织你的应用程序/库的多个不同版本的文档
MermaidJS HTML plugin	输出 KDocs 中出现的 MermaidJS 图和视觉效果
Mathjax HTML plugin	美化输出 KDocs 中出现的数学公式
Kotlin as Java plugin	以 Java 视角输出 Kotlin 签名
GFM plugin	支持以 GitHub Flavoured Markdown 格式生成文档
Jekyll plugin	支持以 Jekyll Flavoured Markdown 格式生成文档

如果你是 Dokka plugin 的开发者, 希望将你的 plugin 添加到这个列表, 请通过 Slack 或 GitHub 联系维护者.

2026/07/11