Merge pull request #10752 from pikinier20/markdown-html-tags

Add support for html tags inside documentation written in markdown

Author: romanowski

scala3doc-testcases/src/tests/htmlTests.scala

@@ -0,0 +1,29 @@
+package tests
+package htmlTests
+
+
+/**<table>
+ * <tr>
+ * <th> ASD </th>
+ * <th> FGH </th>
+ * <th> JKL </th>
+ * </tr>
+ * <tr>
+ * <td> 123 </td>
+ * <td> 456 </td>
+ * <td> 789 </td>
+ * </tr>
+ * </table>
+  * This is <span style="color:red;">red</span> text.
+  * <b> I'm bold </b>
+  * <i> And I'm italic </i>
+  *
+  * An example documention with markdown formatting
+  *
+  *
+  * <pre><code>
+  * def someScalaCode(x: String) = println("Hello " + x)
+  * </code></pre>
+  *
+*/
+class HtmlTest

scala3doc/src/dotty/dokka/tasty/comments/MarkdownConverter.scala

@@ -161,8 +161,17 @@ class MarkdownConverter(val repr: Repr) extends BaseConverter {
 
     case _: mda.SoftLineBreak => emit(dkkd.Br.INSTANCE)
 
+    case inline: mda.HtmlInline =>
+      emit(dkkd.Html(List(dkk.text(inline.getSegments.mkString)).asJava, kt.emptyMap))
+
+    case entity: mda.HtmlEntity =>
+      emit(dkkd.Html(List(dkk.text(entity.getSegments.mkString)).asJava, kt.emptyMap))
+
+    case block: mda.HtmlBlock =>
+      emit(dkkd.Html(List(dkk.text(block.getContentChars.toString)).asJava, kt.emptyMap))
+
     // TODO (https://github.com/lampepfl/scala3doc/issues/205): for now just silent the warnigs
-    case _:mda.HtmlInline | _: mda.LinkRef | _: mda.HtmlEntity | _: mda.HtmlBlock | _: com.vladsch.flexmark.ext.emoji.Emoji =>
+    case _: mda.LinkRef | _: com.vladsch.flexmark.ext.emoji.Emoji =>
       emit(dkk.text(MarkdownParser.renderToText(n)))
 
     case _ =>

scala3doc/src/dotty/dokka/tasty/comments/MarkdownParser.scala

@@ -1,6 +1,7 @@
 package dotty.dokka.tasty.comments
 
 import java.util.{ Arrays }
+import Regexes._
 
 import com.vladsch.flexmark.util.{ast => mdu}
 import com.vladsch.flexmark.formatter.Formatter
@@ -36,11 +37,13 @@ object MarkdownParser {
         "https://github.global.ssl.fastly.net/images/icons/emoji/")
       .set(WikiLinkExtension.LINK_ESCAPE_CHARS, "")
 
+  val parser = Parser.builder(markdownOptions).build()
+
   val RENDERER = Formatter.builder(markdownOptions).build()
 
   def parseToMarkdown(text: String): mdu.Document =
-    Parser.builder(markdownOptions)
-      .build.parse(text).asInstanceOf[mdu.Document]
+    // We need to remove safe tag markers as they break flexmark parsing
+    parser.parse(text.replace(safeTagMarker.toString, "")).asInstanceOf[mdu.Document]
 
 
   def renderToText(node: mdu.Node): String =

scala3doc/src/dotty/renderers/ScalaHtmlRenderer.scala

@@ -99,7 +99,8 @@ class ScalaHtmlRenderer(using ctx: DokkaContext) extends HtmlRenderer(ctx) {
 
   override def buildContentNode(f: FlowContent, node: ContentNode, pageContext: ContentPage, sourceSetRestriciton: JSet[DisplaySourceSet]) = {
     node match {
-      case n: HtmlContentNode => withHtml(f, raw(n.body).toString)
+      case n: HtmlContentNode =>
+        withHtml(f, raw(n.body).toString)
       case n: HierarchyGraphContentNode => buildDiagram(f, n.diagram, pageContext)
       case n: DocumentableList =>
         val ss = if sourceSetRestriciton == null then Set.empty.asJava else sourceSetRestriciton