enable magic aside blocks in snippet captions

Author: tayloraswift

Sources/MarkdownPluginSwift/Markdown.SwiftLanguage.swift

@@ -26,7 +26,7 @@ extension Markdown.SwiftLanguage:Markdown.CodeLanguageType
 extension Markdown.SwiftLanguage
 {
     public
-    func parse(snippet utf8:[UInt8]) -> (overview:String, slices:[Markdown.SnippetSlice])
+    func parse(snippet utf8:[UInt8]) -> (caption:String, slices:[Markdown.SnippetSlice])
     {
         //  It is safe to escape the pointer to ``Parser.parse(source:maximumNestingLevel:)``,
         //  see: https://swiftinit.org/docs/swift-syntax/swiftparser/parser.init(_:maximumnestinglevel:parsetransition:arena:)
@@ -36,7 +36,7 @@ extension Markdown.SwiftLanguage
         }
 
         var start:AbsolutePosition = parsed.position
-        var text:String = ""
+        var caption:String = ""
         lines:
         for piece:TriviaPiece in parsed.leadingTrivia
         {
@@ -75,8 +75,8 @@ extension Markdown.SwiftLanguage
                 fatalError("Encountered a line comment with no leading slashes!")
             }
 
-            text += line[i...].drop(while: \.isWhitespace)
-            text.append("\n")
+            caption += line[i...].drop(while: \.isWhitespace)
+            caption.append("\n")
         }
 
         var parser:SnippetParser = .init(sourcemap: .init(fileName: "", tree: parsed),
@@ -138,6 +138,6 @@ extension Markdown.SwiftLanguage
             return .init(id: slice.id, line: slice.line, code: bytecode)
         }
 
-        return (text, rendered)
+        return (caption, rendered)
     }
 }

Sources/MarkdownSemantics/Markdown.BlockInterpreter.swift

@@ -274,7 +274,8 @@ extension Markdown.BlockInterpreter
                 var items:[Markdown.BlockItem] = []
                 for item:Markdown.BlockItem in list.elements
                 {
-                    guard let prefix:Markdown.BlockPrefix = .extract(from: &item.elements)
+                    guard
+                    let prefix:Markdown.BlockPrefix = .extract(from: &item.elements)
                     else
                     {
                         items.append(item)

Sources/MarkdownSemantics/Snippets/Markdown.Snippet.swift

@@ -16,7 +16,7 @@ extension Markdown
         public
         let slices:OrderedDictionary<String, SnippetSlice>
 
-        @inlinable public
+        private
         init(id:Int32,
             caption:[Markdown.BlockElement],
             slices:OrderedDictionary<String, SnippetSlice>)
@@ -27,3 +27,72 @@ extension Markdown
         }
     }
 }
+extension Markdown.Snippet
+{
+    public
+    init(id:Int32,
+        caption:String,
+        slices:[Markdown.SnippetSlice],
+        using parser:borrowing some MarkdownParser)
+    {
+        let index:OrderedDictionary<String, Markdown.SnippetSlice> = slices.reduce(
+            into: [:])
+        {
+            $0[$1.id] = $1
+        }
+
+        if  caption.allSatisfy(\.isWhitespace)
+        {
+            self.init(id: id, caption: [], slices: index)
+            return
+        }
+
+        //  Most documentation magic is not available to snippet captions (recursive snippets
+        //  especially), but we still want the magic aside blocks to work.
+        var blocks:[Markdown.BlockElement] = []
+        for block:Markdown.BlockElement in parser.parse(.init(location: .init(
+                position: .zero,
+                file: id),
+            text: caption))
+        {
+            switch block
+            {
+            case let list as Markdown.BlockListUnordered:
+                var items:[Markdown.BlockItem] = []
+                for item:Markdown.BlockItem in list.elements
+                {
+                    if  let prefix:Markdown.BlockPrefix = .extract(from: &item.elements),
+                        case .keywords(let aside) = prefix
+                    {
+                        blocks.append(aside(item.elements))
+                    }
+                    else
+                    {
+                        items.append(item)
+                    }
+                }
+                if !items.isEmpty
+                {
+                    list.elements = items
+                    blocks.append(list)
+                }
+
+            case let quote as Markdown.BlockQuote:
+                if  case .keywords(let aside) = Markdown.BlockPrefix.extract(
+                        from: &quote.elements)
+                {
+                    blocks.append(aside(quote.elements))
+                }
+                else
+                {
+                    blocks.append(quote)
+                }
+
+            case let block:
+                blocks.append(block)
+            }
+        }
+
+        self.init(id: id, caption: blocks, slices: index)
+    }
+}

Sources/SymbolGraphLinker/StaticLinker.swift

@@ -278,30 +278,13 @@ extension StaticLinker
         //  snippets from other snippets.
         return supplements.reduce(into: [:])
         {
-            let (caption, slices):(String, [Markdown.SnippetSlice]) = swift.parse(
+            let snippet:(caption:String, slices:[Markdown.SnippetSlice]) = swift.parse(
                 snippet: $1.utf8)
 
-            let id:Int32 = self.symbolizer.intern($1.path)
-            let blocks:[Markdown.BlockElement]
-
-            if  caption.allSatisfy(\.isWhitespace)
-            {
-                blocks = []
-            }
-            else
-            {
-                blocks = self.doccommentParser.parse(.init(
-                    location: .init(position: .zero, file: id),
-                    text: caption))
-            }
-
-            let index:OrderedDictionary<String, Markdown.SnippetSlice> = slices.reduce(
-                into: [:])
-            {
-                $0[$1.id] = $1
-            }
-
-            $0[$1.name] = .init(id: id, caption: blocks, slices: index)
+            $0[$1.name] = .init(id: self.symbolizer.intern($1.path),
+                caption: snippet.caption,
+                slices: snippet.slices,
+                using: self.doccommentParser)
         }
     }