Support GFM code-block and code-inline markdown rendering

[marcelmay]

This PR enhances GFM markdown rendering for code block (wrapped by tripple backtick) and code inline (wrapped by single backtick) markdown. It also fixes missing lang attribute for code block.

[MarcinAman]

This almost works, but needs some work when displaying inside a table. Consider this example:

/**
 * a normal comment with `inline code` or with:
 *
 *
 * ```java
 * class XD {
 *      public static void xd(String a){ }
 * }
 * ```
 */
fun test(abc: String) {

}

When looking on the function's page it is rendered correctly, but when looking at index.md of this package, it is escaped. This actually is a major issue since (correct me if i am wrong) markdown doesn't support displaying multiline content inside a table.

The easiest (but also dirtiest) solution would be to render those tables as html but i am not sure if we want that. @kamildoleglo @sellophane ?

[marcelmay]

@MarcinAman , thx for pointing out the table issue.

Another workaround could be trying to distinguish if the code block is part of a function (and thus table-wrapped), and then render using <pre><code class="language-...>, like mentioned here?

Eg in GfmPlugin.kt:

override fun StringBuilder.buildCodeBlock(code: ContentCodeBlock, pageContext: ContentPage) {          
    if(code.dci.dri.first().callable != null) { // Detect if part of method listing                    
        append("""<pre><code class="language-${code.language}">""")                                    
        code.children.forEach { buildContentNode(it, pageContext) }                                    
        append("</code></pre>")                                                                        
    } else {                                                                                           
        append("```${code.language}\n")                                                                
        code.children.forEach { buildContentNode(it, pageContext) }                                    
        append("\n```")                                                                                
    }                                                                                                  
}  

[MarcinAman]

Tbh i'd opt for creating a gfm-specific preprocessor (look at GfmPlugin.kt, gfmPreprocessors extension point) that would add some sort of marker (can be in form of extra / style) to the code block that would indicate the need for rendering as html. That way we are not keeping logic inside a renderer. The condition on which this marker would be placed should be a simple question is this inside a table?. Then in the renderer you would build the code accordingly.

Also, please don't scrape DRI for information. They are intended as an identifier

[marcelmay]

@MarcinAman , thanks for the hint and I will look into this direction.

[msink]

About code blocks in table - they should never be displayed in tables - because table is a brief index, containing only name and summary description (defined in KDoc Syntax as "first paragraph of the documentation text (the block of text until the first blank line)"

Code block is part of detailed description, on separate page, available by link from the index table.

[MarcinAman]

About code blocks in table - they should never be displayed in tables - because table is a brief index, containing only name and summary description (defined in KDoc Syntax as "first paragraph of the documentation text (the block of text until the first blank line)"

Code block is part of detailed description, on separate page, available by link from the index table.

Yes and no. I agree that they are a part of a detailed description, but we can't block the ability to display code blocks as a part of a entries list simply because type aliases doesn't have separate pages in dokka and then adding a code block wouldn't be possible for them.

Also for the example i've provided before it would be nice to be able to see a code block, since the description before doesn't have a single, separated sentence that would fit in a brief comment

[msink]

type aliases doesn't have separate pages in dokka

Then it's a bug :)
Everything should have separate page, for GFM format at least.

About example above - it just does not conform to official KDoc Syntax definition.
How it will be handled in IDEA?

[MarcinAman]

I see your point but before now they were not needed so we didn't make them. Also i don't see a point making them for HTML (only for GFM and Jekyll). I've created an issue for that: #1667

Idea renders this example normally, as expected with full content.