Dokka生成Java文档时Markdown格式错乱问题求助

针对你遇到的换行丢失、列表格式破坏、@link链接失效问题，可通过以下步骤解决：

1. 升级Dokka Maven插件版本 #

旧版本Dokka对Java 11+环境及Markdown的支持存在缺陷，建议升级至最新稳定版。修改pom.xml中的插件版本：

<plugin>
  <groupId>org.jetbrains.dokka</groupId>
  <artifactId>dokka-maven-plugin</artifactId>
  <!-- 使用最新稳定版，例如1.9.20 -->
  <version>1.9.20</version>
  <!-- 其余配置保持不变 -->
</plugin>

2. 启用Markdown支持并配置解析规则 #

在Dokka的configuration节点中添加Markdown解析开关，同时启用Javadoc链接解析：

<configuration>
  <!-- 匹配当前运行的JDK版本，例如11 -->
  <jdkVersion>11</jdkVersion>
  <sourceDirectories>
    <dir>src/main/java</dir>
  </sourceDirectories>
  <!-- 开启Markdown语法解析 -->
  <markdownSupport>true</markdownSupport>
  <!-- 启用Javadoc @link标签的解析与转换 -->
  <javadocLinkResolution>true</javadocLinkResolution>
  <!-- 保留Javadoc中的原始换行格式 -->
  <preserveRawHtml>true</preserveRawHtml>
</configuration>

3. 调整Javadoc的Markdown写法（可选） #

确保Markdown格式符合Dokka的解析要求：

• 列表块前必须保留空白行
• 每个列表项的-符号需与上方文本保持一致缩进（和Javadoc的*对齐）

调整后的Javadoc示例：

/**
 * The `UNKNOWN` version instance.
 *
 * This is used when a certain library/app does not have
 * `.version` file defined.
 *
 * The `UNKNOWN` is constructed with:
 *
 * - empty string for {@link #getPackageName()}
 * - {@link #UNKNOWN_STR} for {@link #getArtifactId()} and {@link #getProjectVersion()}
 * - `null` for {@link #getBuildNumber()}
 */

4. 重新执行构建命令 #

清理后重新运行Dokka构建：

mvn clean install -P dokka

内容的提问来源于stack exchange，提问作者Gelin Luo