HTML

HTML is Dokka’s default and recommended output format. It is currently in Beta and approaching the Stable release.

You can see an example of the output by browsing documentation for kotlinx.coroutines.

Generate HTML documentation

HTML as an output format is supported by all runners. To generate HTML documentation, follow these steps depending on your build tool or runner:

  • For Gradle, run dokkaHtml or dokkaHtmlMultiModule tasks.
  • For Maven, run the dokka:dokka goal.
  • For CLI runner, run with HTML dependencies set.

HTML pages generated by this format need to be hosted on a web server in order to render everything correctly.

You can use any free static site hosting service, such as GitHub Pages.

Locally, you can use the built-in IntelliJ web server.

HTML - 图1

Configuration

HTML format is Dokka’s base format, so it is configurable through DokkaBase and DokkaBaseConfiguration classes:

【Kotlin】

Via type-safe Kotlin DSL:

  1. import org.jetbrains.dokka.base.DokkaBase
  2. import org.jetbrains.dokka.gradle.DokkaTask
  3. import org.jetbrains.dokka.base.DokkaBaseConfiguration
  4. buildscript {
  5. dependencies {
  6. classpath("org.jetbrains.dokka:dokka-base:1.7.20")
  7. }
  8. }
  9. tasks.withType<DokkaTask>().configureEach {
  10. pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
  11. customAssets = listOf(file("my-image.png"))
  12. customStyleSheets = listOf(file("my-styles.css"))
  13. footerMessage = "(c) 2022 MyOrg"
  14. separateInheritedMembers = false
  15. templatesDir = file("dokka/templates")
  16. mergeImplicitExpectActualDeclarations = false
  17. }
  18. }

Via JSON:

  1. import org.jetbrains.dokka.gradle.DokkaTask
  2. tasks.withType<DokkaTask>().configureEach {
  3. val dokkaBaseConfiguration = """
  4. {
  5. "customAssets": ["${file("assets/my-image.png")}"],
  6. "customStyleSheets": ["${file("assets/my-styles.css")}"],
  7. "footerMessage": "(c) 2022 MyOrg",
  8. "separateInheritedMembers": false,
  9. "templatesDir": "${file("dokka/templates")}",
  10. "mergeImplicitExpectActualDeclarations": false
  11. }
  12. """
  13. pluginsMapConfiguration.set(
  14. mapOf(
  15. // fully qualified plugin name to json configuration
  16. "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration
  17. )
  18. )
  19. }

【Groovy】

  1. import org.jetbrains.dokka.gradle.DokkaTask
  2. tasks.withType(DokkaTask.class) {
  3. String dokkaBaseConfiguration = """
  4. {
  5. "customAssets": ["${file("assets/my-image.png")}"],
  6. "customStyleSheets": ["${file("assets/my-styles.css")}"],
  7. "footerMessage": "(c) 2022 MyOrg"
  8. "separateInheritedMembers": false,
  9. "templatesDir": "${file("dokka/templates")}",
  10. "mergeImplicitExpectActualDeclarations": false
  11. }
  12. """
  13. pluginsMapConfiguration.set(
  14. // fully qualified plugin name to json configuration
  15. ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration]
  16. )
  17. }

【Maven】

  1. <plugin>
  2. <groupId>org.jetbrains.dokka</groupId>
  3. <artifactId>dokka-maven-plugin</artifactId>
  4. ...
  5. <configuration>
  6. <pluginsConfiguration>
  7. <!-- Fully qualified plugin name -->
  8. <org.jetbrains.dokka.base.DokkaBase>
  9. <!-- Options by name -->
  10. <customAssets>
  11. <asset>${project.basedir}/my-image.png</asset>
  12. </customAssets>
  13. <customStyleSheets>
  14. <stylesheet>${project.basedir}/my-styles.css</stylesheet>
  15. </customStyleSheets>
  16. <footerMessage>(c) MyOrg 2022 Maven</footerMessage>
  17. <separateInheritedMembers>false</separateInheritedMembers>
  18. <templatesDir>${project.basedir}/dokka/templates</templatesDir>
  19. <mergeImplicitExpectActualDeclarations>false</mergeImplicitExpectActualDeclarations>
  20. </org.jetbrains.dokka.base.DokkaBase>
  21. </pluginsConfiguration>
  22. </configuration>
  23. </plugin>

【CLI】

Via command line options:

  1. java -jar dokka-cli-1.7.20.jar \
  2. ...
  3. -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}
  4. "

Via JSON configuration:

  1. {
  2. "moduleName": "Dokka Example",
  3. "pluginsConfiguration": [
  4. {
  5. "fqPluginName": "org.jetbrains.dokka.base.DokkaBase",
  6. "serializationFormat": "JSON",
  7. "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\", \"separateInheritedMembers\": false, \"templatesDir\": \"dokka/templates\", \"mergeImplicitExpectActualDeclarations\": false}"
  8. }
  9. ]
  10. }

Configuration options

The table below contains all of the possible configuration options and their purpose.

OptionDescription
customAssetsList of paths for image assets to be bundled with documentation. The image assets can have any file extension. For more information, see Customizing assets.
customStyleSheetsList of paths for .css stylesheets to be bundled with documentation and used for rendering. For more information, see Customizing styles.
templatesDirPath to the directory containing custom HTML templates. For more information, see Templates.
footerMessageThe text displayed in the footer.
separateInheritedMembersThis is a boolean option. If set to true, Dokka renders properties/functions and inherited properties/inherited functions separately. This is disabled by default.
mergeImplicitExpectActualDeclarationsThis is a boolean option. If set to true, Dokka merges declarations that are not declared as expect/actual, but have the same fully qualified name. This can be useful for legacy codebases. This is disabled by default.

For more information about configuring Dokka plugins, see Configuring Dokka plugins.

Customization

To help you add your own look and feel to your documentation, the HTML format supports a number of customization options.

Customize styles

You can use your own stylesheets by using the customStyleSheets configuration option. These are applied to every page.

It’s also possible to override Dokka’s default stylesheets by providing files with the same name:

Stylesheet nameDescription
style.cssMain stylesheet, contains most of the styles used across all pages
logo-styles.cssHeader logo styling
prism.cssStyles for PrismJS syntax highlighter

The source code for all of Dokka’s stylesheets is available on GitHub.

Customize assets

You can provide your own images to be bundled with documentation by using the customAssets configuration option.

These files are copied to the <output>/images directory.

It’s possible to override Dokka’s images and icons by providing files with the same name. The most useful and relevant one being logo-icon.svg, which is the image that’s used in the header. The rest is mostly icons.

You can find all images used by Dokka on GitHub.

To customize the logo, you can begin by providing your own asset for logo-icon.svg.

If you don’t like how it looks, or you want to use a .png file instead of the default .svg file, you can override the logo-styles.css stylesheet to customize it.

For an example of how to do this, see our custom format example project.

You can modify text in the footer by using the footerMessage configuration option.

Templates

Dokka provides the ability to modify FreeMarker templates used for generating documentation pages.

You can change the header completely, add your own banners/menus/search, load analytics, change body styling and so on.

Dokka uses the following templates:

TemplateDescription
base.ftlDefines the general design of all pages to be rendered.
includes/header.ftlThe page header that by default contains the logo, version, source set selector, light/dark theme switch, and search.
includes/footer.ftlThe page footer that contains the footerMessage configuration option and copyright.
includes/page_metadata.ftlMetadata used within <head> container.
includes/source_set_selector.ftlThe source set selector in the header.

The base template is base.ftl and it includes all of the remaining listed templates. You can find the source code for all of Dokka’s templates on GitHub.

You can override any template by using the templatesDir configuration option. Dokka searches for the exact template names within the given directory. If it fails to find user-defined templates, it uses the default templates.

Variables

The following variables are available inside all templates:

VariableDescription
${pageName}The page name
${footerMessage}The text which is set by the footerMessage configuration option
${sourceSets}A nullable list of source sets for multi-platform pages. Each item has name, platform, and filter properties.
${projectName}The project name. It’s available only within the template_cmd directive.
${pathToRoot}The path to root from the current page. It’s useful for locating assets and is available only within the template_cmd directive.

Variables projectName and pathToRoot are available only within the template_cmd directive as they require more context and thus they need to be resolved at later stages by the MultiModule task:

  1. <@template_cmd name="projectName">
  2. <span>${projectName}</span>
  3. </@template_cmd>

Directives

You can also use the following Dokka-defined directives:

VariableDescription
<@content/>The main page content.
<@resources/>Resources such as scripts and stylesheets.
<@version/>The module version taken from configuration. If the versioning plugin is applied, it is replaced with a version navigator.