Edit Page

Markdown

最终更新: 2024/03/21

Markdown 输出格式还处于 Alpha 状态, 因此你在使用时可能遇到 bug, 或迁移问题. 使用这个功能时, 请自行承担风险.

Dokka 能够生成 GitHub 风格 和 Jekyll 兼容的 Markdown 格式文档.

使用这些格式, 你可以更加自由的将文档发布到网站, 因为输出可以嵌入到你的文档页面之内. 例如, 象 OkHttp's API 参考文档 页面.

Markdown 输出格式作为 Dokka plugins 来实现, 由 Dokka 开发组维护, 并且是开源的.

GFM

GFM 输出格式会生成 GitHub 风格的 Markdown 格式的文档.

Gradle plugin for Dokka 包含了 GFM 输出格式. 你可以通过以下 task 使用它:

Task 描述

dokkaGfm

 为单个项目生成生成 GFM 文档.

dokkaGfmMultiModule

只为多项目构建中的父项目创建的 MultiModule task. 它会为子项目生成文档, 并将所有的输出合并到单个位置, 使用共同的内容目录.

dokkaGfmCollector

只为多项目构建中的父项目创建的 Collector task. 它会为每个子项目调用 dokkaGfm, 并将所有的输出合并到一个单独的虚拟项目.

由于 GFM 格式是以 Dokka plugin 方式实现的, 因此你需要以 plugin 依赖项的方式使用它: 

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <dokkaPlugins>
            <plugin>
                <groupId>org.jetbrains.dokka</groupId>
                <artifactId>gfm-plugin</artifactId>
                <version>1.9.20</version>
            </plugin>
        </dokkaPlugins>
    </configuration>
</plugin>

完成上面的配置之后, 请运行 dokka:dokka goal 来生成 GFM 格式文档.

更多详情, 请参见 Maven plugin 文档中的 其它输出格式.

由于 GFM 格式是以 Dokka plugin 方式实现的, 因此你需要 下载 JAR 文件, 并将它传递给 pluginsClasspath.

通过 命令行选项 方式: 

java -jar dokka-cli-1.9.20.jar \
     -pluginsClasspath "./dokka-base-1.9.20.jar;...;./gfm-plugin-1.9.20.jar" \
     ...

通过 JSON 配置 方式: 

{
  ...
  "pluginsClasspath": [
    "./dokka-base-1.9.20.jar",
    "...",
    "./gfm-plugin-1.9.20.jar"
  ],
  ...
}

更多详情, 请参见 CLI 运行器文档中的 其它输出格式.

源代码请参见 GitHub.

Jekyll

Jekyll 输出格式生成 Jekyll 兼容的 Markdown 格式文档.

Gradle plugin for Dokka 包含了 Jekyll 输出格式. 你可以通过以下 task 使用它:

Task 描述

dokkaJekyll

 为单个项目生成生成 Jekyll 文档.

dokkaJekyllMultiModule

只为多项目构建中的父项目创建的 MultiModule task. 它会为子项目生成文档, 并将所有的输出合并到单个位置, 使用共同的内容目录.

dokkaJekyllCollector

只为多项目构建中的父项目创建的 Collector task. 它会为每个子项目调用 dokkaJekyll, 并将所有的输出合并到一个单独的虚拟项目.

由于 Jekyll 格式是以 Dokka plugin 方式实现的, 因此你需要以 plugin 依赖项的方式使用它: 

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <dokkaPlugins>
            <plugin>
                <groupId>org.jetbrains.dokka</groupId>
                <artifactId>jekyll-plugin</artifactId>
                <version>1.9.20</version>
            </plugin>
        </dokkaPlugins>
    </configuration>
</plugin>

完成上面的配置之后, 请运行 dokka:dokka goal 来生成 GFM 格式文档.

更多详情, 请参见 Maven plugin 文档中的 其它输出格式.

由于 Jekyll 格式是以 Dokka plugin 方式实现的, 因此你需要 下载 JAR 文件. 这个格式也是基于 GFM 格式, 因此你还需要提供 GFM 格式的依赖项. 两个 JAR 文件都需要传递给 pluginsClasspath:

通过 命令行选项 方式: 

java -jar dokka-cli-1.9.20.jar \
     -pluginsClasspath "./dokka-base-1.9.20.jar;...;./gfm-plugin-1.9.20.jar;./jekyll-plugin-1.9.20.jar" \
     ...

通过 JSON 配置 方式: 

{
  ...
  "pluginsClasspath": [
    "./dokka-base-1.9.20.jar",
    "...",
    "./gfm-plugin-1.9.20.jar",
    "./jekyll-plugin-1.9.20.jar"
  ],
  ...
}

更多详情, 请参见 CLI 运行器文档中的 其它输出格式.

源代码请参见 GitHub.