[//]: # (title: 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](https://kotlinlang.org/api/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](dokka-gradle.md#generate-documentation), run `dokkaHtml` or `dokkaHtmlMultiModule` tasks.
* For [Maven](dokka-maven.md#generate-documentation), run the `dokka:dokka` goal.
* For [CLI runner](dokka-cli.md#generate-documentation), 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](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages).
>
> Locally, you can use the [built-in IntelliJ web server](https://www.jetbrains.com/help/idea/php-built-in-web-server.html).
>
{type="note"}

## Configuration

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

<tabs group="build-script">
<tab title="Kotlin" group-key="kotlin">

Via type-safe 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:%dokkaVersion%")
    }
}

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

Via 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
        )
    )
}
```

</tab>
<tab title="Groovy" group-key="groovy">

```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]
    )
}
```

</tab>
<tab title="Maven" group-key="mvn">

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

</tab>
<tab title="CLI" group-key="cli">

Via [command line options](dokka-cli.md#run-with-command-line-options):

```Bash
java -jar dokka-cli-%dokkaVersion%.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}
"
```

Via [JSON configuration](dokka-cli.md#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}"
    }
  ]
}
```

</tab>
</tabs>

### Configuration options

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

| **Option**                              | **Description**                                                                                                                                                                                                                                                                               |
|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `customAssets`                          | List of paths for image assets to be bundled with documentation. The image assets can have any file extension. For more information, see [Customizing assets](#customize-assets).                                                                                                             |
| `customStyleSheets`                     | List of paths for `.css` stylesheets to be bundled with documentation and used for rendering. For more information, see [Customizing styles](#customize-styles).                                                                                                                              |
| `templatesDir`                          | Path to the directory containing custom HTML templates. For more information, see [Templates](#templates).                                                                                                                                                                                    |
| `footerMessage`                         | The text displayed in the footer.                                                                                                                                                                                                                                                             |
| `separateInheritedMembers`              | This is a boolean option. If set to `true`, Dokka renders properties/functions and inherited properties/inherited functions separately. This is disabled by default.                                                                                                                          |
| `mergeImplicitExpectActualDeclarations` | This is a boolean option. If set to `true`, Dokka merges declarations that are not declared as [expect/actual](https://kotlinlang.org/docs/multiplatform-connect-to-apis.html), 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](dokka-plugins.md#configure-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](#configuration). These are applied to every page.

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

| **Stylesheet name**  | **Description**                                                    |
|----------------------|--------------------------------------------------------------------|
| `style.css`          | Main stylesheet, contains most of the styles used across all pages |
| `logo-styles.css`    | Header logo styling                                                |
| `prism.css`          | Styles for [PrismJS](https://prismjs.com/) syntax highlighter      |
| `jetbrains-mono.css` | Font styling                                                       |

The source code for all of Dokka's stylesheets is
[available on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/styles).

### Customize assets

You can provide your own images to be bundled with documentation by using the `customAssets`
[configuration option](#configuration). 

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](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/images).

### Change the logo

To customize the logo, you can begin by [providing your own asset](#customize-assets) 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](#customize-styles) to customize it.

For an example of how to do this, see our
[custom format example project](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle/dokka-customFormat-example).

### Modify the footer

You can modify text in the footer by using the `footerMessage` [configuration option](#configuration).

### Templates

Dokka provides the ability to modify [FreeMarker](https://freemarker.apache.org/) 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:

| **Template**                       | **Description**                                                                                                       |
|------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| `base.ftl`                         | Defines the general design of all pages to be rendered.                                                               |
| `includes/header.ftl`              | The page header that by default contains the logo, version, source set selector, light/dark theme switch, and search. |
| `includes/footer.ftl`              | The page footer that contains the `footerMessage` [configuration option](#configuration) and copyright.               |
| `includes/page_metadata.ftl`       | Metadata used within `<head>` container.                                                                              |
| `includes/source_set_selector.ftl` | [The source set](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) 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](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/base/src/main/resources/dokka/templates).

You can override any template by using the `templatesDir` [configuration option](#configuration). 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:

| **Variable**       | **Description**                                                                                                                                                                                    |
|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `${pageName}`      | The page name                                                                                                                                                                                      |
| `${footerMessage}` | The text which is set by the `footerMessage` [configuration option](#configuration)                                                                                                                |
| `${sourceSets}`    | A nullable list of [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#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](dokka-gradle.md#multi-project-builds) task:

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

#### Directives

You can also use the following Dokka-defined [directives](https://freemarker.apache.org/docs/ref_directive_userDefined.html):

| **Variable**    | **Description**                                                                                                                                                                              |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `<@content/>`   | The main page content.                                                                                                                                                                       |
| `<@resources/>` | Resources such as scripts and stylesheets.                                                                                                                                                   |
| `<@version/>`   | The module version taken from configuration. If the [versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) is applied, it is replaced with a version navigator. |