fix: don't escape markdown within doc preformat blocks (#643)

Author: lucix-aws

.changes/88581b9f-34b0-4509-8eaf-481efd2cbdf1.json

@@ -0,0 +1,5 @@
+{
+    "id": "88581b9f-34b0-4509-8eaf-481efd2cbdf1",
+    "type": "bugfix",
+    "description": "Don't escape markdown within preformat blocks in documentation."
+}

smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/lang/DocumentationPreprocessor.kt

@@ -200,12 +200,19 @@ private fun Node.hasAncestor(predicate: (Node) -> Boolean): Boolean =
 private fun Node.isList() =
     nodeName().let { it == "ul" || it == "ol" }
 
-private fun TextNode.markdownText() =
-    text()
-        // Replace square brackets with escaped equivalents so that they are not rendered as invalid Markdown
-        // links.
+private fun Node.isPreformat() =
+    nodeName().let { it == "code" || it == "pre" }
+
+private fun TextNode.markdownText() = when {
+    // If we're inside a preformat block, everything is literal, ie. no escapes required.
+    hasAncestor(Node::isPreformat) -> text()
+
+    // Replace square brackets with escaped equivalents so that they are not rendered as invalid Markdown
+    // links.
+    else -> text()
         .replace("[", "[")
         .replace("]", "]")
+}
 
 /**
  * Operates on all substrings that fall within the provided section delimiters. Returns a new string where all

smithy-kotlin-codegen/src/test/kotlin/software/amazon/smithy/kotlin/codegen/lang/DocumentationPreprocessorTest.kt

@@ -161,6 +161,21 @@ class DocumentationPreprocessorTest {
         inputTest(input, expected)
     }
 
+    @Test
+    fun `it renders markdown text`() {
+        val input = "<p>This [should be escaped because it's in formatland].</p>" +
+            "<p><code>this should [not]</code></p>" +
+            "<p><pre>nor [should] this</pre></p>"
+        val expected = """
+        This &#91;should be escaped because it's in formatland&#93;.
+        
+        `this should [not]`
+        
+        `nor [should] this`
+        """.trimIndent()
+        inputTest(input, expected)
+    }
+
     @Test
     fun `it fully renders S3 CreateMultipartUpload`() {
         val input = """