Dokka: add support for markdown images

[Groostav]

I went through the trouble of making a diagram for a state machine used on our application, but was disappointed to learn when I hit ctrl + alt + k in intelliJ that <img.../> tags aren't converted with standard markdown ![hover text](https://img-src).

can I ask for support for markdown image links in documentation? if the links were local-only that would suffice to, but embedding web images would be nice.

[BoxResin]

I hope this feature to be added to dokka soon!

[jdrider]

My workaround is to have a folder for images at the root level of the project and define a custom task that copies those images into the generated directory. These images can then be referenced in the documentation files using a relative path. This is similar to the doc-files directory used by Javadoc.

/**
 * Task that copies all .png files from the documentation folder to the build/javadoc/doc-files
 * folder so that they can be referenced in the generated documentation.
 */
task copyDocumentationImages(type: Copy){
    from ('documentation/images'){
        include '*.png'
    }
    into "$buildDir/javadoc/doc-files"
}

/**
 * Task that will generate Dokka documentation and copy the images to the build
 * folder to be referenced.  This is a workaround since Dokka does not currently support
 * embedding images.
 */
task generateDocumentation(){
    dependsOn 'dokka'
    dependsOn 'copyDocumentationImages'
}

Images can then be referenced in the markdown files. The path is short for html format docs, but several more levels (../) are required when javadoc format is used.

[App Diagram](../doc-files/App_Diagram.png "App Diagram")

[clarfonthey]

Wanted to add that I am also missing this feature. It would be nice if we could specify files to be included with the Dokka output as well, with linked images and other things automatically included.

[BoD]

I, too, just spent an hour making a very nice diagram only to realize I cannot embed it in my code documentation 😢 I am very sad now.

[zathras]

+1 on the above. I can't live without embedding diagrams in my generated documentation. It seems that dokka won't let me embed an <img>, either, so I had to resort to post-processing, viz:

tasks {
    compileKotlin {
        kotlinOptions.jvmTarget = "1.8"
    }
    compileTestKotlin {
        kotlinOptions.jvmTarget = "1.8"
    }

    val copyDocImages by registering(Copy::class) {
        from("../docsrc")
        include("*.svg")
        into("$buildDir/dokka/lib")
    }

    val dokka by getting(DokkaTask::class) {
        dependsOn(copyDocImages)
        outputFormat = "html"
        outputDirectory = "$buildDir/dokka"
        configuration {
            includes = listOf(
                "../docsrc/module.md", 
                "../docsrc/com.jovial.db9010/package.md"
            )
        }
        doLast {
            PostProcessHack.process(File("$buildDir/dokka/lib"))
        }
    }
}

object PostProcessHack {
    val imageRegex = Regex("""\${'$'}IMAGE[ \t]*\(([^)]*)\)""")
        // Yow.  That matches "$IMAGE (foo.svg)", with MatchResult's
        // groupValues[1] containing "foo.svg".  You're welcome.

    fun process(dir: File) {
        for (f : File in dir.listFiles()) {
            if (f.isDirectory) {
                process(f)
            } else if (f.name.endsWith(".html")) {
                var modified = false
                val text = f.readText()
                val result = imageRegex.replace(text) { mr ->
                    modified = true
                    """<img src="${mr.groupValues[1]}">"""
                }
                if (modified) f.writeText(result)
            }
        }
    }
}

It works and all, but I am saddened that it's so difficult to produce good-looking, complete documentation. This encourages more people to commit _Crimes Against Software™_.

[kamildoleglo]

We can't fix this in IntelliJ, as they don't use dokka internally, you can file an issue on YouTrack for that. We can probably do something about this in dokka