HTML
HTML — это формат вывода Dokka по умолчанию и рекомендуемый формат. Он поддерживает проекты Kotlin Multiplatform, Android и Java. Кроме того, формат HTML можно использовать для документирования сборок как с одним проектом, так и с несколькими проектами.
Примеры вывода в формате HTML можно найти в следующей документации:
Создание документации HTML
Формат HTML поддерживается всеми средствами запуска. Чтобы создать документацию HTML, выполните следующие действия в зависимости от используемого инструмента сборки или средства запуска:
-
Для Gradle можно выполнить следующие задачи:
dokkaGenerateдля создания документации во всех доступных форматах, поддерживаемых применёнными плагинами. Эта задача рекомендуется большинству пользователей. При запуске этой задачи в IntelliJ IDEA в журнале выводится ссылка на результат, по которой можно перейти.-
dokkaGeneratePublicationHtmlдля создания документации только в формате HTML. Эта задача предоставляет каталог вывода в качестве@OutputDirectory. Используйте её, если нужно использовать созданные файлы в других задачах Gradle, например загрузить их на сервер, переместить в каталог GitHub Pages или упаковать вjavadoc.jar. Эта задача намеренно не включена в группы задач Gradle, поскольку не предназначена для повседневного использования.
Для Maven выполните цель
dokka:dokka.Для средства запуска CLI укажите зависимости HTML при запуске.
Настройка
Формат 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}"
}
]
}
Параметры конфигурации
В таблице ниже перечислены все возможные параметры конфигурации и их назначение:
Параметр |
Описание |
|---|---|
|
Список путей к файлам изображений, включаемым в документацию. Файлы изображений могут иметь любое расширение. Дополнительную информацию см. в разделе Настройка ресурсов. |
|
Список путей к таблицам стилей |
|
Путь к каталогу с пользовательскими HTML-шаблонами. Дополнительную информацию см. в разделе Шаблоны. |
|
Текст, отображаемый в нижнем колонтитуле. |
|
Этот параметр имеет логический тип. Если установить значение |
|
Этот параметр имеет логический тип. Если установить значение |
Дополнительную информацию о настройке плагинов Dokka см. в разделе Настройка плагинов Dokka.
Настройка внешнего вида
Формат HTML поддерживает ряд параметров настройки, которые помогут придать документации желаемый внешний вид.
Настройка стилей
Вы можете использовать собственные таблицы стилей с помощью параметра конфигурации customStyleSheets. Они применяются на каждой странице.
Также можно переопределить таблицы стилей Dokka по умолчанию, предоставив файлы с такими же именами:
Имя таблицы стилей |
Описание |
|---|---|
|
Основная таблица стилей; содержит большую часть стилей, используемых на всех страницах |
|
Стили логотипа в заголовке страницы |
|
Стили подсветчика синтаксиса 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; он включает все остальные перечисленные шаблоны. Исходный код всех шаблонов Dokka можно найти на GitHub.
Любой шаблон можно переопределить с помощью параметра конфигурации templatesDir. Dokka ищет в указанном каталоге шаблоны с точными именами. Если пользовательские шаблоны не найдены, используются шаблоны по умолчанию.
Переменные
Во всех шаблонах доступны следующие переменные:
Переменная |
Описание |
|---|---|
|
Имя страницы |
|
Текст, заданный с помощью параметра конфигурации |
|
Список наборов исходного кода для многоплатформенных страниц; может быть пустым. Каждый элемент имеет свойства |
|
Имя проекта. Доступно только внутри директивы |
|
Путь от текущей страницы к корневому каталогу. Полезен для поиска ресурсов и доступен только внутри директивы |
Переменные projectName и pathToRoot доступны только внутри директивы template_cmd, поскольку для них требуется дополнительный контекст, поэтому их значения определяются на более поздних этапах:
<@template_cmd name="projectName">
<span>${projectName}</span>
</@template_cmd>
Директивы
Также можно использовать следующие директивы, определённые в Dokka:
Переменная |
Описание |
|---|---|
|
Основное содержимое страницы. |
|
Ресурсы, такие как скрипты и таблицы стилей. |
|
Версия подпроекта, взятая из конфигурации. Если применён плагин управления версиями, вместо неё отображается навигатор версий. |
© 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