Experimental markdown output

Package.swift

@@ -33,6 +33,10 @@ let package = Package(
             name: "SwiftDocC",
             targets: ["SwiftDocC"]
         ),
+        .library(
+            name: "SwiftDocCMarkdownOutput",
+            targets: ["SwiftDocCMarkdownOutput"]
+        ),
         .executable(
             name: "docc",
             targets: ["docc"]
@@ -47,6 +51,7 @@ let package = Package(
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
                 .product(name: "CLMDB", package: "swift-lmdb"),
                 .product(name: "Crypto", package: "swift-crypto"),
+                .target(name: "SwiftDocCMarkdownOutput")
             ],
             swiftSettings: swiftSettings
         ),
@@ -126,6 +131,12 @@ let package = Package(
             swiftSettings: swiftSettings
         ),
 
+        // Experimental markdown output
+        .target(
+            name: "SwiftDocCMarkdownOutput",
+            dependencies: []
+        )
+
     ]
 )
 

Sources/SwiftDocC/Converter/DocumentationContextConverter.swift

@@ -101,4 +101,21 @@ public class DocumentationContextConverter {
         )
         return translator.visit(node.semantic) as? RenderNode
     }
+
+    /// Converts a documentation node to a markdown node.
+    /// - Parameters:
+    ///   - node: The documentation node to convert.
+    /// - Returns: The markdown node representation of the documentation node.
+    internal func markdownOutput(for node: DocumentationNode) -> CollectedMarkdownOutput? {
+        guard !node.isVirtual else {
+            return nil
+        }
+
+        var translator = MarkdownOutputNodeTranslator(
+            context: context,
+            bundle: bundle,
+            node: node
+        )
+        return translator.createOutput()
+    }
 }

Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift

@@ -9,6 +9,7 @@
 */
 
 import Foundation
+@_spi(MarkdownOutput) import SwiftDocCMarkdownOutput
 
 #if canImport(os)
 package import os
@@ -81,6 +82,7 @@ package enum ConvertActionConverter {
         var assets = [RenderReferenceType : [any RenderReference]]()
         var coverageInfo = [CoverageDataEntry]()
         let coverageFilterClosure = documentationCoverageOptions.generateFilterClosure()
+        var markdownManifest = MarkdownOutputManifest(title: bundle.displayName, documents: [])
 
         // An inner function to gather problems for errors encountered during the conversion.
         //
@@ -129,6 +131,22 @@ package enum ConvertActionConverter {
                         return
                     }
 
+                    if
+                        FeatureFlags.current.isExperimentalMarkdownOutputEnabled,
+                        let markdownConsumer = outputConsumer as? (any ConvertOutputMarkdownConsumer),
+                        let markdownNode = converter.markdownOutput(for: entity) {
+                        try markdownConsumer.consume(markdownNode: markdownNode.writable)
+                        if
+                            FeatureFlags.current.isExperimentalMarkdownOutputManifestEnabled,
+                            let manifest = markdownNode.manifest
+                        {
+                            resultsGroup.async(queue: resultsSyncQueue) {
+                                markdownManifest.documents.formUnion(manifest.documents)
+                                markdownManifest.relationships.formUnion(manifest.relationships)
+                            }
+                        }
+                    }
+
                     try outputConsumer.consume(renderNode: renderNode)
 
                     switch documentationCoverageOptions.level {
@@ -213,6 +231,12 @@ package enum ConvertActionConverter {
                 }
             }
         }
+
+        if
+            FeatureFlags.current.isExperimentalMarkdownOutputManifestEnabled,
+            let markdownConsumer = outputConsumer as? (any ConvertOutputMarkdownConsumer) {
+            try markdownConsumer.consume(markdownManifest: try markdownManifest.writable)
+        }
 
         switch documentationCoverageOptions.level {
         case .detailed, .brief:

Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift

@@ -9,7 +9,7 @@
 */
 
 import Foundation
-
+@_spi(MarkdownOutput) import SwiftDocCMarkdownOutput
 /// A consumer for output produced by a documentation conversion.
 ///
 /// Types that conform to this protocol manage what to do with documentation conversion products, for example persist them to disk
@@ -50,6 +50,17 @@ public protocol ConvertOutputConsumer {
 
     /// Consumes a file representation of the local link resolution information.
     func consume(linkResolutionInformation: SerializableLinkResolutionInformation) throws
+
+}
+
+// Merge into ConvertOutputMarkdownConsumer when no longer SPI
+@_spi(MarkdownOutput)
+public protocol ConvertOutputMarkdownConsumer {
+    /// Consumes a markdown output node
+    func consume(markdownNode: WritableMarkdownOutputNode) throws
+
+    /// Consumes a markdown output manifest
+    func consume(markdownManifest: WritableMarkdownOutputManifest) throws
 }
 
 // Default implementations that discard the documentation conversion products, for consumers that don't need these