HTML

配置

HTML 格式是 Dokka 的基本格式, 因此它可以通过 DokkaBase 和 DokkaBaseConfiguration 类配置:

通过类型安全的 Kotlin DSL:

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:

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(
            // plugin 的完整限定名称, to, json 配置
            "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"
      "separateInheritedMembers": false,
      "templatesDir": "${file("dokka/templates")}",
      "mergeImplicitExpectActualDeclarations": false
    }
    """
    pluginsMapConfiguration.set(
        // plugin 的完整限定名称, :, json 配置
        ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration]
    )
}

<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.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 配置:

{
  "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 的声明, 但使用相同的完整限定名称. 这个设置对旧的代码库可能很有用. 这个设置默认关闭.

自定义

自定义样式表

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

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

模板

模板	描述
`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 命令内使用, 因为它们需要更多的上下文信息, 因此需要在更晚的阶段由 MultiModule task 解析:

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

命令

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

HTML﻿

生成 HTML 文档﻿

note

配置﻿

配置选项﻿

自定义﻿

自定义样式表﻿

自定义资源﻿

修改 logo﻿

修改页脚﻿

模板﻿

变量﻿

命令﻿

HTML

生成 HTML 文档

配置

配置选项

自定义

自定义样式表

自定义资源

修改 logo

修改页脚

模板

变量

命令