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 也可以带有它们自己的配置选项. 要查看有哪些选项可以使用, 请参考你使用的 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, 可能对你有用:
如果你是 Dokka plugin 的开发者, 希望将你的 plugin 添加到这个列表, 请通过 Slack 或 GitHub 联系维护者.
2026/10/11