HTML

HTML 是 Dokka 的默认并且推荐的输出格式. 它支持 Kotlin Multiplatform, Android, 以及 Java 项目. 此外, 你可以使用 HTML 格式, 对单项目构建和多项目构建生成文档.

关于输出格式的示例, 请查看以下文档:

生成 HTML 文档

所有的运行器都支持 HTML 输出格式. 要生成 HTML 文档, 请根据你的构建工具和运行器, 执行以下步骤:

对于 Gradle, 可以运行以下 task:
- dokkaGenerate: 生成文档, 使用应用的插件支持的所有可用格式. 这是对大多数用户推荐使用的 task. 在 IntelliJ IDEA 中使用这个 task 时, 它会输出一个可点击的链接.
- dokkaGeneratePublicationHtml: 生成文档, 只使用 HTML 格式. 这个 task 将输出目录作为 @OutputDirectory 公开. 当你需要在其它 Gradle task 中使用生成的文件时, 例如上传到服务器, 移动到 GitHub Pages 目录, 或打包到 javadoc.jar 之内, 请使用这个 task. 这个 task 特意没有列入 Gradle task 组, 因为它并不用于日常的使用场景.
  如果你在使用 IntelliJ IDEA, 你可能会看到 dokkaGenerateHtml Gradle task. 这个 task 只是 dokkaGeneratePublicationHtml 的别名. 这两个 task 执行完全相同的操作.
对于 Maven, 运行 dokka:dokka goal.
对于 CLI 运行器, 运行 HTML 依赖项集合.

配置

HTML 格式是 Dokka 的基本格式. 你可以使用以下选项对它进行配置:

// build.gradle.kts

dokka {
    pluginsConfiguration.html {
        customAssets.from("logo.png")
        customStyleSheets.from("styles.css")
        footerMessage.set("(c) Your Company")
        separateInheritedMembers.set(false)
        templatesDir.set(file("dokka/templates"))
        mergeImplicitExpectActualDeclarations.set(false)
    }
}

// build.gradle

dokka {
    pluginsConfiguration {
        html {
            customAssets.from("logo.png")
            customStyleSheets.from("styles.css")
            footerMessage.set("(c) Your Company")
            separateInheritedMembers.set(false)
            templatesDir.set(file("dokka/templates"))
            mergeImplicitExpectActualDeclarations.set(false)
        }
    }
}

<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>
                <separateInheritedMembers>false</separateInheritedMembers>
                <templatesDir>${project.basedir}/dokka/templates</templatesDir>
                <mergeImplicitExpectActualDeclarations>false</mergeImplicitExpectActualDeclarations>
            </org.jetbrains.dokka.base.DokkaBase>
        </pluginsConfiguration>
    </configuration>
</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\", \"separateInheritedMembers\": false, \"templatesDir\": \"dokka/templates\", \"mergeImplicitExpectActualDeclarations\": false}
"

通过 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}"
    }
  ]
}

配置选项

下表包括所有可以使用的配置选项, 以及它们的用途:

选项	描述
`customAssets`	要与文档绑定到一起的图片资源的路径列表. 图片资源可以使用任意的文件扩展名. 更多详情请参见自定义资源.
`customStyleSheets`	要与文档绑定到一起并在显示时使用的 `.css` 样式表的路径列表. 更多详情请参见自定义样式表.
`templatesDir`	包含自定义 HTML 模板的目录路径. 更多详情请参见模板.
`footerMessage`	在页脚显示的文字.
`separateInheritedMembers`	这是一个 boolean 选项. 如果设置为 `true`, Dokka 会将属性/函数与继承的属性/继承的函数分开显示. 这个设置默认关闭.
`mergeImplicitExpectActualDeclarations`	这是一个 boolean 选项. 如果设置为 `true`, Dokka 合并那些没有声明为 expect/actual 的声明, 但使用相同的完整限定名称. 这个设置对旧的代码库可能很有用. 这个设置默认关闭.

关于 Dokka plugin 配置的更多详情, 请参见配置 Dokka plugins.

自定义

为了帮助你为你的文档添加自己的外观和风格, HTML 格式支持很多的自定义选项.

自定义样式表

你可以使用 customStyleSheets 配置选项, 使用你自己的样式表. 这些配置会被应用于所有的页面.

可以通过提供相同名称的文件来覆盖 Dokka 的默认样式表:

样式表名称	描述
`style.css`	主样式表, 包含在所有页面中使用的大部分样式
`logo-styles.css`	页头 logo 样式
`prism.css`	用于 PrismJS 语法高亮度显示器的样式

Dokka 所有样式表的源代码, 请参见 GitHub.

自定义资源

你可以使用 customAssets 配置选项, 提供你自己的绑定到文档的图片.

这些文件会被复制到 <output>/images 目录.

对 customAssets 属性, 可以使用文件集合 (FileCollection):

customAssets.from("example.png", "example2.png")

可以通过提供相同名称的文件来覆盖 Dokka 的图片和图标. 最重要的是 logo-icon.svg, 它是用于页头的图片. 其他主要是图标.

Dokka 使用的所有图片, 请参见 GitHub.

修改 logo

要自定义 logo, 你可以从提供你自己的 logo-icon.svg 资源开始.

如果你不喜欢它的外观, 或者你想要使用 .png 文件, 而不是默认的 .svg 文件, 你可以覆盖 logo-styles.css 样式表来定制它.

具体的例子, 请参见我们的自定义格式的示例项目.

支持的最大 logo 尺寸是宽 120 像素, 高 36 像素. 如果你使用更大的图片, 它的大小会自动调整.

你可以使用 footerMessage 配置选项, 修改页脚中的文字.

模板

Dokka 提供了修改用于生成文档页面的 FreeMarker 模板的能力.

你可以完全彻底的修改页头, 添加你的自己的横幅/菜单/搜索, 负载析, 修改页面 body 样式, 等等等等.

Dokka 使用以下模板:

模板	描述
`base.ftl`	定义显示的所有页面的通常设计.
`includes/header.ftl`	页头, 默认包含 logo, 版本, 源代码集选择器, 浅色/深色主题切换, 以及搜索.
`includes/footer.ftl`	页脚, 包含 `footerMessage` 配置选项, 以及版权信息.
`includes/page_metadata.ftl`	在 `<head>` 容器内使用的元数据.
`includes/source_set_selector.ftl`	页头中的源代码集选择器.

基础模板是 base.ftl, 它引入(include)其它所有模板. Dokka 所有模板的源代码请参见 GitHub.

你可以使用 templatesDir 配置选项覆盖任何一个模板. Dokka 会在指定的目录搜索指定的模板名称. 如果无法找到用户定义的模板, 它会使用默认模板.

变量

下表是在所有模板内可以使用的变量:

变量	描述
`${pageName}`	页面名称
`${footerMessage}`	`footerMessage` 配置选项设置的文字
`${sourceSets}`	用于对跨平台页面的源代码集 List, 可为 null. List 中的每个元素包含 `name`, `platform`, 和 `filter` 属性.
`${projectName}`	项目名称. 只能在 `template_cmd` 命令内使用.
`${pathToRoot}`	从当前页面到根的路径. 可以用于定位资源, 只能在 `template_cmd` 命令内使用.

变量 projectName 和 pathToRoot 只能在 template_cmd 命令内使用, 因为它们需要更多的上下文信息, 因此需要在更晚的阶段解析:

<@template_cmd name="projectName">
    <span>${projectName}</span>
</@template_cmd>

命令

你也可以使用下面这些由 Dokka 定义的命令:

变量	描述
`<@content/>`	主页面内容.
`<@resources/>`	资源, 例如脚本和样式表.
`<@version/>`	从配置得到的子项目版本. 如果应用了 versioning plugin, 它会被替换为一个版本导航器.

2026/07/11