# HTML
> **Note:**
> 这篇向导适用于 Dokka Gradle plugin (DGP) v2 模式. DGP v1 模式不再支持. 要从 v1 模式升级到 v2 模式, 请遵循 [迁移向导](dokka-migration.html).
HTML 是 Dokka 的默认并且推荐的输出格式. 它支持 Kotlin Multiplatform, Android, 以及 Java 项目. 此外, 你可以使用 HTML 格式, 对单项目构建和多项目构建生成文档.
关于输出格式的示例, 请查看以下文档:
* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/)
* [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html)
* [Hexagon](https://hexagontk.com/stable/api/)
* [Ktor](https://api.ktor.io/)
* [OkHttp](https://square.github.io/okhttp/5.x/okhttp/okhttp3/)
* [Gradle](https://docs.gradle.org/current/kotlin-dsl/index.html)
## 生成 HTML 文档
所有的运行器都支持 HTML 输出格式. 要生成 HTML 文档, 请根据你的构建工具和运行器, 执行以下步骤:
* 对于 [Gradle](dokka-gradle.html#generate-documentation), 可以运行以下 task: * `dokkaGenerate`: 生成文档, 使用 [应用的插件支持的所有可用格式](dokka-gradle.html#configure-documentation-output-format). 这是对大多数用户推荐使用的 task. 在 IntelliJ IDEA 中使用这个 task 时, 它会输出一个可点击的链接. * `dokkaGeneratePublicationHtml`: 生成文档, 只使用 HTML 格式. 这个 task 将输出目录作为 `@OutputDirectory` 公开. 当你需要在其它 Gradle task 中使用生成的文件时, 例如上传到服务器, 移动到 GitHub Pages 目录, 或打包到 `javadoc.jar` 之内, 请使用这个 task. 这个 task 特意没有列入 Gradle task 组, 因为它并不用于日常的使用场景. > **Tip:** > 如果你在使用 IntelliJ IDEA, 你可能会看到 `dokkaGenerateHtml` Gradle task. 这个 task 只是 `dokkaGeneratePublicationHtml` 的别名. 这两个 task 执行完全相同的操作.
* 对于 [Maven](dokka-maven.html#generate-documentation), 运行 `dokka:dokka` goal.
* 对于 [CLI 运行器](dokka-cli.html#generate-documentation), 运行 HTML 依赖项集合.
> **Note:**
> 这种格式生成的 HTML 页面, 需要托管在 Web 服务器上, 才能正常显示它的全部内容.
>
>
>
> 你可以使用任何免费的静态网站托管服务, 例如 [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages).
>
>
>
> 在本地, 你可以使用 [内建的 IntelliJ Web 服务器](https://www.jetbrains.com/help/idea/php-built-in-web-server.html).
## 配置
HTML 格式是 Dokka 的基本格式. 你可以使用以下选项对它进行配置:
Gradle Kotlin DSL:
```KOTLIN
// 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)
}
}
```
Gradle Groovy DSL:
```GROOVY
// 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)
}
}
}
```
Maven:
```XML
org.jetbrains.dokka
dokka-maven-plugin
...
${project.basedir}/my-image.png
${project.basedir}/my-styles.css
(c) MyOrg 2022 Maven
false
${project.basedir}/dokka/templates
false
```
CLI:
通过 [命令行选项](dokka-cli.html#run-with-command-line-options):
```BASH
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 配置](dokka-cli.html#run-with-json-configuration):
```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` | 要与文档绑定到一起的图片资源的路径列表. 图片资源可以使用任意的文件扩展名. 更多详情请参见 [自定义资源](#customize-assets). |
| `customStyleSheets` | 要与文档绑定到一起并在显示时使用的 `.css` 样式表的路径列表. 更多详情请参见 [自定义样式表](#customize-styles). |
| `templatesDir` | 包含自定义 HTML 模板的目录路径. 更多详情请参见 [模板](#templates). |
| `footerMessage` | 在页脚显示的文字. |
| `separateInheritedMembers` | 这是一个 boolean 选项. 如果设置为 `true`, Dokka 会将属性/函数与继承的属性/继承的函数分开显示. 这个设置默认关闭. |
| `mergeImplicitExpectActualDeclarations` | 这是一个 boolean 选项. 如果设置为 `true`, Dokka 合并那些没有声明为 [expect/actual](https://www.jetbrains.com/help/kotlin-multiplatform-dev/multiplatform-connect-to-apis.html) 的声明, 但使用相同的完整限定名称. 这个设置对旧的代码库可能很有用. 这个设置默认关闭. |
关于 Dokka plugin 配置的更多详情, 请参见 [配置 Dokka plugins](dokka-plugins.html#configure-dokka-plugins).
## 自定义
为了帮助你为你的文档添加自己的外观和风格, HTML 格式支持很多的自定义选项.
### 自定义样式表
你可以使用 `customStyleSheets` [配置选项](#configuration), 使用你自己的样式表. 这些配置会被应用于所有的页面.
可以通过提供相同名称的文件来覆盖 Dokka 的默认样式表:
| 样式表名称 | 描述 |
| --- | --- |
| `style.css` | 主样式表, 包含在所有页面中使用的大部分样式 |
| `logo-styles.css` | 页头 logo 样式 |
| `prism.css` | 用于 [PrismJS](https://prismjs.com/) 语法高亮度显示器的样式 |
Dokka 所有样式表的源代码, 请参见 [GitHub](https://github.com/Kotlin/dokka/tree/2.2.0/dokka-subprojects/plugin-base/src/main/resources/dokka/styles).
### 自定义资源
你可以使用 `customAssets` [配置选项](#configuration), 提供你自己的绑定到文档的图片.
这些文件会被复制到 `