Documentation update

Source/SwiftLintCore/Documentation/RuleDocumentation.swift

@@ -40,6 +40,10 @@ struct RuleDocumentation {
     var fileContents: String {
         let description = ruleType.description
         var content = [h1(description.name), description.description, detailsSummary(ruleType.init())]
+        if let rationale = description.rationale {
+            content += [h2("Rationale")]
+            content.append(formattedRationale(rationale))
+        }
         let nonTriggeringExamples = description.nonTriggeringExamples.filter { !$0.excludeFromDocumentation }
         if nonTriggeringExamples.isNotEmpty {
             content += [h2("Non Triggering Examples")]
@@ -53,6 +57,26 @@ struct RuleDocumentation {
         return content.joined(separator: "\n\n")
     }
 
+    private func formattedRationale(_ rationale: String) -> String {
+        var result = ""
+        var insideMultilineString = false
+        rationale.enumerateLines { line, _ in
+            var formattedLine = line
+            if line.contains("```") {
+                if insideMultilineString {
+                    insideMultilineString = false
+                } else {
+                    insideMultilineString = true
+                    if line.hasSuffix("```") {
+                        formattedLine += "swift"
+                    }
+                }
+            }
+            result += formattedLine + "\n"
+        }
+        return result
+    }
+
     private func formattedCode(_ example: Example) -> String {
         if let config = example.configuration, let configuredRule = try? ruleType.init(configuration: config) {
             let configDescription = configuredRule.createConfigurationDescription(exclusiveOptions: Set(config.keys))

Source/SwiftLintCore/Models/RuleDescription.swift

@@ -12,7 +12,8 @@ public struct RuleDescription: Equatable, Sendable {
     public let description: String
 
     /// A longer explanation of the rule's purpose and rationale. Typically defined as a multiline string, long text 
-    /// lines should be wrapped.
+    /// lines should be wrapped. Markdown formatting is supported. Multiline code blocks will be formatted as
+    /// `swift` code unless otherwise specified.
     public let rationale: String?
 
     /// The `RuleKind` that best categorizes this rule.