Spec-Zone.ru › Kotlin 2

HTML

Это руководство относится к режиму DGP v2 плагина Dokka Gradle. Режим DGP v1 больше не поддерживается. Чтобы перейти с режима v1 на режим v2, следуйте руководству по миграции.

HTML — это формат вывода Dokka по умолчанию и рекомендуемый формат. Он поддерживает проекты Kotlin Multiplatform, Android и Java. Кроме того, формат HTML можно использовать для документирования сборок как с одним проектом, так и с несколькими проектами.

Примеры вывода в формате HTML можно найти в следующей документации:

  • kotlinx.coroutines

  • Bitmovin

  • Hexagon

  • Ktor

  • OkHttp

  • Gradle

Создание документации HTML

Формат HTML поддерживается всеми средствами запуска. Чтобы создать документацию HTML, выполните следующие действия в зависимости от используемого инструмента сборки или средства запуска:

  • Для Gradle можно выполнить следующие задачи:

    • dokkaGenerate для создания документации во всех доступных форматах, поддерживаемых применёнными плагинами. Эта задача рекомендуется большинству пользователей. При запуске этой задачи в IntelliJ IDEA в журнале выводится ссылка на результат, по которой можно перейти.

    • dokkaGeneratePublicationHtml для создания документации только в формате HTML. Эта задача предоставляет каталог вывода в качестве @OutputDirectory. Используйте её, если нужно использовать созданные файлы в других задачах Gradle, например загрузить их на сервер, переместить в каталог GitHub Pages или упаковать в javadoc.jar. Эта задача намеренно не включена в группы задач Gradle, поскольку не предназначена для повседневного использования.

      При использовании IntelliJ IDEA может отображаться задача Gradle dokkaGenerateHtml. Эта задача является просто псевдонимом dokkaGeneratePublicationHtml. Обе задачи выполняют совершенно одинаковую операцию.

  • Для Maven выполните цель dokka:dokka.

  • Для средства запуска CLI укажите зависимости HTML при запуске.

Чтобы все элементы страниц HTML, созданных в этом формате, отображались правильно, их необходимо разместить на веб-сервере.

Можно воспользоваться любым бесплатным сервисом статического хостинга, например GitHub Pages.

Локально можно использовать встроенный веб-сервер IntelliJ.

Настройка

Формат HTML — базовый формат Dokka. Его можно настроить с помощью следующих параметров:

// 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)
    }
}
// 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)
        }
    }
}
<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>

Через параметры командной строки:

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:

{
  "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

Список путей к файлам изображений, включаемым в документацию. Файлы изображений могут иметь любое расширение. Дополнительную информацию см. в разделе Настройка ресурсов.

customStyleSheets

Список путей к таблицам стилей .css, включаемым в документацию и используемым для её отображения. Дополнительную информацию см. в разделе Настройка стилей.

templatesDir

Путь к каталогу с пользовательскими HTML-шаблонами. Дополнительную информацию см. в разделе Шаблоны.

footerMessage

Текст, отображаемый в нижнем колонтитуле.

separateInheritedMembers

Этот параметр имеет логический тип. Если установить значение true, Dokka будет отображать свойства и функции, а также унаследованные свойства и функции отдельно. По умолчанию этот параметр отключён.

mergeImplicitExpectActualDeclarations

Этот параметр имеет логический тип. Если установить значение true, Dokka объединит объявления, не объявленные как expect/actual, но имеющие одинаковое полное имя. Это может быть полезно для устаревших кодовых баз. По умолчанию этот параметр отключён.

Дополнительную информацию о настройке плагинов Dokka см. в разделе Настройка плагинов Dokka.

Настройка внешнего вида

Формат HTML поддерживает ряд параметров настройки, которые помогут придать документации желаемый внешний вид.

Настройка стилей

Вы можете использовать собственные таблицы стилей с помощью параметра конфигурации customStyleSheets. Они применяются на каждой странице.

Также можно переопределить таблицы стилей Dokka по умолчанию, предоставив файлы с такими же именами:

Имя таблицы стилей

Описание

style.css

Основная таблица стилей; содержит большую часть стилей, используемых на всех страницах

logo-styles.css

Стили логотипа в заголовке страницы

prism.css

Стили подсветчика синтаксиса PrismJS

Исходный код всех таблиц стилей Dokka доступен на GitHub.

Настройка ресурсов

Вы можете включить собственные изображения в документацию с помощью параметра конфигурации customAssets.

Эти файлы копируются в каталог <output>/images.

Для коллекций файлов можно использовать свойство customAssets (FileCollection):

customAssets.from("example.png", "example2.png")

Вы можете переопределить изображения и значки Dokka, предоставив файлы с такими же именами. Самый полезный и актуальный файл — logo-icon.svg, изображение, используемое в заголовке страницы. Остальные файлы — преимущественно значки.

Все изображения, используемые Dokka, можно найти на GitHub.

Изменение логотипа

Чтобы настроить логотип, сначала добавьте собственный ресурс для logo-icon.svg.

Если вас не устраивает его внешний вид или вы хотите использовать файл .png вместо файла .svg по умолчанию, можно переопределить таблицу стилей logo-styles.css, чтобы настроить логотип.

Пример такой настройки см. в нашем проекте с пользовательским форматом.

Максимальный поддерживаемый размер логотипа — 120 пикселей в ширину и 36 пикселей в высоту. Если изображение больше, его размер будет автоматически уменьшен.

Изменение нижнего колонтитула

Текст в нижнем колонтитуле можно изменить с помощью параметра конфигурации footerMessage.

Шаблоны

Dokka позволяет изменять шаблоны FreeMarker, используемые для создания страниц документации.

Вы можете полностью изменить заголовок страницы, добавить собственные баннеры, меню и поиск, подключить аналитику, изменить стили содержимого и многое другое.

Dokka использует следующие шаблоны:

Шаблон

Описание

base.ftl

Задаёт общий дизайн всех создаваемых страниц.

includes/header.ftl

Заголовок страницы, который по умолчанию содержит логотип, версию, переключатель наборов исходного кода, переключатель светлой и тёмной темы, а также поиск.

includes/footer.ftl

Нижний колонтитул страницы, содержащий параметр конфигурации footerMessage и сведения об авторских правах.

includes/page_metadata.ftl

Метаданные, используемые внутри контейнера <head>.

includes/source_set_selector.ftl

Переключатель наборов исходного кода в заголовке страницы.

Базовый шаблон — base.ftl; он включает все остальные перечисленные шаблоны. Исходный код всех шаблонов Dokka можно найти на GitHub.

Любой шаблон можно переопределить с помощью параметра конфигурации templatesDir. Dokka ищет в указанном каталоге шаблоны с точными именами. Если пользовательские шаблоны не найдены, используются шаблоны по умолчанию.

Переменные

Во всех шаблонах доступны следующие переменные:

Переменная

Описание

${pageName}

Имя страницы

${footerMessage}

Текст, заданный с помощью параметра конфигурации footerMessage

${sourceSets}

Список наборов исходного кода для многоплатформенных страниц; может быть пустым. Каждый элемент имеет свойства name, platform и filter.

${projectName}

Имя проекта. Доступно только внутри директивы template_cmd.

${pathToRoot}

Путь от текущей страницы к корневому каталогу. Полезен для поиска ресурсов и доступен только внутри директивы template_cmd.

Переменные projectName и pathToRoot доступны только внутри директивы template_cmd, поскольку для них требуется дополнительный контекст, поэтому их значения определяются на более поздних этапах:

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

Директивы

Также можно использовать следующие директивы, определённые в Dokka:

Переменная

Описание

<@content/>

Основное содержимое страницы.

<@resources/>

Ресурсы, такие как скрипты и таблицы стилей.

<@version/>

Версия подпроекта, взятая из конфигурации. Если применён плагин управления версиями, вместо неё отображается навигатор версий.

18 декабря 2025 г.
CLIJavadoc

© 2010–2026 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/dokka-html.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API