Configuration specific to HTML format¶

Prerequisites¶

Dokka's HTML format requires a web server to view documentation correctly. This can be achieved by using the one that is build in IntelliJ or providing your own. If this requisite is not fulfilled Dokka with fail to load navigation pane and search bars.

Important

Concepts specified below apply only to configuration of the Base Plugin (that contains HTML format) and needs to be applied via pluginsConfiguration and not on the root one.

Modifying assets¶

It is possible to change static assets that are used to generate dokka's HTML. Currently, user can modify:

customAssets
customStyleSheets

Every file provided in those values will be applied to every page.

Dokka uses 4 stylesheets:

style.css - main css file responsible for styling the page
jetbrains-mono.css - fonts used across dokka
logo-styles.css - logo styling
prism.css - code highlighting

Also, it uses js scripts. The actual ones are here. User can choose to add or override those files - stylesheets and js scripts. Resources will be overridden when in pluginConfiguration block there is a resource with the same name.

Dokka supports custom messages in the footer via footerMessage string property on base plugin configuration. Keep in mind that this value will be passed exactly to the output HTML, so it has to be valid and escaped correctly.

Separating inherited members¶

By setting a boolean property separateInheritedMembers dokka will split inherited members (like functions, properties etc.) from ones declared in viewed class. Separated members will have it's own tabs on the page.

Merging declarations with name clashing¶

By setting a boolean property mergeImplicitExpectActualDeclarations dokka will merge declarations that do not have expect/actual keywords but have the same fully qualified name. The declarations will be displayed on one page. By default, it is disabled. The page names of such declaration have a prefix that is the name of source set.

Examples¶

In order to override a logo and style it accordingly a css file named logo-styles.css is needed:

.library-name a {
    position: relative;
    --logo-width: 100px;
    margin-left: calc(var(--logo-width) + 5px);
}

.library-name a::before {
    content: '';
    background: url("https://upload.wikimedia.org/wikipedia/commons/9/9d/Ubuntu_logo.svg") center no-repeat;
    background-size: contain;
    position: absolute;
    width: var(--logo-width);
    height: 50px;
    top: -18px;
    left: calc(-1 * var(--logo-width) - 5px);
    /* other styles required to make your page pretty */
}

For build system specific instructions please visit dedicated pages: gradle, maven and cli

Custom HTML pages¶

Templates are taken from the folder that is defined by the templatesDir property. To customize HTML output, you can use the default template as a starting point.

Note

To change page assets, you can set properties customAssets and customStyleSheets. Assets are handled by Dokka itself, not FreeMaker.

Currently, there is only one template file with predefined name base.ftl. It defines general design of all pages to render.
If templatesDir is defined, Dokka will find the base.ftl file there.

Variables given below are available to the template: * ${pageName} - the page name * ${footerMessage} - text that is set by the footerMessage property * ${sourceSets} - a nullable list of source sets, only for multi-platform pages. Each source set has name, platfrom and filter properties.

Also, Dokka-defined directives can be used: * <@content/> - main content * <@resources/> - scripts, stylesheets * <@version/> - version (versioning-plugin will replace this with a version navigator) * <@template_cmd name="...""> ... - is used for variables that depend on the root project (such pathToRoot, projectName). They are available only inside the directive. This is processed by a multi-module task that assembles partial outputs from modules. Example:

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