Cleanup paragraphs and tables in GFM renderer (#1946)

* GFM renderer: cleanup paragraphs

* GFM renderer: cleanup tables

* GFM renderer: add tests for wrong header in table

Table with extra cell in row is really generated by `all-modules-page` plugin

* Remove commented-out lines

* Add BriefCommentPreprocessor which inserts a line break between a signature and a brief comment

Fixed a bug with `mapTransform` function which replaces table headers with their contents

Co-authored-by: Kamil Doległo <kamil.doleglo@interia.pl>

10 files changed, 341 insertions, 93 deletions

diff --git a/plugins/gfm/api/gfm.api b/plugins/gfm/api/gfm.api
index bc43ba05..fc388825 100644
--- a/plugins/gfm/api/gfm.api
+++ b/plugins/gfm/api/gfm.api
@@ -11,6 +11,7 @@ public final class org/jetbrains/dokka/gfm/GfmCommand$Companion {
 
 public final class org/jetbrains/dokka/gfm/GfmPlugin : org/jetbrains/dokka/plugability/DokkaPlugin {
 	public fun <init> ()V
+	public final fun getBriefCommentPreprocessor ()Lorg/jetbrains/dokka/plugability/Extension;
 	public final fun getGfmPreprocessors ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
 	public final fun getLocationProvider ()Lorg/jetbrains/dokka/plugability/Extension;
 	public final fun getPackageListCreator ()Lorg/jetbrains/dokka/plugability/Extension;
@@ -33,6 +34,11 @@ public final class org/jetbrains/dokka/gfm/location/MarkdownLocationProvider$Fac
 	public fun getLocationProvider (Lorg/jetbrains/dokka/pages/RootPageNode;)Lorg/jetbrains/dokka/gfm/location/MarkdownLocationProvider;
 }
 
+public final class org/jetbrains/dokka/gfm/renderer/BriefCommentPreprocessor : org/jetbrains/dokka/transformers/pages/PageTransformer {
+	public fun <init> ()V
+	public fun invoke (Lorg/jetbrains/dokka/pages/RootPageNode;)Lorg/jetbrains/dokka/pages/RootPageNode;
+}
+
 public class org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer : org/jetbrains/dokka/base/renderers/DefaultRenderer {
 	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
 	public synthetic fun buildDRILink (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentDRILink;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V
diff --git a/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/GfmPlugin.kt b/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/GfmPlugin.kt
index 4ca639b2..78597d44 100644
--- a/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/GfmPlugin.kt
+++ b/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/GfmPlugin.kt
@@ -6,6 +6,7 @@ import org.jetbrains.dokka.base.renderers.PackageListCreator
 import org.jetbrains.dokka.base.renderers.RootCreator
 import org.jetbrains.dokka.base.resolvers.shared.RecognizedLinkFormat
 import org.jetbrains.dokka.gfm.location.MarkdownLocationProvider
+import org.jetbrains.dokka.gfm.renderer.BriefCommentPreprocessor
 import org.jetbrains.dokka.gfm.renderer.CommonmarkRenderer
 import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.transformers.pages.PageTransformer
@@ -28,6 +29,10 @@ class GfmPlugin : DokkaPlugin() {
         gfmPreprocessors with RootCreator
     }
 
+    val briefCommentPreprocessor by extending {
+        gfmPreprocessors with BriefCommentPreprocessor()
+    }
+
     val packageListCreator by extending {
         (gfmPreprocessors
                 providing { PackageListCreator(it, RecognizedLinkFormat.DokkaGFM) }
diff --git a/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/BriefCommentPreprocessor.kt b/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/BriefCommentPreprocessor.kt
new file mode 100644
index 00000000..fd65e2f9
--- /dev/null
+++ b/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/BriefCommentPreprocessor.kt
@@ -0,0 +1,16 @@
+package org.jetbrains.dokka.gfm.renderer
+
+import org.jetbrains.dokka.pages.*
+import org.jetbrains.dokka.transformers.pages.PageTransformer
+
+class BriefCommentPreprocessor : PageTransformer {
+    override fun invoke(input: RootPageNode) = input.transformContentPagesTree { contentPage ->
+        contentPage.modified(content = contentPage.content.recursiveMapTransform<ContentGroup, ContentNode> {
+            if (it.dci.kind == ContentKind.BriefComment) {
+                it.copy(style = it.style + setOf(TextStyle.Block))
+            } else {
+                it
+            }
+        })
+    }
+}
diff --git a/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt b/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt
index 676b0606..f18c7093 100644
--- a/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt
+++ b/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt
@@ -26,11 +26,7 @@ open class CommonmarkRenderer(
         childrenCallback: StringBuilder.() -> Unit
     ) {
         return when {
-            node.hasStyle(TextStyle.Block) -> {
-                childrenCallback()
-                buildParagraph()
-            }
-            node.hasStyle(TextStyle.Paragraph) -> {
+            node.hasStyle(TextStyle.Block) || node.hasStyle(TextStyle.Paragraph) -> {
                 buildParagraph()
                 childrenCallback()
                 buildParagraph()
@@ -43,7 +39,7 @@ open class CommonmarkRenderer(
         buildParagraph()
         append("#".repeat(level) + " ")
         content()
-        appendNewLine()
+        buildParagraph()
     }
 
     override fun StringBuilder.buildLink(address: String, content: StringBuilder.() -> Unit) {
@@ -57,7 +53,9 @@ open class CommonmarkRenderer(
         pageContext: ContentPage,
         sourceSetRestriction: Set<DisplaySourceSet>?
     ) {
+        buildParagraph()
         buildListLevel(node, pageContext)
+        buildParagraph()
     }
 
     private fun StringBuilder.buildListItem(items: List<ContentNode>, pageContext: ContentPage) {
@@ -135,10 +133,11 @@ open class CommonmarkRenderer(
             }.groupBy(Pair<DisplaySourceSet, String>::second, Pair<DisplaySourceSet, String>::first)
 
             distinct.filter { it.key.isNotBlank() }.forEach { (text, platforms) ->
-                append(" ")
+                buildParagraph()
                 buildSourceSetTags(platforms.toSet())
-                append(" $text")
-                appendNewLine()
+                buildNewLine()
+                append(text.trim())
+                buildParagraph()
             }
         }
     }
@@ -170,46 +169,40 @@ open class CommonmarkRenderer(
             }
         } else {
             val size = node.header.firstOrNull()?.children?.size ?: node.children.firstOrNull()?.children?.size ?: 0
+            if (size <= 0) return
 
             if (node.header.isNotEmpty()) {
                 node.header.forEach {
-                    append("| ")
                     it.children.forEach {
-                        append(" ")
+                        append("| ")
                         it.build(this, pageContext, it.sourceSets)
-                        append(" | ")
+                        append(" ")
                     }
-                    append("\n")
                 }
             } else {
                 append("| ".repeat(size))
-                if (size > 0) {
-                    append("|")
-                    appendNewLine()
-                }
             }
+            append("|")
+            appendNewLine()
 
             append("|---".repeat(size))
-            if (size > 0) {
-                append("|")
-                appendNewLine()
-            }
+            append("|")
+            appendNewLine()
 
-            node.children.forEach {
-                val builder = StringBuilder()
-                it.children.forEach {
-                    builder.append("| ")
-                    builder.append("<a name=\"${it.dci.dri.first()}\"></a>")
-                    builder.append(
-                        buildString { it.build(this, pageContext) }.replace(
-                            Regex("#+ "),
-                            ""
-                        )
-                    )  // Workaround for headers inside tables
+            node.children.forEach { row ->
+                row.children.forEach { cell ->
+                    append("| ")
+                    append(buildString { cell.build(this, pageContext) }
+                        .trim()
+                        .replace("#+ ".toRegex(), "") // Workaround for headers inside tables
+                        .replace("\\\n", "\n\n")
+                        .replace("\n[\n]+".toRegex(), "<br>")
+                        .replace("\n", " ")
+                    )
+                    append(" ")
                 }
-                append(builder.toString().withEntersAsHtml())
-                append("|".repeat(size + 1 - it.children.size))
-                append("\n")
+                append("|")
+                appendNewLine()
             }
         }
     }
@@ -259,25 +252,22 @@ open class CommonmarkRenderer(
         distinct.values.forEach { entry ->
             val (instance, sourceSets) = entry.getInstanceAndSourceSets()
 
+            buildParagraph()
             buildSourceSetTags(sourceSets)
+            buildNewLine()
 
             instance.before?.let {
-                buildNewLine()
-                append("Brief description")
-                buildNewLine()
                 buildContentNode(
                     it,
                     pageContext,
                     sourceSets.first()
                 ) // It's workaround to render content only once
+                buildParagraph()
             }
 
-            buildNewLine()
-            append("Content")
             entry.groupBy { buildString { buildContentNode(it.first.divergent, pageContext, setOf(it.second)) } }
                 .values.forEach { innerEntry ->
                     val (innerInstance, innerSourceSets) = innerEntry.getInstanceAndSourceSets()
-                    buildNewLine()
                     if (sourceSets.size > 1) {
                         buildSourceSetTags(innerSourceSets)
                         buildNewLine()
@@ -287,12 +277,10 @@ open class CommonmarkRenderer(
                         pageContext,
                         setOf(innerSourceSets.first())
                     ) // It's workaround to render content only once
+                    buildParagraph()
                 }
 
             instance.after?.let {
-                buildNewLine()
-                append("More info")
-                buildNewLine()
                 buildContentNode(
                     it,
                     pageContext,
@@ -358,11 +346,6 @@ open class CommonmarkRenderer(
         }
     }
 
-    private fun String.withEntersAsHtml(): String = this
-        .replace("\\\n", "\n\n")
-        .replace("\n[\n]+".toRegex(), "<br>")
-        .replace("\n", " ")
-
     private fun List<Pair<ContentDivergentInstance, DisplaySourceSet>>.getInstanceAndSourceSets() =
         this.let { Pair(it.first().first, it.map { it.second }.toSet()) }
 
diff --git a/plugins/gfm/src/test/kotlin/renderers/gfm/DivergentTest.kt b/plugins/gfm/src/test/kotlin/renderers/gfm/DivergentTest.kt
index d9ae5e99..ae1b4d7f 100644
--- a/plugins/gfm/src/test/kotlin/renderers/gfm/DivergentTest.kt
+++ b/plugins/gfm/src/test/kotlin/renderers/gfm/DivergentTest.kt
@@ -41,7 +41,11 @@ class DivergentTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-        val expect = "//[testPage](test-page.md)\n\n[js]\\\nContent\\\na"
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[js]\
+                        |a""".trimMargin()
+
         CommonmarkRenderer(context).render(page)
         assert(renderedContent == expect)
     }
@@ -57,7 +61,11 @@ class DivergentTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-        val expect = "//[testPage](test-page.md)\n\n[js]\\\nContent\\\na"
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[js]\
+                        |a""".trimMargin()
+
         CommonmarkRenderer(context).render(page)
         assert(renderedContent == expect)
     }
@@ -83,7 +91,18 @@ class DivergentTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-        val expect = "//[testPage](test-page.md)\n\n[js, jvm, native]\\\nContent\\\n[js]\\\na\\\n[jvm]\\\nb\\\n[native]\\\nc"
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[js, jvm, native]\
+                        |[js]\
+                        |a
+                        |
+                        |[jvm]\
+                        |b
+                        |
+                        |[native]\
+                        |c""".trimMargin()
+
         CommonmarkRenderer(context).render(page)
         assert(renderedContent == expect)
     }
@@ -109,7 +128,15 @@ class DivergentTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-        val expect = "//[testPage](test-page.md)\n\n[js]\\\nContent\\\na\\\nb\\\nc"
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[js]\
+                        |a
+                        |
+                        |b
+                        |
+                        |c""".trimMargin()
+
         CommonmarkRenderer(context).render(page)
         assert(renderedContent == expect)
     }
@@ -145,7 +172,24 @@ class DivergentTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-        val expect = "//[testPage](test-page.md)\n\n[native, js, jvm]\\\nContent\\\n[native]\\\na\\\n[js]\\\nb\\\n[jvm]\\\nc\\\n[js]\\\nd\\\n[native]\\\ne"
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[native, js, jvm]\
+                        |[native]\
+                        |a
+                        |
+                        |[js]\
+                        |b
+                        |
+                        |[jvm]\
+                        |c
+                        |
+                        |[js]\
+                        |d
+                        |
+                        |[native]\
+                        |e""".trimMargin()
+
         CommonmarkRenderer(context).render(page)
         assert(renderedContent == expect)
     }
@@ -193,7 +237,28 @@ class DivergentTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-        val expect = "//[testPage](test-page.md)\n\n[native]\\\nContent\\\na\\\nMore info\\\na+\n\n[js]\\\nContent\\\nb\\\nd\\\nMore info\\\nbd+\n\n[jvm]\\\nContent\\\nc\n\n[native]\\\nContent\\\ne\\\nMore info\\\ne+"
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[native]\
+                        |a
+                        |
+                        |a+
+                        |
+                        |[js]\
+                        |b
+                        |
+                        |d
+                        |
+                        |bd+
+                        |
+                        |[jvm]\
+                        |c
+                        |
+                        |[native]\
+                        |e
+                        |
+                        |e+""".trimMargin()
+
         CommonmarkRenderer(context).render(page)
         assert(renderedContent == expect)
     }
@@ -220,7 +285,15 @@ class DivergentTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-        val expect = "//[testPage](test-page.md)\n\n[native]\\\nBrief description\\\nab-\\\nContent\\\na\\\nb"
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[native]\
+                        |ab-
+                        |
+                        |a
+                        |
+                        |b""".trimMargin()
+
         CommonmarkRenderer(context).render(page)
         assert(renderedContent == expect)
     }
@@ -247,7 +320,15 @@ class DivergentTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-        val expect = "//[testPage](test-page.md)\n\n[native]\\\nContent\\\na\\\nb\\\nMore info\\\nab+"
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[native]\
+                        |a
+                        |
+                        |b
+                        |
+                        |ab+""".trimMargin()
+
         CommonmarkRenderer(context).render(page)
         assert(renderedContent == expect)
     }
@@ -280,7 +361,17 @@ class DivergentTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-        val expect = "//[testPage](test-page.md)\n\n[native]\\\nBrief description\\\nab-\\\nContent\\\na\\\nb\\\nMore info\\\nab+"
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[native]\
+                        |ab-
+                        |
+                        |a
+                        |
+                        |b
+                        |
+                        |ab+""".trimMargin()
+
         CommonmarkRenderer(context).render(page)
         assert(renderedContent == expect)
     }
@@ -313,7 +404,22 @@ class DivergentTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-        val expect = "//[testPage](test-page.md)\n\n[native]\\\nBrief description\\\na-\\\nContent\\\na\\\nMore info\\\nab+\n\n[native]\\\nBrief description\\\nb-\\\nContent\\\nb\\\nMore info\\\nab+"
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[native]\
+                        |a-
+                        |
+                        |a
+                        |
+                        |ab+
+                        |
+                        |[native]\
+                        |b-
+                        |
+                        |b
+                        |
+                        |ab+""".trimMargin()
+
         CommonmarkRenderer(context).render(page)
         assert(renderedContent == expect)
     }
@@ -364,7 +470,30 @@ class DivergentTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-        val expect = "//[testPage](test-page.md)\n\n[native]\\\nContent\\\na\\\nMore info\\\na+\n\n[js, jvm]\\\nContent\\\n[js]\\\nb\\\n[jvm]\\\nc\\\n[js]\\\nd\\\nMore info\\\nbd+\n\n[native]\\\nContent\\\ne\\\nMore info\\\ne+"
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[native]\
+                        |a
+                        |
+                        |a+
+                        |
+                        |[js, jvm]\
+                        |[js]\
+                        |b
+                        |
+                        |[jvm]\
+                        |c
+                        |
+                        |[js]\
+                        |d
+                        |
+                        |bd+
+                        |
+                        |[native]\
+                        |e
+                        |
+                        |e+""".trimMargin()
+
         CommonmarkRenderer(context).render(page)
         assert(renderedContent == expect)
     }
diff --git a/plugins/gfm/src/test/kotlin/renderers/gfm/GroupWrappingTest.kt b/plugins/gfm/src/test/kotlin/renderers/gfm/GroupWrappingTest.kt
index 11105ebd..eafe3e13 100644
--- a/plugins/gfm/src/test/kotlin/renderers/gfm/GroupWrappingTest.kt
+++ b/plugins/gfm/src/test/kotlin/renderers/gfm/GroupWrappingTest.kt
@@ -16,10 +16,12 @@ class GroupWrappingTest : GfmRenderingOnlyTestBase() {
             }
             text("c")
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |abc""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
-
-        assert(renderedContent == "//[testPage](test-page.md)\n\nabc")
+        assert(renderedContent == expect)
     }
 
     @Test
@@ -31,10 +33,14 @@ class GroupWrappingTest : GfmRenderingOnlyTestBase() {
             }
             text("c")
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |ab
+                        |
+                        |c""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
-
-        assert(renderedContent == "//[testPage](test-page.md)\n\nab\n\nc")
+        assert(renderedContent == expect)
     }
 
     @Test
@@ -46,9 +52,14 @@ class GroupWrappingTest : GfmRenderingOnlyTestBase() {
             }
             text("c")
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |ab
+                        |
+                        |c""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
-        assert(renderedContent == "//[testPage](test-page.md)\n\nab\n\nc")
+        assert(renderedContent == expect)
     }
 
     @Test
@@ -65,11 +76,15 @@ class GroupWrappingTest : GfmRenderingOnlyTestBase() {
                 text("d")
             }
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |a
+                        |
+                        |bc
+                        |
+                        |d""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
-
-//        renderedContent.match(Div("a", Div(Div("bc")), "d"))
-        assert(renderedContent == "//[testPage](test-page.md)\n\nabc\n\nd")
+        assert(renderedContent == expect)
     }
-
 }
diff --git a/plugins/gfm/src/test/kotlin/renderers/gfm/SimpleElementsTest.kt b/plugins/gfm/src/test/kotlin/renderers/gfm/SimpleElementsTest.kt
index 1a28a9a8..ee156c7f 100644
--- a/plugins/gfm/src/test/kotlin/renderers/gfm/SimpleElementsTest.kt
+++ b/plugins/gfm/src/test/kotlin/renderers/gfm/SimpleElementsTest.kt
@@ -120,13 +120,12 @@ class SimpleElementsTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
-
-        val expect = """\//[testPage](test-page.md)
-            \
-            \|  Col1 |  Col2 |  Col3 | 
-            \|---|---|---|
-            \| <a name="////PointingToDeclaration/"></a>Text1| <a name="////PointingToDeclaration/"></a>Text2| <a name="////PointingToDeclaration/"></a>Text3|
-            \| <a name="////PointingToDeclaration/"></a>Text4| <a name="////PointingToDeclaration/"></a>Text5| <a name="////PointingToDeclaration/"></a>Text6|""".trimMargin("\\")
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        || Col1 | Col2 | Col3 |
+                        ||---|---|---|
+                        || Text1 | Text2 | Text3 |
+                        || Text4 | Text5 | Text6 |""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
         assertEquals(expect, renderedContent)
@@ -148,15 +147,61 @@ class SimpleElementsTest : GfmRenderingOnlyTestBase() {
                 }
             }
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        || | | |
+                        ||---|---|---|
+                        || Text1 | Text2 | Text3 |
+                        || Text4 | Text5 | Text6 |""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
 
-        val expect = """\//[testPage](test-page.md)
-            \
-            \| | | |
-            \|---|---|---|
-            \| <a name="////PointingToDeclaration/"></a>Text1| <a name="////PointingToDeclaration/"></a>Text2| <a name="////PointingToDeclaration/"></a>Text3|
-            \| <a name="////PointingToDeclaration/"></a>Text4| <a name="////PointingToDeclaration/"></a>Text5| <a name="////PointingToDeclaration/"></a>Text6|""".trimMargin("\\")
+    @Test
+    fun `table with extra cell in row`() {
+        val page = testPage {
+            table {
+                header {
+                    text("Col1")
+                }
+                row {
+                    text("Text1")
+                    text("Text2")
+                }
+            }
+        }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        || Col1 |
+                        ||---|
+                        || Text1 | Text2 |""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
         assertEquals(expect, renderedContent)
     }
+
+    @Test
+    fun `table with extra cell in header`() {
+        val page = testPage {
+            table {
+                header {
+                    text("Col1")
+                    text("Col2")
+                }
+                row {
+                    text("Text1")
+                }
+            }
+        }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        || Col1 | Col2 |
+                        ||---|---|
+                        || Text1 |""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
+
 }
diff --git a/plugins/gfm/src/test/kotlin/renderers/gfm/SourceSetDependentHintTest.kt b/plugins/gfm/src/test/kotlin/renderers/gfm/SourceSetDependentHintTest.kt
index 254832de..dae9983a 100644
--- a/plugins/gfm/src/test/kotlin/renderers/gfm/SourceSetDependentHintTest.kt
+++ b/plugins/gfm/src/test/kotlin/renderers/gfm/SourceSetDependentHintTest.kt
@@ -39,9 +39,13 @@ class SourceSetDependentHintTest : GfmRenderingOnlyTestBase() {
                 text("c")
             }
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[pl1, pl2, pl3]\
+                        |abc""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
-        assert(renderedContent == "//[testPage](test-page.md)\n\n [pl1, pl2, pl3] abc")
+        assert(renderedContent == expect)
     }
 
     @Test
@@ -53,9 +57,19 @@ class SourceSetDependentHintTest : GfmRenderingOnlyTestBase() {
                 text("c", sourceSets = setOf(pl3))
             }
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[pl1]\
+                        |a
+                        |
+                        |[pl2]\
+                        |b
+                        |
+                        |[pl3]\
+                        |c""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
-        assert(renderedContent == "//[testPage](test-page.md)\n\n [pl1] a\n\n [pl2] b\n\n [pl3] c")
+        assert(renderedContent == expect)
     }
 
     @Test
@@ -67,9 +81,16 @@ class SourceSetDependentHintTest : GfmRenderingOnlyTestBase() {
                 text("c", sourceSets = setOf(pl2))
             }
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[pl1]\
+                        |ab
+                        |
+                        |[pl2]\
+                        |bc""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
-        assert(renderedContent == "//[testPage](test-page.md)\n\n [pl1] ab\n\n [pl2] bc")
+        assert(renderedContent == expect)
     }
 
     @Test
@@ -81,9 +102,13 @@ class SourceSetDependentHintTest : GfmRenderingOnlyTestBase() {
                 text("b", sourceSets = setOf(pl2))
             }
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[pl1, pl2]\
+                        |ab""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
-        assert(renderedContent == "//[testPage](test-page.md)\n\n [pl1, pl2] ab")
+        assert(renderedContent == expect)
     }
 
     @Test
@@ -97,9 +122,18 @@ class SourceSetDependentHintTest : GfmRenderingOnlyTestBase() {
                 text("b", sourceSets = setOf(pl2))
             }
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[pl1]\
+                        |ab
+                        |
+                        |[pl2]\
+                        |a
+                        |
+                        |b""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
-        assert(renderedContent == "//[testPage](test-page.md)\n\n [pl1] ab\n\n [pl2] a\n\nb")
+        assert(renderedContent == expect)
     }
 
     @Test
@@ -113,9 +147,13 @@ class SourceSetDependentHintTest : GfmRenderingOnlyTestBase() {
                 text("b", sourceSets = setOf(pl2))
             }
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[pl1, pl2]\
+                        |ab""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
-        assert(renderedContent == "//[testPage](test-page.md)\n\n [pl1, pl2] ab")
+        assert(renderedContent == expect)
     }
 
     @Test
@@ -127,8 +165,15 @@ class SourceSetDependentHintTest : GfmRenderingOnlyTestBase() {
                 text("b", sourceSets = setOf(pl3))
             }
         }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |[pl1, pl2]\
+                        |a
+                        |
+                        |[pl3]\
+                        |b""".trimMargin()
 
         CommonmarkRenderer(context).render(page)
-        assert(renderedContent == "//[testPage](test-page.md)\n\n [pl1, pl2] a\n\n [pl3] b")
+        assert(renderedContent == expect)
     }
 }
diff --git a/plugins/jekyll/api/jekyll.api b/plugins/jekyll/api/jekyll.api
index d36b70c2..28d01241 100644
--- a/plugins/jekyll/api/jekyll.api
+++ b/plugins/jekyll/api/jekyll.api
@@ -1,5 +1,6 @@
 public final class org/jetbrains/dokka/jekyll/JekyllPlugin : org/jetbrains/dokka/plugability/DokkaPlugin {
 	public fun <init> ()V
+	public final fun getBriefCommentPreprocessor ()Lorg/jetbrains/dokka/plugability/Extension;
 	public final fun getJekyllPreprocessors ()Lorg/jetbrains/dokka/plugability/ExtensionPoint;
 	public final fun getPackageListCreator ()Lorg/jetbrains/dokka/plugability/Extension;
 	public final fun getRenderer ()Lorg/jetbrains/dokka/plugability/Extension;
diff --git a/plugins/jekyll/src/main/kotlin/JekyllPlugin.kt b/plugins/jekyll/src/main/kotlin/JekyllPlugin.kt
index bcc73862..675dfb39 100644
--- a/plugins/jekyll/src/main/kotlin/JekyllPlugin.kt
+++ b/plugins/jekyll/src/main/kotlin/JekyllPlugin.kt
@@ -4,16 +4,15 @@ import org.jetbrains.dokka.CoreExtensions
 import org.jetbrains.dokka.base.renderers.PackageListCreator
 import org.jetbrains.dokka.base.renderers.RootCreator
 import org.jetbrains.dokka.base.resolvers.shared.RecognizedLinkFormat
-import org.jetbrains.dokka.gfm.renderer.CommonmarkRenderer
 import org.jetbrains.dokka.gfm.GfmPlugin
-import org.jetbrains.dokka.pages.*
+import org.jetbrains.dokka.gfm.renderer.BriefCommentPreprocessor
+import org.jetbrains.dokka.gfm.renderer.CommonmarkRenderer
+import org.jetbrains.dokka.pages.ContentPage
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.plugability.plugin
 import org.jetbrains.dokka.plugability.query
 import org.jetbrains.dokka.transformers.pages.PageTransformer
-import java.lang.StringBuilder
-
 
 class JekyllPlugin : DokkaPlugin() {
 
@@ -29,6 +28,10 @@ class JekyllPlugin : DokkaPlugin() {
         jekyllPreprocessors with RootCreator
     }
 
+    val briefCommentPreprocessor by extending {
+        jekyllPreprocessors with BriefCommentPreprocessor()
+    }
+
     val packageListCreator by extending {
         jekyllPreprocessors providing {
             PackageListCreator(it, RecognizedLinkFormat.DokkaJekyll)