How do I document a Kotlin package like with the Java `package-info.java` in an IntelliJ IDEA/Gradle project?

kotlinlang.org says that a separate markdown file documents all packages. Is there a canonical path for that markdown file in an IntelliJ IDEA project? Is there a canonical way to process that file with Gradle? Is there a way to have these .md files alongside .kt files in the package directory?

If you want to produce your documentations using Dokka, you can create a single markdown (.md) file with headers for each package (or probably separate markdown file in each package with a single header in that file for that package):

my-packages-docs.md:

# Package com.example.mylibrary.firstpackage

This is the docs for firstpackage.

# Package com.example.mylibrary.anotherpackage

This is the docs for anotherpackage.

## This is a subheader for anotherpackages docs

Include the markdown file in the Dokka result by passing the path of the file(s) to Dokka using the -include command line parameter or the proper parameters in Ant, Maven and Gradle plugins.

Here is an example configuration for Dokka in the library build.gradle.kts file (Kotlin DSL):

Dokka v2:

dokka {
    dokkaSourceSets.main {
        includes.from("my-packages-docs.md", "another.md")
    }
}

Dokka v1:

tasks.withType<DokkaTask>().configureEach { // OR tasks.dokkaHtml.configure {
    dokkaSourceSets {
        configureEach { // OR named("main") {
            includes.from("my-packages-docs.md", "another.md")
        }
    }
}

Refer to Dokka module and package documentation for more information.