HTML
HTML 是 Dokka 的默认并且推荐的输出格式. 目前处于 Beta 版, 正在接近稳定发布版.
你可以浏览 kotlinx.coroutines 的文档, 看看 HTML 输出的示例.
生成 HTML 文档
所有的运行器都支持 HTML 输出格式. 要生成 HTML 文档, 请根据你的构建工具和运行器, 执行以下步骤:
配置
HTML 格式是 Dokka 的基本格式, 因此它可以通过 DokkaBase
和 DokkaBaseConfiguration
类配置:
通过类型安全的 Kotlin DSL:
通过 JSON:
通过 命令行选项:
通过 JSON 配置:
配置选项
下表包括所有可以使用的配置选项, 以及它们的用途.
选项 | 描述 |
---|---|
| 要与文档绑定到一起的图片资源的路径列表. 图片资源可以使用任意的文件扩展名. 更多详情请参见 自定义资源. |
| 要与文档绑定到一起并在显示时使用的 |
| 包含自定义 HTML 模板的目录路径. 更多详情请参见 模板. |
| 在页脚显示的文字. |
| 这是一个 boolean 选项. 如果设置为 |
| 这是一个 boolean 选项. 如果设置为 |
关于 Dokka plugin 配置的更多详情, 请参见 配置 Dokka plugins.
自定义
为了帮助你为你的文档添加自己的外观和风格, HTML 格式支持很多的自定义选项.
自定义样式表
你可以使用 customStyleSheets
配置选项, 使用你自己的样式表. 这些配置会被应用于所有的页面.
可以通过提供相同名称的文件来覆盖 Dokka 的默认样式表:
样式表名称 | 描述 |
---|---|
| 主样式表, 包含在所有页面中使用的大部分样式 |
| 页头 logo 样式 |
| 用于 PrismJS 语法高亮度显示器的样式 |
Dokka 所有样式表的源代码, 请参见 GitHub.
自定义资源
你可以使用 customAssets
配置选项, 提供你自己的绑定到文档的图片.
这些文件会被复制到 <output>/images
目录.
可以通过提供相同名称的文件来覆盖 Dokka 的图片和图标. 最重要的是 logo-icon.svg
, 它是用于页头的图片. 其他主要是图标.
Dokka 使用的所有图片, 请参见 GitHub.
修改 logo
要自定义 logo, 你可以从 提供你自己的 logo-icon.svg
资源 开始.
如果你不喜欢它的外观, 或者你想要使用 .png
文件, 而不是默认的 .svg
文件, 你可以 覆盖 logo-styles.css
样式表 来定制它.
具体的例子, 请参见我们的 自定义格式的示例项目.
修改页脚
你可以使用 footerMessage
配置选项, 修改页脚中的文字.
模板
Dokka 提供了修改用于生成文档页面的 FreeMarker 模板的能力.
你可以完全彻底的修改页头, 添加你的自己的横幅/菜单/搜索, 负载析, 修改页面 body 样式, 等等等等.
Dokka 使用以下模板:
模板 | 描述 |
---|---|
| 定义显示的所有页面的通常设计. |
| 页头, 默认包含 logo, 版本, 源代码集选择器, 浅色/深色主题切换, 以及搜索. |
| 页脚, 包含 |
| 在 |
| 页头中的 源代码集 选择器. |
基础模板是 base.ftl
, 它引入(include)其它所有模板. Dokka 所有模板的源代码请参见 GitHub.
你可以使用 templatesDir
配置选项 覆盖任何一个模板. Dokka 会在指定的目录搜索指定的模板名称. 如果无法找到用户定义的模板, 它会使用默认模板.
变量
下表是在所有模板内可以使用的变量:
变量 | 描述 |
---|---|
| 页面名称 |
|
|
| 用于对跨平台页面的 源代码集 List, 可为 null. List 中的每个元素包含 |
| 项目名称. 只能在 |
| 从当前页面到根的路径. 可以用于定位资源, 只能在 |
变量 projectName
和 pathToRoot
只能在 template_cmd
命令内使用, 因为它们需要更多的上下文信息, 因此需要在更晚的阶段由 MultiModule task 解析:
命令
你也可以使用下面这些由 Dokka 定义的 命令:
变量 | 描述 |
---|---|
| 主页面内容. |
| 资源, 例如脚本和样式表. |
| 从配置得到的模块版本. 如果应用了 versioning plugin, 它会被替换为一个版本导航器. |