1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
|
[//]: # (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. |
|
