Samples are not placed in code fences for GFM

[bherbst]

trafficstars

Describe the bug Code samples are not placed in code fences with the GFM format, which makes the output very difficult to read since the code will not have syntax highlighting, nor will it be placed in a code block.

Given this documented function:

/**
 * Print a greeting to the standard output
 * 
 * @sample samples.basicSample
 */
fun greet(name: String) {
  println("Hello $name!")
}

And this sample file:

package samples

// This function will print "Hello Everyone!"
fun basicSample() {
  greet("Everyone")
}

./gradlew dokkaGfm will generate an index.md containing this:

## Samples  
 [jvm]
fun basicSample() {
   //sampleStart 
   greet("Everyone") 
   //sampleEnd
}   

Expected behaviour

I'd expect markdown that looks something closer to this:

## Samples  
[jvm]
```kotlin
fun basicSample() {
   //sampleStart 
   greet("Everyone") 
   //sampleEnd
}
```

Screenshots This is an example of how the current markdown will be rendered:

Here's what I'd expect to see:

Ideally the "//sampleStart" and "//sampleEnd" would also be gone, but that's perhaps a different issue.

To Reproduce See above for a basic example.

Here is a fork of the Dokka Gradle example from Kotlin's examples repo with a sample set up as well: dokka-gradle-example.zip

Dokka configuration Configuration of dokka used to reproduce the bug

tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets {
        named("main") {
            // ...
            samples.from("samples/Sample.kt")
        }
    }
}

Installation

• Operating system: macOS
• Build tool: Gradle v6.5.1
• Dokka version: 1.4.0

[DanielRibeiroMaciel-TomTom]

We would also like to see that fixed. Code blocks now get pasted without indentation and without formatting. Even if using code fences in kdoc:

/**
 *```json
 *  (write some json here)
 *```
 */

The triple quotes markup disappears when converted to gfm, it is not present on the md file.

[ghost]

Until this is fixed, we're using awk to clean these up. https://gist.github.com/carr-disco/e58b17a75fd102de44cc7312ca4d58db

[nomisRev]

This seems to be broken not just for GFM but also for Jekyll. Is there any news on this? This is blocking Arrow from migrating away from 0.10.x.

[sayan-chaliha]

This is definitely a blocker for hosting GFM documentation wikis. Even included *.md files are processed and code-blocks are removed from them.

[IgnatBeresnev]

Hi, can someone please check it on Dokka 1.7.0? I believe it should be fixed, at least to some degree. Implemented in https://github.com/Kotlin/dokka/pull/2485

For

/**
 * Print a greeting to the standard output
 *
 * @sample samples.basicSample
 */
fun greet(name: String) {
    println("Hello $name!")
}

Dokka generates the following:

[sayan-chaliha]

Just checked it on 1.7.0 -- definitely better! Thanks!!

[IgnatBeresnev]

I'll close the issue as implemented/fixed, but do let us know if you encounter any other problems related to that.