Open AIDoc

简体中文

繁體中文
日本語
한국어

简体中文

繁體中文
日本語
한국어

Appearance

HTML ​

HTML 是 Dokka 的默认推荐输出格式。它目前处于 Beta 版，并且正在接近稳定版发布。

你可以浏览 kotlinx.coroutines 的文档来查看输出示例。

生成 HTML 文档 ​

HTML 作为输出格式受到所有运行器的支持。要生成 HTML 文档，请根据你使用的构建工具或运行器执行以下步骤：

  • 对于 Gradle，运行 dokkaHtml 或 dokkaHtmlMultiModule 任务。
  • 对于 Maven，运行 dokka:dokka 目标。
  • 对于 CLI runner，运行并设置 HTML 依赖项。

通过此格式生成的 HTML 页面需要托管在 Web 服务器上才能正确渲染所有内容。

你可以使用任何免费的静态网站托管服务，例如 GitHub Pages。

在本地，你可以使用 IntelliJ 内置 Web 服务器。

配置 ​

HTML 格式是 Dokka 的基础格式，因此可以通过 DokkaBase 和 DokkaBaseConfiguration 类进行配置：

通过类型安全的 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:2.0.0")
    }
}

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

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

通过命令行选项：

Bash
java -jar dokka-cli-2.0.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 配置：

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这是一个布尔选项。如果设置为 true，Dokka 会单独渲染属性/函数和继承的属性/继承的函数。默认情况下此选项禁用。
mergeImplicitExpectActualDeclarations这是一个布尔选项。如果设置为 true，Dokka 会合并那些未声明为 expect/actual 但具有相同完全限定名的声明。这对于遗留代码库可能很有用。默认情况下此选项禁用。

关于配置 Dokka 插件，请参见配置 Dokka 插件。

自定义 ​

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

自定义样式 ​

你可以使用 customStyleSheets 配置选项来使用你自己的样式表。这些样式会应用于每个页面。

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

样式表名称描述
style.css主样式表，包含所有页面中使用的大部分样式
logo-styles.css页眉 Logo 样式
prism.cssPrismJS 语法高亮器的样式

Dokka 所有样式表的源代码在 GitHub 上可用。

自定义资源 ​

你可以使用 customAssets 配置选项来提供你自己的图片以与文档捆绑。

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

可以通过提供同名文件来覆盖 Dokka 的图片和图标。其中最有用和相关的是 logo-icon.svg，它是页眉中使用的图片。其余大部分是图标。

你可以在GitHub上找到 Dokka 使用的所有图片。

要自定义 Logo，你可以首先为 logo-icon.svg 提供你自己的资源。

如果你不喜欢它的外观，或者你想使用 .png 文件而不是默认的 .svg 文件，你可以覆盖 logo-styles.css 样式表来对其进行自定义。

关于如何执行此操作的示例，请参见我们的自定义格式示例项目。

支持的最大 Logo 尺寸为宽度 120 像素，高度 36 像素。如果你使用更大的图片，它将自动调整大小。

修改页脚 ​

你可以使用 footerMessage 配置选项来修改页脚中的文本。

模板 ​

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

你可以完全更改页眉，添加你自己的横幅/菜单/搜索，加载分析，更改正文样式等等。

Dokka 使用以下模板：

模板描述
base.ftl定义所有要渲染页面的总体设计。
includes/header.ftl默认包含 Logo、版本、源代码集选择器、亮/暗主题切换和搜索的页面页眉。
includes/footer.ftl包含 footerMessage 配置选项和版权的页面页脚。
includes/page_metadata.ftl<head> 容器中使用的元数据。
includes/source_set_selector.ftl页眉中的源代码集选择器。

基础模板是 base.ftl，它包含了所有剩余的列出的模板。你可以在GitHub上找到 Dokka 所有模板的源代码。

你可以使用 templatesDir 配置选项来覆盖任何模板。Dokka 会在给定目录中搜索完全匹配的模板名称。如果未能找到用户定义的模板，它将使用默认模板。

变量 ​

所有模板中都可以使用以下变量：

变量描述
${pageName}页面名称
${footerMessage}由 footerMessage 配置选项设置的文本
${sourceSets}用于多平台页面的源代码集的可空 list。每个项都具有 name、platform 和 filter 属性。
${projectName}项目名称。它仅在 template_cmd 指令中可用。
${pathToRoot}从当前页面到根目录的路径。它对于定位资源很有用，并且仅在 template_cmd 指令中可用。

变量 projectName 和 pathToRoot 仅在 template_cmd 指令中可用，因为它们需要更多上下文，因此需要由 MultiModule 任务在后期阶段解析：

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

指令 ​

你还可以使用以下 Dokka 定义的指令：

变量描述
<@content/>主要页面内容。
<@resources/>脚本和样式表等资源。
<@version/>从配置中获取的模块版本。如果应用了版本化插件，它将被版本导航器替换。

Copyright © 2025 Open AIDoc.