From c530437f9a65d22646eb82ca8cd5b68ee5ec1dbc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 27 Aug 2025 18:08:06 +0200
Subject: [PATCH 01/68] Initial HTML output proof of concept

---
 .../ConvertActionConverter.swift              |  13 +-
 .../ConvertOutputConsumer.swift               |   6 +-
 .../Rendering/HTML/HTMLMarkupRender.swift     | 480 ++++++++++
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 837 ++++++++++++++++++
 .../Convert/ConvertFileWritingConsumer.swift  |   8 +
 5 files changed, 1342 insertions(+), 2 deletions(-)
 create mode 100644 Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift
 create mode 100644 Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift

diff --git a/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift b/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
index 17a5db0a70..79a00b834c 100644
--- a/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
+++ b/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
@@ -122,8 +122,19 @@ package enum ConvertActionConverter {
             // Wrap JSON encoding in an autorelease pool to avoid retaining the autoreleased ObjC objects returned by `JSONSerialization`
             autoreleasepool {
                 do {
+                    // FIXME: This needs a feature flag instead of being hard-coded like this
+                    var renderer = HTMLRenderer(reference: identifier, context: context, renderContext: renderContext)
+                    
                     let entity = try context.entity(with: identifier)
-
+                    if let symbol = entity.semantic as? Symbol {
+                        let html = renderer.renderSymbol(symbol)
+                        try outputConsumer.consume(page: html, for: identifier)
+                    } else if let article = entity.semantic as? Article {
+                        let html = renderer.renderArticle(article)
+                        try outputConsumer.consume(page: html, for: identifier)
+                    }
+                    return
+                    
                     guard let renderNode = converter.renderNode(for: entity) else {
                         // No render node was produced for this entity, so just skip it.
                         return
diff --git a/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift b/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift
index f5e1ebd432..5915d58bd1 100644
--- a/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift
+++ b/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift
@@ -8,7 +8,7 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-import Foundation
+public import Foundation
 
 /// A consumer for output produced by a documentation conversion.
 ///
@@ -23,6 +23,9 @@ public protocol ConvertOutputConsumer {
     /// > Warning: This method might be called concurrently.
     func consume(renderNode: RenderNode) throws
     
+    // FIXME: I don't know if the same consumer should handle both kinds of output
+    func consume(page: XMLNode, for reference: ResolvedTopicReference) throws
+    
     /// Consumes a documentation bundle with the purpose of extracting its on-disk assets.
     func consume(assetsInBundle bundle: DocumentationBundle) throws
     
@@ -58,6 +61,7 @@ public extension ConvertOutputConsumer {
     func consume(renderReferenceStore: RenderReferenceStore) throws {}
     func consume(buildMetadata: BuildMetadata) throws {}
     func consume(linkResolutionInformation: SerializableLinkResolutionInformation) throws {}
+    func consume(page: XMLNode, for reference: ResolvedTopicReference) throws {}
 }
 
 // Default implementation so that conforming types don't need to implement deprecated API.
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift
new file mode 100644
index 0000000000..c4151919bd
--- /dev/null
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift
@@ -0,0 +1,480 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+import Markdown
+
+struct HTMLMarkupRender: MarkupVisitor {
+    let reference: ResolvedTopicReference
+    let context: DocumentationContext
+    
+    mutating func defaultVisit(_ markup: any Markdown.Markup) -> XMLNode {
+        fatalError("A placeholder node also crashes here so we might as well make it explicit")
+    }
+    
+    //
+    
+    
+    mutating func visitParagraph(_ paragraph: Paragraph) -> XMLNode {
+        .element(named: "p", children: visit(paragraph.children))
+    }
+    
+    mutating func visitBlockQuote(_ blockQuote: BlockQuote) -> XMLNode {
+        let aside = Aside(blockQuote)
+        
+        var children: [XMLNode] = [
+            .element(named: "p", children: [.text(aside.kind.displayName)], attributes: ["class": "label"])
+        ]
+        for child in aside.content {
+            children.append(visit(child))
+        }
+        
+        return .element(
+            named: "blockquote",
+            children: children,
+            attributes: ["class": "aside \(aside.kind.rawValue.lowercased())"]
+        )
+    }
+    
+    mutating func visitHeading(_ heading: Heading) -> XMLNode {
+        .element(named: "h\(heading.level)", children: visit(heading.children))
+    }
+    
+    mutating func visitEmphasis(_ emphasis: Emphasis) -> XMLNode {
+        .element(named: "i", children: visit(emphasis.children))
+    }
+    
+    mutating func visitStrong(_ strong: Strong) -> XMLNode {
+        .element(named: "b", children: visit(strong.children))
+    }
+    
+    mutating func visitStrikethrough(_ strikethrough: Strikethrough) -> XMLNode {
+        .element(named: "s", children: visit(strikethrough.children))
+    }
+    
+    mutating func visitInlineCode(_ inlineCode: InlineCode) -> XMLNode {
+        .element(named: "code", children: [.text(inlineCode.code)])
+    }
+    
+    func visitText(_ text: Text) -> XMLNode {
+        .text(text.string)
+    }
+    
+    func visitLineBreak(_ lineBreak: LineBreak) -> XMLNode {
+        .element(named: "br")
+    }
+    
+    func visitSoftBreak(_ softBreak: SoftBreak) -> XMLNode {
+        .text(" ") // A soft line break doesn't actually break the content
+    }
+    
+    func visitThematicBreak(_ thematicBreak: ThematicBreak) -> XMLNode {
+        .element(named: "hr")
+    }
+    
+    private func _removeComments(from node: XMLNode) {
+        guard let element = node as? XMLElement,
+              let children = element.children
+        else {
+            return
+        }
+        
+        let withoutComments = children.filter { $0.kind != .comment }
+        element.setChildren(withoutComments)
+        
+        for child in withoutComments {
+            _removeComments(from: child)
+        }
+    }
+    
+    func visitHTMLBlock(_ html: HTMLBlock) -> XMLNode {
+        do {
+            let parsed = try XMLElement(xmlString: html.rawHTML)
+            _removeComments(from: parsed)
+            return parsed
+        } catch {
+            return .text("")
+        }
+    }
+    
+    func visitInlineHTML(_ html: InlineHTML) -> XMLNode {
+        // Inline HTML is one tag at a time, meaning that the closing and opening tags are parsed separately
+        // Because of this, we can't parse it with `XMLElement` or `XMLParser`.
+        
+        // We assume that we want all tags except for comments
+        guard !html.rawHTML.hasPrefix("<!--") else {
+            return .text("")
+        }
+        
+        // We can't create a valid structured XMLNode (because that closing tag will come later,
+        // so we return the raw tag as text.
+        return .text(html.rawHTML)
+    }
+    
+    mutating func visitLink(_ link: Link) -> XMLNode {
+        guard let destination = link.destination else {
+            return .text("")
+        }
+        
+        let customTitle: [XMLNode]?
+        if link.hasChildren {
+            var a = [XMLNode]()
+            for child in link.inlineChildren {
+                a.append(visit(child))
+            }
+            
+            if a == [.text(destination)] {
+                customTitle = nil
+            } else {
+                customTitle = a
+            }
+        } else {
+            customTitle = nil
+        }
+        
+        // Make a relative link
+        if let resolved = context.referenceIndex[destination],
+           let node = context.documentationCache[resolved]
+        {
+            
+            let children = customTitle ?? {
+                switch node.name {
+                    case .conceptual(let title):
+                        [ .text(title) ]
+                    case .symbol(let name):
+                        [ .element(named: "code", children: [.text(name)]) ]
+                }
+            }()
+            
+            return .element(
+                named: "a",
+                children: children,
+                attributes: ["href": path(to: resolved)]
+            )
+        } else if !destination.hasPrefix("doc:") {
+            // This could be a http link
+            
+            let children = customTitle ?? [.text(destination)]
+            
+            return .element(
+                named: "a",
+                children: children,
+                attributes: ["href": destination]
+            )
+        }
+        else {
+            let name = LinkCompletionTools.parse(linkString: destination).last?.name ?? ""
+            return .text(name)
+        }
+    }
+    
+    mutating func visitSymbolLink(_ symbolLink: SymbolLink) -> XMLNode {
+        guard let destination = symbolLink.destination,
+              let resolved = context.referenceIndex[destination],
+              let node = context.documentationCache[resolved],
+              let symbol = node.semantic as? Symbol
+        else {
+            let name = symbolLink.destination.flatMap { LinkCompletionTools.parse(linkString: $0).last?.name } ?? ""
+            return .element(named: "code", children: [.text(name)])
+        }
+        
+        if case .conceptual(let title) = node.name {
+            // Custom title is same in all languages
+            return .element(
+                named: "a",
+                children: [.text(title)],
+                attributes: ["href": path(to: resolved)]
+            )
+        }
+        
+        let link = XMLNode.element(
+            named: "a",
+            children: [],
+            attributes: ["href": path(to: resolved)]
+        )
+        
+        for (trait, variant) in symbol.titleVariants.allValues {
+            guard let lang = trait.interfaceLanguage else { continue }
+            
+            var attributes: [String: String] = [:]
+            if symbol.titleVariants.allValues.count > 1 {
+                attributes["class"] = "\(lang)-only"
+            }
+            
+            link.addChild(
+                .element(named: "code", children: [.text(variant)], attributes: attributes)
+            )
+        }
+        return link
+//
+//        let hasMultipleLanguages = Set(symbol.titleVariants.allValues.map(\.variant)).count > 1
+//        guard hasMultipleLanguages else {
+//            // Same spelling in all languages
+//            return .element(
+//                named: "a",
+//                children: [.element(named: "code", children: [symbol.title])],
+//                attributes: ["href": path(to: resolved)]
+//            )
+//        }
+//        
+//        let titles = symbol.titleVariants.map {
+//            
+//        }
+//        
+//        let titles = symbol.titleVariants.allValues
+//        
+//        let spelling: XMLNode = switch node.name {
+//            case .conceptual(let title): .text(title)
+//            case .symbol(let name):
+//        }
+//        
+//        return .element(
+//            named: "a",
+//            children: [spelling],
+//            attributes: ["href": path(to: resolved)]
+//        )
+    }
+    
+    private func path(to destination: ResolvedTopicReference) -> String {
+        (destination.url.relative(to: reference.url)?.path
+            ?? destination.path) + "/index.html"
+    }
+    
+    
+    func visitImage(_ image: Image) -> XMLNode {
+        guard let source = image.source,
+              let asset = context.resolveAsset(named: source, in: reference)
+        else {
+            return .text("") // ???: What do we return here?
+        }
+        
+        let data = asset.data(bestMatching: .init(userInterfaceStyle: .light, displayScale: .double))
+        
+        let finalImageURL = URL(string: "\(String(repeating: "../", count: reference.pathComponents.count - 1))images/\(reference.bundleID.rawValue)/\(data.url.lastPathComponent)")!
+        
+        var attributes = [
+            "src": finalImageURL.path,
+            "decoding": "async",
+            "loading": "lazy",
+        ]
+        if let scale = data.traitCollection?.displayScale {
+            attributes["srcset"] = "\(finalImageURL.path) \(scale.rawValue)"
+        }
+        if let altText = image.altText {
+            attributes["alt"] = altText
+        }
+        
+        return .element(named: "picture", children: [
+            .element(named: "img", attributes: attributes)
+        ])
+    }
+    
+    func visitCodeBlock(_ codeBlock: CodeBlock) -> XMLNode {
+        let attributes = codeBlock.language.map {
+            ["class": $0]
+        }
+        
+        return .element(
+            named: "pre",
+            children: [
+                .element(named: "code", children: [.text(codeBlock.code)])
+            ],
+            attributes: attributes
+        )
+        
+    }
+    
+    // MARK: List
+    
+    mutating func visitUnorderedList(_ unorderedList: UnorderedList) -> XMLNode {
+        .element(named: "ul", children: visit(unorderedList.children))
+    }
+    
+    mutating func visitOrderedList(_ orderedList: OrderedList) -> XMLNode {
+        .element(named: "ol", children: visit(orderedList.children))
+    }
+    
+    mutating func visitListItem(_ listItem: ListItem) -> XMLNode {
+        .element(named: "li", children: visit(listItem.children))
+    }
+    
+    // MARK: Tables
+    
+    mutating func visitTable(_ table: Table) -> XMLNode {
+        let element = XMLElement(name: "table")
+        
+        var renderer = HTMLMarkupRender(reference: reference, context: context)
+        
+        if !table.head.isEmpty {
+            var column = 0
+            
+            element.addChild(
+                .element(named: "thead", children: [
+                    .element(named: "tr", children: table.head.cells.compactMap { (cell) -> XMLNode? in
+                        defer { column += 1 }
+                        
+                        if cell.colspan == 0 || cell.rowspan == 0 {
+                            return nil
+                        }
+                        
+                        var attributes: [String: String] = [:]
+                        if cell.colspan != 1 {
+                            attributes["colspan"] = "\(cell.colspan)"
+                        }
+                        if cell.rowspan != 1 {
+                            attributes["rowspan"] = "\(cell.rowspan)"
+                        }
+                        
+                        if let alignment = table.columnAlignments[column] {
+                            attributes["class"] = switch alignment {
+                                case .left:   "left"
+                                case .center: "center"
+                                case .right:  "right"
+                            }
+                        }
+                        
+                        return .element(
+                            named: "th",
+                            children: renderer.visit(cell.children),
+                            attributes: attributes
+                        )
+                    })
+                ])
+            )
+        }
+        
+        if !table.body.isEmpty {
+            element.addChild(
+                .element(named: "tbody", children: table.body.rows.map { row in
+                    var column = 0
+                    return .element(named: "tr", children: row.cells.compactMap { (cell) -> XMLNode? in
+                        defer { column += 1 }
+                        
+                        if cell.colspan == 0 || cell.rowspan == 0 {
+                            return nil
+                        }
+                        
+                        var attributes: [String: String] = [:]
+                        if cell.colspan != 1 {
+                            attributes["colspan"] = "\(cell.colspan)"
+                        }
+                        if cell.rowspan != 1 {
+                            attributes["rowspan"] = "\(cell.rowspan)"
+                        }
+                        
+                        if let alignment = table.columnAlignments[column] {
+                            attributes["class"] = switch alignment {
+                                case .left:   "left"
+                                case .center: "center"
+                                case .right:  "right"
+                            }
+                        }
+                        
+                        return .element(
+                            named: "td",
+                            children: renderer.visit(cell.children),
+                            attributes: attributes
+                        )
+                    })
+                })
+            )
+        }
+        
+        return element
+    }
+    
+    // MARK: Markup children
+    
+    private mutating func visit(_ container: MarkupChildren) -> [XMLNode] {
+        var children: [XMLNode] = []
+        children.reserveCapacity(container.underestimatedCount)
+        
+        guard container.contains(where: { $0 is InlineHTML }) else {
+            for element in container {
+                children.append(visit(element))
+            }
+            return children
+        }
+        
+        var elements = Array(container)
+        outer: while !elements.isEmpty {
+            let element = elements.removeFirst()
+            
+            guard let start = element as? InlineHTML else {
+                children.append(visit(element))
+                continue
+            }
+            
+            // Try to parse the smallest valid inline HTML
+            var rawHTML = start.rawHTML
+            guard !rawHTML.hasPrefix("<!--") else {
+                // Skip plain inline comments
+                continue
+            }
+            
+            // Check if this is a a complete "empty-element" tag (for example `<br />` or `<hr />`)
+            if let parsed = try? XMLElement(xmlString: rawHTML) {
+                children.append(parsed)
+                continue
+            }
+            
+            // Gradually increase the content to try and parse
+            var copy = elements
+            inner: while !copy.isEmpty, let next = copy.first as? any InlineMarkup {
+                _ = copy.removeFirst()
+                
+                if let html = next as? InlineHTML, html.rawHTML.hasPrefix("<!--") {
+                    // Skip this comment
+                    continue inner
+                }
+                
+                rawHTML += next.format()
+                if let parsed = try? XMLElement(xmlString: rawHTML) {
+                    children.append(parsed)
+                    elements = copy // Skip over all the elements that make up this parsed node
+                    continue outer
+                }
+                
+            }
+            // Didn't parse anything valid before running out of inline elements.
+            // Just drop this html tag
+            continue
+        }
+        
+        return children
+    }
+    
+    // MARK: Blah
+    
+    func visitBlockDirective(_ blockDirective: BlockDirective) -> XMLNode {
+        .text("") // Do nothing for now
+    }
+    
+    mutating func visitDoxygenNote(_ doxygenNote: DoxygenNote) -> XMLNode {
+        .element(named: "p", children: visit(doxygenNote.children))
+    }
+    
+    mutating func visitDoxygenReturns(_ doxygenReturns: DoxygenReturns) -> XMLNode {
+        .element(named: "p", children: visit(doxygenReturns.children))
+    }
+    
+    mutating func visitDoxygenAbstract(_ doxygenAbstract: DoxygenAbstract) -> XMLNode {
+        .element(named: "p", children: visit(doxygenAbstract.children))
+    }
+    
+    mutating func visitDoxygenParameter(_ doxygenParam: DoxygenParameter) -> XMLNode {
+        .element(named: "p", children: visit(doxygenParam.children))
+    }
+    
+    mutating func visitDoxygenDiscussion(_ doxygenDiscussion: DoxygenDiscussion) -> XMLNode {
+        .element(named: "p", children: visit(doxygenDiscussion.children))
+        
+    }
+}
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
new file mode 100644
index 0000000000..b8f1f533af
--- /dev/null
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -0,0 +1,837 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+import FoundationXML
+#endif
+import Markdown
+import SymbolKit
+
+struct HTMLRenderer {
+    let reference: ResolvedTopicReference
+    let context: DocumentationContext
+    let renderContext: RenderContext
+    
+    private func path(to destination: ResolvedTopicReference) -> String {
+        (destination.url.relative(to: reference.url)?.path
+            ?? destination.path) + "/index.html"
+    }
+    
+    
+    mutating func renderArticle(_ article: Article) -> XMLNode {
+        let node = context.documentationCache[reference]!
+        
+        let main = XMLElement(name: "main")
+        
+        let breadcrumbs = context.shortestFinitePath(to: reference) ?? [context.soleRootModuleReference!]
+        let breadcrumbElements: [XMLNode] = breadcrumbs.map {
+            let node = context.documentationCache[$0]!
+            
+            return .element(named: "a", children: [.text(node.name.plainText)], attributes: ["href": path(to: $0)])
+        }
+        
+        let articleElement = XMLElement(name: "article")
+        main.addChild(articleElement)
+        
+        let hero = XMLElement(name: "section")
+        articleElement.addChild(
+            .element(named: "div", children: [hero], attributes: ["id": article.topics != nil ? "hero-api" : "hero-article"])
+        )
+        
+        // Breadcrumbs and Eyebrow
+        hero.addChild(
+            .element(named: "header", children: [
+                .element(named: "nav", children: [
+                    .element(
+                        named: "ul",
+                        children: (breadcrumbElements + [.text(node.name.plainText)]).map {
+                            .element(named: "li", children: [$0])
+                        },
+                        attributes: ["id": "breadcrumbs"]
+                    )
+                ]),
+                
+                .element(
+                    named: "span",
+                    children: [.text(article.topics == nil ? "Article": "API Collection")],
+                    attributes: ["class": "eyebrow"]
+                ),
+            ])
+        )
+        
+        
+        // FIXME: Add a background for articles
+        // FIXME: Then add a background for the Framework page
+        
+        // Title
+        hero.addChild(
+            .element(
+                named: "h1",
+                children: [.text(node.name.plainText.replacingOccurrences(of: ":", with: ":\u{82}"))], // support breaking on parameters
+                attributes: ["class": "title"]
+            )
+        )
+        
+        // Abstract
+        if let abstract = article.abstract {
+            var renderer = HTMLMarkupRender(reference: reference, context: context)
+            let paragraph = renderer.visitParagraph(abstract) as! XMLElement
+            
+            paragraph.addAttribute(
+                XMLNode.attribute(withName: "id", stringValue: "abstract") as! XMLNode
+            )
+            hero.addChild(paragraph)
+        }
+        
+        // Discussion
+        if let discussion = article.discussion {
+            articleElement.addChild(makeDiscussion(discussion, isSymbol: false))
+        }
+        
+        var hasMadeSeparatedCuration = false
+        
+        func separateCurationIfNeeded() {
+            guard !hasMadeSeparatedCuration else {
+                return
+            }
+            
+            guard let section: XMLElement = (articleElement.children ?? []).reversed().mapFirst(where: {
+                guard let element = $0 as? XMLElement, element.name == "section" else { return nil }
+                return element
+            }) else {
+                return
+            }
+            
+            hasMadeSeparatedCuration = true
+            section.setAttributesWith(["class": "separated"])
+        }
+        
+        // Topics
+        if let topics = article.topics {
+            separateCurationIfNeeded()
+            articleElement.addChild(makeGroupedSection(topics))
+        }
+        
+        // See Also
+        if let seeAlso = article.seeAlso {
+            separateCurationIfNeeded()
+            articleElement.addChild(makeGroupedSection(seeAlso))
+        }
+        if let taskGroup = AutomaticCuration.seeAlso(for: node, withTraits: [.swift, .objectiveC], context: context, bundle: context.bundle, renderContext: renderContext, renderer: .init(documentationContext: context, bundle: context.bundle)) {
+            separateCurationIfNeeded()
+            // Automatice SeeAlso
+            let section = XMLElement(name: "section")
+            
+            if let title = SeeAlsoSection.title {
+                section.addChild(
+                    .selfReferencingHeader(title: title)
+                )
+            }
+            
+            
+            if let heading = taskGroup.title {
+                section.addChild(
+                    .selfReferencingHeader(level: 3, title: heading)
+                )
+            }
+            
+            for link in taskGroup.references {
+                if let element = self.makeTopicSectionItem(for: link) {
+                    section.addChild(element)
+                }
+            }
+            
+            articleElement.addChild(section)
+        }
+        
+        return makePage(main: main, title: article.title?.plainText ?? node.name.plainText, plainDescription: article.abstract?.plainText)
+    }
+    
+    mutating func renderSymbol(_ symbol: Symbol) -> XMLNode {
+        let node = context.documentationCache[reference]!
+        
+        let isDeprecated = symbol.isDeprecated
+        
+        let main = XMLElement(name: "main")
+        
+        let breadcrumbs = context.linkResolver.localResolver.breadcrumbs(of: reference, in: reference.sourceLanguage) ?? []
+        let breadcrumbElements: [XMLNode] = breadcrumbs.map {
+            let node = context.documentationCache[$0]!
+            
+            return .element(named: "a", children: [.text(node.name.plainText)], attributes: ["href": path(to: $0)])
+        }
+        
+        let articleElement = XMLElement(name: "article")
+        main.addChild(articleElement)
+        
+        let hero = XMLElement(name: "section")
+        if symbol.kind.identifier == .module {
+            articleElement.addChild(
+                .element(named: "div", children: [hero], attributes: ["id": "hero-module"])
+            )
+        } else {
+            hero.setAttributesWith(["class": "separated"])
+            articleElement.addChild(hero)
+        }
+        
+        // Breadcrumbs and Eyebrow
+        hero.addChild(
+            .element(named: "header", children: [
+                .element(named: "nav", children: [
+                    .element(
+                        named: "ul",
+                        children: (breadcrumbElements + [.text(node.name.plainText)]).map {
+                            .element(named: "li", children: [$0], attributes: isDeprecated ? ["class": "deprecated"] : nil)
+                        },
+                        attributes: ["id": "breadcrumbs"]
+                    )
+                ]),
+                
+                .element(
+                    named: "span",
+                    children: [.text(symbol.roleHeading)],
+                    attributes: ["class": "eyebrow"]
+                ),
+            ])
+        )
+        
+        // Title
+        let titleVariants = symbol.titleVariants.allValues.sorted(by: { $0.trait < $1.trait})
+        for (trait, variant) in titleVariants {
+            guard let lang = trait.interfaceLanguage else { continue }
+            
+            var classes: [String] = []
+            if titleVariants.count > 1 {
+                classes.append("\(lang)-only")
+            }
+            if isDeprecated {
+                classes.append("deprecated")
+            }
+            
+            let attributes: [String: String]?
+            if classes.isEmpty {
+                attributes = nil
+            } else {
+                attributes = ["class": classes.joined(separator: " ")]
+            }
+            
+            hero.addChild(
+                .element(
+                    named: "h1",
+                    children: makeWordBreakFor(title: variant),
+                    attributes: attributes
+                )
+            )
+        }
+        
+        // Abstract
+        if let abstract = symbol.abstract {
+            var renderer = HTMLMarkupRender(reference: reference, context: context)
+            let paragraph = renderer.visitParagraph(abstract) as! XMLElement
+            
+            paragraph.addAttribute(
+                XMLNode.attribute(withName: "id", stringValue: "abstract") as! XMLNode
+            )
+            hero.addChild(paragraph)
+        }
+        
+        // Availability
+        if let availability = symbol.availability?.availability {
+            // ???: Do we want a div for this?
+            let container = XMLNode.element(named: "div", attributes: ["class": "availability"])
+            hero.addChild(container)
+            
+            for item in availability.filter({ $0.domain != nil }).sorted(by: \.domain!.rawValue) {
+                let name = item.domain!.rawValue
+                
+                let introducedVersion = item.introducedVersion.map {
+                    "\($0.major).\($0.minor)"
+                }
+                let deprecatedVersion = item.deprecatedVersion.map {
+                    "\($0.major).\($0.minor)"
+                }
+                
+                let short: String
+                let description: String
+                if let introducedVersion {
+                    if let deprecatedVersion {
+                        short = " \(introducedVersion)–\(deprecatedVersion)"
+                        description = "Introduced in \(name) \(introducedVersion) and deprecated in \(name) \(deprecatedVersion)"
+                    } else {
+                        short = " \(introducedVersion)+"
+                        description = "Available on \(introducedVersion) and later"
+                    }
+                } else {
+                    short = ""
+                    description = "Available on \(name)"
+                }
+                let text = "\(name) \(short)"
+                
+                var attributes = [
+                    "role": "text",
+                    "aria-label": "\(text), \(description)",
+                    "title": description
+                ]
+                if isDeprecated {
+                    attributes["class"] = "deprecated"
+                }
+                
+                // TODO: Add deprecated and beta badges
+                container.addChild(
+                    .element(
+                        named: "span",
+                        children: [.text(text)],
+                        attributes: attributes
+                    )
+                )
+            }
+            
+        }
+        
+        // Declaration
+        for (trait, variant) in symbol.declarationVariants.allValues.sorted(by: { $0.trait < $1.trait}) {
+            guard let lang = trait.interfaceLanguage else { continue }
+            
+            for (/*platforms*/_, declaration) in variant {
+                // FIXME: Pretty print declarations for Swift and Objective-C
+                
+                hero.addChild(
+                    .element(named: "pre", children: [
+                        .element(named: "code", children: declaration.declarationFragments.map { fragment in
+                            // ???: Do `.text` tokens need to be wrapped in a span?
+                            if fragment.kind == .typeIdentifier,
+                               let symbolID = fragment.preciseIdentifier,
+                               let reference = context.localOrExternalReference(symbolID: symbolID)
+                            {
+                                // Make a link
+                                return .element(named: "span", children: [
+                                    .element(
+                                        named: "a",
+                                        children: [.text(fragment.spelling)],
+                                        attributes: ["href": path(to: reference)]
+                                    )
+                                ], attributes: ["class": "type-identifier-link"])
+                            }
+                            else {
+                                return .element(named: "span", children: [.text(fragment.spelling)], attributes: ["class": "token-\(fragment.kind.rawValue)"])
+                            }
+                        })
+                    ], attributes: ["class": "\(lang)-only"])
+                )
+            }
+        }
+        
+        // Deprecation message
+        if let deprecationSummary = symbol.deprecatedSummary {
+            var renderer = HTMLMarkupRender(reference: reference, context: context)
+            var children: [XMLNode] = [
+                .element(named: "p", children: [.text("Deprecated")], attributes: ["class": "label"])
+            ]
+            for child in deprecationSummary.content {
+                children.append(renderer.visit(child))
+            }
+            
+            hero.addChild(
+                .element(
+                    named: "blockquote",
+                    children: children,
+                    attributes: ["class": "aside deprecated"]
+                )
+            )
+        }
+        
+        
+        // Parameters
+        if let parameters = symbol.parametersSection, !parameters.parameters.isEmpty {
+            let section = XMLElement(name: "section")
+            section.addAttribute(
+                XMLNode.attribute(withName: "class", stringValue: "parameters") as! XMLNode
+            )
+            
+            if let title = ParametersSection.title {
+                section.addChild(
+                    .selfReferencingHeader(title: title)
+                )
+            }
+            
+            var renderer = HTMLMarkupRender(reference: reference, context: context)
+            
+            let list = XMLElement(name: "dl") // list
+            section.addChild(list)
+            
+            for parameter in parameters.parameters {
+                // name
+                list.addChild(
+                    .element(named: "dt", children: [
+                        .element(named: "code", children: [.text(parameter.name)])
+                    ])
+                )
+                
+                // description
+                list.addChild(
+                    .element(named: "dd", children: parameter.contents.map { renderer.visit($0) })
+                )
+            }
+            
+            articleElement.addChild(section)
+        }
+        
+        // Return value
+        if let returnsSection = symbol.returnsSection {
+            let section = XMLElement(name: "section")
+            section.addAttribute(
+                XMLNode.attribute(withName: "class", stringValue: "return-value") as! XMLNode
+            )
+            
+            if let title = ReturnsSection.title {
+                section.addChild(
+                    .selfReferencingHeader(title: title)
+                )
+            }
+            
+            var renderer = HTMLMarkupRender(reference: reference, context: context)
+            
+            for markup in returnsSection.content {
+                section.addChild(
+                    renderer.visit(markup)
+                )
+            }
+            
+            articleElement.addChild(section)
+        }
+        
+        // Discussion
+        if let discussion = symbol.discussion {
+            articleElement.addChild(makeDiscussion(discussion, isSymbol: true))
+        }
+        
+        var hasMadeSeparatedCuration = false
+        
+        func separateCurationIfNeeded() {
+            guard !hasMadeSeparatedCuration else {
+                return
+            }
+            
+            guard let section: XMLElement = (articleElement.children ?? []).reversed().mapFirst(where: {
+                guard let element = $0 as? XMLElement, element.name == "section" else { return nil }
+                return element
+            }) else {
+                return
+            }
+            
+            hasMadeSeparatedCuration = true
+            section.setAttributesWith(["class": "separated"])
+        }
+        
+        // Topics
+        if let topics = symbol.topics {
+            separateCurationIfNeeded()
+            
+            articleElement.addChild(makeGroupedSection(topics))
+        }
+        if let automaticTopics = try? AutomaticCuration.topics(for: node, withTraits: [.swift, .objectiveC], context: context) {
+            // Automatice SeeAlso
+            let section = XMLElement(name: "section")
+            
+            var didAddAnyLink = false
+            
+            if let title = TopicsSection.title {
+                section.addChild(
+                    .selfReferencingHeader(title: title)
+                )
+            }
+            
+            for automaticTopic in automaticTopics {
+                if let heading = automaticTopic.title {
+                    section.addChild(
+                        .selfReferencingHeader(level: 3, title: heading)
+                    )
+                }
+                
+                for link in automaticTopic.references {
+                    if let element = self.makeTopicSectionItem(for: link) {
+                        didAddAnyLink = true
+                        section.addChild(element)
+                    }
+                }
+            }
+            
+            if didAddAnyLink {
+                separateCurationIfNeeded()
+                articleElement.addChild(section)
+            }
+        }
+        
+        // See Also
+        if let seeAlso = symbol.seeAlso {
+            separateCurationIfNeeded()
+            articleElement.addChild(makeGroupedSection(seeAlso))
+        }
+        
+        if let taskGroup = AutomaticCuration.seeAlso(for: node, withTraits: [.swift, .objectiveC], context: context, bundle: context.bundle, renderContext: renderContext, renderer: .init(documentationContext: context, bundle: context.bundle)) {
+            // Automatice SeeAlso
+            let section = XMLElement(name: "section")
+            separateCurationIfNeeded()
+            
+            if let title = SeeAlsoSection.title {
+                section.addChild(
+                    .selfReferencingHeader(title: title)
+                )
+            }
+            
+            if let heading = taskGroup.title {
+                section.addChild(
+                    .selfReferencingHeader(level: 3, title: heading)
+                )
+            }
+            
+            for link in taskGroup.references {
+                if let element = self.makeTopicSectionItem(for: link) {
+                    section.addChild(element)
+                }
+            }
+            
+            articleElement.addChild(section)
+        }
+        
+        return makePage(main: main, title: symbol.title, plainDescription: symbol.abstract?.plainText)
+    }
+    
+    private func makeWordBreakFor(title: String) -> [XMLNode] {
+        
+        var result: [XMLNode] = []
+        
+        var remaining = title[...]
+        
+        while let splitIndex = remaining.firstIndex(where: { $0 == ":" || $0 == "(" || $0 == ")" }) {
+            var part = remaining[...splitIndex]
+            if part.first?.isWhitespace == true {
+                part = part.dropFirst()
+            }
+            result.append(.text(part))
+            
+            remaining = remaining[splitIndex...].dropFirst()
+            if !remaining.isEmpty {
+                result.append(.element(named: "wbr"))
+            }
+        }
+        
+        result.append(.text(remaining))
+        
+        return result
+    }
+    
+    private func makeDiscussion(_ discussion: DiscussionSection, isSymbol: Bool) -> XMLNode {
+        let section = XMLElement(name: "section")
+        
+        // Don't add a heading if it's already authored
+        if (discussion.content.first as? Heading)?.level != 2 {
+            section.addChild(
+                .selfReferencingHeader(title: isSymbol ? "Discussion" : "Overview")
+            )
+        }
+        
+        var renderer = HTMLMarkupRender(reference: reference, context: context)
+        
+        var remaining = discussion.content[...]
+        if let heading = discussion.content.first as? Heading, heading.level == 2 {
+            _ = remaining.removeFirst()
+            section.addChild(
+                .selfReferencingHeader(title: heading.title)
+            )
+        }
+        
+        for markup in remaining {
+            section.addChild(
+                renderer.visit(markup)
+            )
+        }
+        
+        return section
+    }
+    
+    private func makeGroupedSection<Grouped: GroupedSection>(_ groupedSection: Grouped) -> XMLNode {
+        let section = XMLElement(name: "section")
+        
+        if let title = Grouped.title {
+            section.addChild(
+                .selfReferencingHeader(title: title)
+            )
+        }
+        
+        for taskGroup in groupedSection.taskGroups {
+            if let heading = taskGroup.heading {
+                section.addChild(
+                    .selfReferencingHeader(level: 3, title: heading.title)
+                )
+            }
+            
+            for link in taskGroup.links {
+                guard let destination = link.destination,
+                      let reference = context.referenceIndex[destination]
+                else {
+                    // Unresolved links wouldn't be found here
+                    continue
+                }
+                
+                if let element = self.makeTopicSectionItem(for: reference) {
+                    section.addChild(element)
+                }
+            }
+        }
+        
+        return section
+    }
+    
+    private func makeTopicSectionItem(for reference: ResolvedTopicReference) -> XMLNode? {
+        var renderer = HTMLMarkupRender(reference: reference, context: context)
+        
+        if let local = context.documentationCache[reference] {
+            let container = XMLNode.element(named: "div")//, attributes: ["class": className])
+            var className = "link-block"
+             
+            // Title
+            var titles: [XMLNode]? = nil
+            if let symbol = local.semantic as? Symbol {
+                if symbol.isDeprecated {
+                    className += " deprecated"
+                }
+                
+                if case .conceptual(let title) = local.name {
+                    // FIXME: What element and class should this be?
+                    titles = [.element(named: "span", children: [.text(title)])]
+                    
+                }
+                else  {
+                    titles = symbol.subHeadingVariants
+                        .allValues.sorted(by: { $0.trait < $1.trait})
+                        .compactMap { trait, variant in
+                            guard let lang = trait.interfaceLanguage else { return nil }
+                            
+                            return .element(
+                                named: "code",
+                                children: variant.map { fragment in
+                                    let className = switch fragment.kind {
+                                        case .identifier, .externalParameter:
+                                            "identifier"
+                                        default:
+                                            "decorator"
+                                    }
+                                    
+                                    return .element(named: "span", children: makeWordBreakFor(title: fragment.spelling), attributes: ["class": className])
+                                },
+                                attributes: ["class": "\(lang)-only"]
+                            )
+                        }
+                }
+                
+            } else if let article = local.semantic as? Article {
+                if let heading = article.title {
+                    // FIXME: What element and class should this be?
+                    titles = [.element(named: "span", children: [.text(heading.title)])]
+                }
+            }
+            container.setAttributesWith(["class": className])
+            if let titles {
+                container.addChild(
+                    .element(named: "a", children: titles, attributes: ["href": path(to: reference)])
+                )
+            }
+            
+            // Abstract
+            if let abstract = (local.semantic as? any Abstracted)?.abstract {
+                container.addChild(renderer.visitParagraph(abstract))
+            }
+            
+            return container
+        } else if let external = context.externalCache[reference] {
+            let container = XMLNode.element(named: "div", attributes: ["class": "link-block"])
+            
+            let renderReference = external.topicRenderReference
+            let title: XMLNode
+            if renderReference.kind == .symbol, let fragments = renderReference.fragments {
+                title = .element(named: "code", children: fragments.map { fragment in
+                    let className = fragment.kind == .identifier ? "identifier" : "decorator"
+                    return .element(named: "span", children: [.text(fragment.text)], attributes: ["class": className])
+                })
+            } else {
+                // FIXME: What element and class should this be?
+                title = .element(named: "span", children: [.text(renderReference.title)])
+            }
+            
+            container.addChild(
+                .element(named: "a", children: [title], attributes: ["href": path(to: reference)])
+            )
+            
+            // TODO: Support external abstracts as well
+            
+            return container
+        }
+        return nil
+    }
+    
+    private func makePage(main: XMLNode, title: String, plainDescription: String?) -> XMLNode {
+        let head = XMLElement(name: "head")
+        head.setChildren([
+            // <meta charset="utf-8">
+            .element(named: "meta", attributes: ["charset": "utf-8"]),
+            
+            // <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+            .metaElement(name: "viewport", content: "width=device-width,initial-scale=1,viewport-fit=cover"),
+            
+            // <link rel="icon" href="/favicon.ico">
+            .element(named: "link", attributes: [
+                "rel": "icon",
+                "href": "/favicon.ico", // ???: Should this be relative to the page?
+            ]),
+            
+            // <link rel="mask-icon" href="/apple-logo.svg" color="#333333">
+            .element(named: "link", attributes: [
+                "rel": "mask-icon",
+                "href": "/apple-logo.svg", // ???: Should this be relative to the page?
+                "color": "#333333",
+            ]),
+            
+            .element(named: "title", children: [
+                .text(title)
+            ]),
+            
+            // <link rel="stylesheet" href="styles.css" />
+            .element(named: "link", attributes: [
+                "rel": "stylesheet",
+                "href": String(repeating: "../", count: reference.url.pathComponents.count - 1) + "styles.css"
+            ]),
+            
+            .element(named: "script", attributes: [
+                "type": "text/javascript",
+                "src": String(repeating: "../", count: reference.url.pathComponents.count - 1) + "reference.js"
+            ]),
+            
+            // FIXME: Include OpenGraph metadata
+        ])
+        if let abstract = plainDescription {
+            head.addChild(
+                .metaElement(name: "description", content: abstract)
+            )
+        }
+        
+        // FIXME: Add the page header here
+        let header = XMLNode.element(
+            named: "header",
+            children: [
+                .element(named: "button", attributes: ["id": "sidebar-toggle", "onclick": "toggleSidebar()"]),
+                
+                .element(
+                    named: "span",
+                    children: [.text("Documentation")],
+                    attributes: ["id": "header-title"]
+                ),
+                
+                .element(named: "div", children: [
+                    .element(named: "label", children: [.text("Language: ")], attributes: ["for": "language-toggle"]),
+                    
+                    .element(
+                        named: "select",
+                        children: [
+                            .element(named: "option", children: [.text("Swift")], attributes: ["value": "swift"]),
+                            .element(named: "option", children: [.text("Objective-C")], attributes: ["value": "occ"]),
+                        ],
+                        attributes: ["id": "language-toggle", "onchange": "languageChanged()"]
+                    ),
+                ])
+            ]
+        )
+        
+        // Wrap up the page
+        let document = XMLDocument(rootElement: .element(
+            named: "html",
+            children: [
+                head,
+                .element(named: "body", children: [
+                    header,
+                    main // Passes as an argument
+                ])
+            ],
+            attributes: ["lang": "en-US"]
+        ))
+        document.documentContentKind = .xhtml
+        
+        let docTypeDefinition = XMLDTD()
+        docTypeDefinition.publicID = "-//W3C//DTD XHTML 1.0 Strict//EN"
+        docTypeDefinition.systemID = "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
+        docTypeDefinition.name = "html"
+        document.dtd = docTypeDefinition
+        
+        return document
+    }
+    
+}
+
+// FIXME: Move these extensions to a file or maybe write our own html nodes
+extension XMLNode {
+    static func element(
+        named name: String,
+        children: [XMLNode]? = nil,
+        attributes: [String: String]? = nil,
+    ) -> XMLElement {
+        let attributeNodes: [XMLNode]?
+        if let attributes, !attributes.isEmpty {
+            attributeNodes = attributes.sorted(by: \.key).map {
+                XMLNode.attribute(withName: $0.key, stringValue: $0.value) as! XMLNode
+            }
+        } else {
+            attributeNodes = nil
+        }
+        
+        return XMLNode.element(
+            withName: name,
+            children: children,
+            attributes: attributeNodes
+        ) as! XMLElement
+    }
+    
+    static func text(_ value: some StringProtocol) -> XMLNode {
+        XMLNode.text(withStringValue: String(value)) as! XMLNode
+    }
+}
+
+extension XMLNode {
+    static func metaElement(name: String, content: String) -> XMLElement {
+        .element(named: "meta", attributes: ["name": name, "content": content])
+    }
+    
+    static func metaElement(property: String, content: String) -> XMLElement {
+        .element(named: "meta", attributes: ["property": property, "content": content])
+    }
+    
+    static func selfReferencingHeader(level: Int = 2, title: String) -> XMLElement {
+        let id = urlReadableFragment(title)
+        return .element(
+            named: "h\(level)",
+            children: [
+                .element(
+                    named: "a",
+                    children: [.text(title)],
+                    attributes: ["href": "#\(id)"]
+                )
+            ],
+            attributes: ["id": id]
+        )
+    }
+}
+
+// Note; this isn't a Comparable conformance because I wanted it to be private to this file.
+private extension DocumentationDataVariantsTrait {
+    static func < (lhs: DocumentationDataVariantsTrait, rhs: DocumentationDataVariantsTrait) -> Bool {
+        (lhs.interfaceLanguage ?? "") < (rhs.interfaceLanguage ?? "")
+    }
+}
diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift
index 56e4925851..76fa22c3d5 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift
@@ -68,6 +68,14 @@ struct ConvertFileWritingConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
         indexer?.index(renderNode)
     }
     
+    func consume(page: XMLNode, for reference: ResolvedTopicReference) throws {
+        let htmlString = page.xmlString//(options: .nodePrettyPrint)
+        
+        let url = targetFolder.appendingPathComponent(reference.path)
+        try? fileManager.createDirectory(at: url, withIntermediateDirectories: true, attributes: nil)
+        try htmlString.write(to: url.appendingPathComponent("index.html"), atomically: true, encoding: .utf8)
+    }
+    
     func consume(externalRenderNode: ExternalRenderNode) throws {
         // Index the external node, if indexing is enabled.
         indexer?.index(externalRenderNode)

From b15fcf1ea4225615339cc2b8b8c339fbf8201d16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sun, 28 Sep 2025 11:23:41 +0200
Subject: [PATCH 02/68] Start adding core rendering tests

---
 .../HTML/HTMLMarkupRenderTests.swift          | 355 ++++++++++++++++++
 1 file changed, 355 insertions(+)
 create mode 100644 Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift

diff --git a/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift b/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift
new file mode 100644
index 0000000000..6f547b7983
--- /dev/null
+++ b/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift
@@ -0,0 +1,355 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+import XCTest
+@testable import SwiftDocC
+import Markdown
+
+final class HTMLMarkupRenderTests: XCTestCase {
+ 
+    func testRenderParagraphsWithFormattedText() async throws {
+        try await assert(
+            rendering: "This is a paragraph with _emphasized_ and **strong** text.",
+            matches: "<p>This is a paragraph with <i>emphasized</i> and <b>strong</b> text.</p>"
+        )
+        
+        try await assert(
+            rendering: "This is a paragraph with ~strikethrough~ and `pre-formatted` text.",
+            matches: "<p>This is a paragraph with <s>strikethrough</s> and <code>pre-formatted</code> text.</p>"
+        )
+        
+        try await assert(
+            rendering: #"This is a paragraph with "double" and 'single' quoted text."#,
+            matches: "<p>This is a paragraph with “double” and ‘single’ quoted text.</p>"
+        )
+    }
+    
+    func testRenderHeadings() async throws {
+        try await assert(
+            rendering: """
+            # One
+            
+            ## Two
+            
+            ### Three
+            """,
+            prettyFormatted: true,
+            matches: """
+            <h1>One</h1>
+            <h2>Two</h2>
+            <h3>Three</h3>
+            """
+        )
+        
+        try await assert(
+            rendering: """
+            One
+            ===
+            
+            Two
+            ---
+            """,
+            prettyFormatted: true,
+            matches: """
+            <h1>One</h1>
+            <h2>Two</h2>
+            """
+        )
+        
+        try await assert(
+            rendering: """
+            # _One_
+            
+            ## **Two**
+            
+            ### `Three`
+            """,
+            prettyFormatted: true,
+            matches: """
+            <h1>
+            <i>One</i>
+            </h1>
+            <h2>
+            <b>Two</b>
+            </h2>
+            <h3>
+            <code>Three</code>
+            </h3>
+            """
+        )
+    }
+    
+    func testRenderTables() async throws {
+        try await assert(
+            rendering: """
+            First  | Second  | 
+            ------ | ------- |
+            One    | Two     | 
+            """,
+            prettyFormatted: true,
+            // It's weird that XMLNode doesn't indent the <table> children
+            matches: """
+            <table>
+            <thead>
+                <tr>
+                    <th>First</th>
+                    <th>Second</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td>One</td>
+                    <td>Two</td>
+                </tr>
+            </tbody>
+            </table>
+            """
+        )
+        
+        try await assert(
+            rendering: """
+            First | Second | Third |
+            ----- | ------ | ----- |
+            One           || Two   |
+            Three | Four          ||
+            Five                 |||
+            """,
+            prettyFormatted: true,
+            // It's weird that XMLNode doesn't indent the <table> children
+            matches: """
+            <table>
+            <thead>
+                <tr>
+                    <th>First</th>
+                    <th>Second</th>
+                    <th>Third</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td colspan="2">One</td>
+                    <td>Two</td>
+                </tr>
+                <tr>
+                    <td>Three</td>
+                    <td colspan="2">Four</td>
+                </tr>
+                <tr>
+                    <td colspan="3">Five</td>
+                </tr>
+            </tbody>
+            </table>
+            """
+        )
+        
+        try await assert(
+            rendering: """
+            First | Second | Third | Fourth 
+            ----- | ------ | ----- | ------
+            One   | Two    | Three | Four
+            ^     | Five   | ^     | Six
+            Seven | ^      | ^     | Eight
+            """,
+            prettyFormatted: true,
+            // It's weird that XMLNode doesn't indent the <table> children
+            matches: """
+            <table>
+            <thead>
+                <tr>
+                    <th>First</th>
+                    <th>Second</th>
+                    <th>Third</th>
+                    <th>Fourth</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td rowspan="2">One</td>
+                    <td>Two</td>
+                    <td rowspan="3">Three</td>
+                    <td>Four</td>
+                </tr>
+                <tr>
+                    <td rowspan="2">Five</td>
+                    <td>Six</td>
+                </tr>
+                <tr>
+                    <td>Seven</td>
+                    <td>Eight</td>
+                </tr>
+            </tbody>
+            </table>
+            """
+        )
+    }
+    
+    func testRenderLists() async throws {
+        try await assert(
+            rendering: """
+            - First
+            - Second
+              + A
+              + B
+            - Third
+              1. One
+              2. Two
+                 * Inner
+            """,
+            prettyFormatted: true,
+            // It's weird that XMLNode doesn't indent the outmost <ul> children
+            matches: """
+            <ul>
+            <li>
+                <p>First</p>
+            </li>
+            <li>
+                <p>Second</p>
+                <ul>
+                    <li>
+                        <p>A</p>
+                    </li>
+                    <li>
+                        <p>B</p>
+                    </li>
+                </ul>
+            </li>
+            <li>
+                <p>Third</p>
+                <ol>
+                    <li>
+                        <p>One</p>
+                    </li>
+                    <li>
+                        <p>Two</p>
+                        <ul>
+                            <li>
+                                <p>Inner</p>
+                            </li>
+                        </ul>
+                    </li>
+                </ol>
+            </li>
+            </ul>
+            """
+        )
+    }
+    
+    func testRenderAsides() async throws {
+        try await assert(
+            rendering: """
+            > Note: Something noteworthy
+            >
+            > > Important: Something important
+            """,
+            prettyFormatted: true,
+            // It's weird that XMLNode doesn't indent the <ul> children
+            matches: """
+            <blockquote class="aside note">
+            <p class="label">Note</p>
+            <p>Something noteworthy</p>
+            <blockquote class="aside important">
+                <p class="label">Important</p>
+                <p>Something important</p>
+            </blockquote>
+            </blockquote>
+            """
+        )
+    }
+    
+    func testRenderCodeBlocks() async throws {
+        try await assert(
+            rendering: """
+            ~~~
+            Some block of code
+            ~~~
+            """,
+            prettyFormatted: true,
+            matches: """
+            <pre>
+            <code>Some block of code
+            </code>
+            </pre>
+            """
+        )
+        
+        try await assert(
+            rendering: """
+                Some block of code
+            """,
+            prettyFormatted: true,
+            matches: """
+            <pre>
+            <code>Some block of code
+            </code>
+            </pre>
+            """
+        )
+        
+        try await assert(
+            rendering: """
+            ```lang
+            Some block of code
+            ```
+            """,
+            prettyFormatted: true,
+            matches: """
+            <pre class="lang">
+            <code>Some block of code
+            </code>
+            </pre>
+            """
+        )
+        
+    }
+    
+    func testRenderMiscellaneousElements() async throws {
+        try await assert(
+            rendering: "First\nSecond", // new lines usually have no special meaning in markdown...
+            matches: "<p>First Second</p>"
+        )
+        
+        try await assert(
+            rendering: "First  \nSecond", // ... but with two trailing spaces they are treated as line breaks
+            matches: "<p>First<br/>Second</p>"
+        )
+        
+        try await assert(
+            rendering: """
+            -------
+            """,
+            matches: "<hr/>"
+        )
+    }
+    
+    private func assert(
+        rendering markdownContent: String,
+        prettyFormatted: Bool = false,
+        matches expectedHTML: String,
+        file: StaticString = #filePath,
+        line: UInt = #line
+    ) async throws {
+        let markup = Document(parsing: markdownContent)
+        
+        let (_, context) = try await testBundleAndContext()
+        let reference = ResolvedTopicReference(bundleID: "com.test", path: "/something", sourceLanguage: .swift)
+        var renderer = HTMLMarkupRender(reference: reference, context: context)
+        
+        let htmlNodes = markup.children.map { renderer.visit($0) }
+        
+        let htmlString = if prettyFormatted {
+            htmlNodes.map { $0.xmlString(options: [.nodePrettyPrint, .nodeCompactEmptyElement]) }.joined(separator: "\n")
+        } else {
+            htmlNodes.map { $0.xmlString(options: .nodeCompactEmptyElement) }.joined(separator: "")
+        }
+        
+        XCTAssertEqual(htmlString, expectedHTML, file: file, line: line)
+    }
+}

From 4e119f60d54a7aa8b230d4ef3fd8bba66fa35b10 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sun, 28 Sep 2025 17:49:04 +0200
Subject: [PATCH 03/68] Extract returning link and asset information

---
 .../Rendering/HTML/HTMLMarkupRender.swift     | 242 ++++++++++--------
 .../Model/Rendering/HTML/HTMLRenderer.swift   |  88 ++++++-
 .../HTML/HTMLMarkupRenderTests.swift          |  85 +++++-
 3 files changed, 289 insertions(+), 126 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift
index c4151919bd..04568d8e95 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift
@@ -11,9 +11,58 @@
 import Foundation
 import Markdown
 
-struct HTMLMarkupRender: MarkupVisitor {
-    let reference: ResolvedTopicReference
-    let context: DocumentationContext
+/// A type that provides information about other pages, and on-page elements, that the rendered page references.
+protocol LinkProvider {
+    /// Provide information about another page or on-page element, or `nil` if the other page can't be found.
+    func element(for path: URL) -> LinkedElement?
+    
+    /// Provide information about an asset, or `nil` if the asset can't be found.
+    func assetNamed(_ assetName: String) -> LinkedAsset?
+}
+
+struct LinkedElement {
+    /// The path within the output archive to the linked element.
+    var path: URL
+    /// The names of the linked element.
+    ///
+    /// Articles, headings, tutorials, and similar pages have a ``Names/single/conceptual(_:)`` name.
+    ///
+    var names: Names
+    enum Names {
+        /// This element has the same name in all language representations
+        case single(Name)
+        /// This element is a symbol with different names in different languages.
+        ///
+        /// Because `@DisplayName` applies to all language representations, these language specific names are always the symbol's subheading declaration and should display in a monospaced font.
+        case languageSpecificSymbol([String /* Language ID */: String])
+    }
+    enum Name {
+        /// The name refers to an article, heading, or custom `@DisplayName` and should display as regular text.
+        case conceptual(String)
+        /// The name refers to a symbol's subheading declaration and should display in a monospaced font.
+        case symbol(String)
+    }
+}
+
+struct LinkedAsset {
+    /// The path within the output archive to each image variant, by their light/dark style.
+    var images: [ColorStyle: [Int /* display scale*/: URL]]
+    
+    enum ColorStyle: String {
+        case light, dark
+    }
+}
+
+struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
+    /// The path within the output archive to the page that this renderer renders.
+    let path: URL
+    /// A type that provides information about other pages that the rendered page references.
+    let linkProvider: Provider
+    
+    init(path: URL, linkProvider: Provider) {
+        self.path = path
+        self.linkProvider = linkProvider
+    }
     
     mutating func defaultVisit(_ markup: any Markdown.Markup) -> XMLNode {
         fatalError("A placeholder node also crashes here so we might as well make it explicit")
@@ -119,161 +168,130 @@ struct HTMLMarkupRender: MarkupVisitor {
     }
     
     mutating func visitLink(_ link: Link) -> XMLNode {
-        guard let destination = link.destination else {
+        guard let destination = link.destination.flatMap({ URL(string: $0) }) else {
             return .text("")
         }
         
-        let customTitle: [XMLNode]?
         if link.hasChildren {
-            var a = [XMLNode]()
+            var customTitle = [XMLNode]()
             for child in link.inlineChildren {
-                a.append(visit(child))
+                customTitle.append(visit(child))
             }
             
-            if a == [.text(destination)] {
-                customTitle = nil
-            } else {
-                customTitle = a
+            if customTitle != [.text(destination.absoluteString)] {
+                return .element(
+                    named: "a",
+                    children: customTitle,
+                    attributes: [
+                        // Use relative links for DocC elements, and the full link otherwise.
+                        "href": linkProvider.element(for: destination).flatMap { path(to: $0.path) } ?? destination.absoluteString
+                    ]
+                )
             }
-        } else {
-            customTitle = nil
         }
         
         // Make a relative link
-        if let resolved = context.referenceIndex[destination],
-           let node = context.documentationCache[resolved]
-        {
-            
-            let children = customTitle ?? {
-                switch node.name {
-                    case .conceptual(let title):
-                        [ .text(title) ]
-                    case .symbol(let name):
-                        [ .element(named: "code", children: [.text(name)]) ]
-                }
-            }()
+        if let linkedElement = linkProvider.element(for: destination) {
+            let children: [XMLNode] = switch linkedElement.names {
+                case .single(let name):
+                    switch name {
+                        case .conceptual(let name): [ .text(name) ]
+                        case .symbol(let name):     [ .element(named: "code", children: [.text(name)]) ]
+                    }
+                    
+                case .languageSpecificSymbol(let namesByLanguageID):
+                    namesByLanguageID.sorted(by: \.key).map { languageID, name in
+                            .element(named: "code", children: [.text(name)], attributes: ["class": "\(languageID)-only"])
+                    }
+            }
             
             return .element(
                 named: "a",
                 children: children,
-                attributes: ["href": path(to: resolved)]
+                attributes: ["href": path(to: linkedElement.path)]
             )
-        } else if !destination.hasPrefix("doc:") {
+        } else if destination.scheme != "doc" {
             // This could be a http link
-            
-            let children = customTitle ?? [.text(destination)]
-            
             return .element(
                 named: "a",
-                children: children,
-                attributes: ["href": destination]
+                children: [.text(destination.absoluteString)],
+                attributes: ["href": destination.absoluteString]
             )
-        }
-        else {
-            let name = LinkCompletionTools.parse(linkString: destination).last?.name ?? ""
-            return .text(name)
+        } else {
+            // If this is an unresolved documentation link, try to display only the name of the linked symbol; without the rest of its path and without its disambiguation.
+            return .text(LinkCompletionTools.parse(linkString: destination.path).last?.name ?? "")
         }
     }
     
     mutating func visitSymbolLink(_ symbolLink: SymbolLink) -> XMLNode {
-        guard let destination = symbolLink.destination,
-              let resolved = context.referenceIndex[destination],
-              let node = context.documentationCache[resolved],
-              let symbol = node.semantic as? Symbol
+        guard let destination = symbolLink.destination.flatMap({ URL(string: $0) }),
+              let linkedElement = linkProvider.element(for: destination)
         else {
+            // If this is an unresolved symbol link, try to display only the name of the linked symbol; without the rest of its path and without its disambiguation.
             let name = symbolLink.destination.flatMap { LinkCompletionTools.parse(linkString: $0).last?.name } ?? ""
             return .element(named: "code", children: [.text(name)])
         }
         
-        if case .conceptual(let title) = node.name {
-            // Custom title is same in all languages
-            return .element(
-                named: "a",
-                children: [.text(title)],
-                attributes: ["href": path(to: resolved)]
-            )
+        let children: [XMLNode] = switch linkedElement.names {
+            case .single(let name):
+                switch name {
+                    case .conceptual(let name): [ .text(name) ]
+                    case .symbol(let name):     [ .element(named: "code", children: [.text(name)]) ]
+                }
+                
+            case .languageSpecificSymbol(let namesByLanguageID):
+                namesByLanguageID.sorted(by: \.key).map { languageID, name in
+                    .element(named: "code", children: [.text(name)], attributes: ["class": "\(languageID)-only"])
+                }
         }
         
-        let link = XMLNode.element(
+        return .element(
             named: "a",
-            children: [],
-            attributes: ["href": path(to: resolved)]
+            children: children,
+            attributes: ["href": path(to: linkedElement.path)]
         )
-        
-        for (trait, variant) in symbol.titleVariants.allValues {
-            guard let lang = trait.interfaceLanguage else { continue }
-            
-            var attributes: [String: String] = [:]
-            if symbol.titleVariants.allValues.count > 1 {
-                attributes["class"] = "\(lang)-only"
-            }
-            
-            link.addChild(
-                .element(named: "code", children: [.text(variant)], attributes: attributes)
-            )
-        }
-        return link
-//
-//        let hasMultipleLanguages = Set(symbol.titleVariants.allValues.map(\.variant)).count > 1
-//        guard hasMultipleLanguages else {
-//            // Same spelling in all languages
-//            return .element(
-//                named: "a",
-//                children: [.element(named: "code", children: [symbol.title])],
-//                attributes: ["href": path(to: resolved)]
-//            )
-//        }
-//        
-//        let titles = symbol.titleVariants.map {
-//            
-//        }
-//        
-//        let titles = symbol.titleVariants.allValues
-//        
-//        let spelling: XMLNode = switch node.name {
-//            case .conceptual(let title): .text(title)
-//            case .symbol(let name):
-//        }
-//        
-//        return .element(
-//            named: "a",
-//            children: [spelling],
-//            attributes: ["href": path(to: resolved)]
-//        )
-    }
-    
-    private func path(to destination: ResolvedTopicReference) -> String {
-        (destination.url.relative(to: reference.url)?.path
-            ?? destination.path) + "/index.html"
     }
     
+    private func path(to otherElement: URL) -> String {
+        (otherElement.relative(to: path)?.path ?? otherElement.path)
+    }
     
     func visitImage(_ image: Image) -> XMLNode {
-        guard let source = image.source,
-              let asset = context.resolveAsset(named: source, in: reference)
-        else {
-            return .text("") // ???: What do we return here?
+        guard let asset = image.source.flatMap({ linkProvider.assetNamed($0) }), !asset.images.isEmpty else {
+            return .text("") // ???: What do we return for images that won't display anything?
         }
         
-        let data = asset.data(bestMatching: .init(userInterfaceStyle: .light, displayScale: .double))
+        var children = [XMLNode]()
         
-        let finalImageURL = URL(string: "\(String(repeating: "../", count: reference.pathComponents.count - 1))images/\(reference.bundleID.rawValue)/\(data.url.lastPathComponent)")!
+        func srcAttributes(for images: [Int: URL]) -> [String: String] {
+            switch images.count {
+                case 0: [:]
+                case 1: ["src": path(to: images.first!.value)]
+                default: ["srcset": images.sorted(by: { $0.key > $1.key }) // large scale factors first
+                    .map { scale, url in "\(path(to: url)) \(scale)x" }
+                    .joined(separator: ", ")
+                ]
+            }
+        }
         
-        var attributes = [
-            "src": finalImageURL.path,
+        // Add light and dark sources
+        for (style, images) in asset.images {
+            var attributes = srcAttributes(for: images)
+            attributes["media"] = "(prefers-color-scheme: \(style.rawValue))"
+            children.append(.element(named: "source", attributes: attributes))
+        }
+        
+        var imgAttributes = [
             "decoding": "async",
             "loading": "lazy",
+            // ???: Does the image need a src/srcset for compatibility?
         ]
-        if let scale = data.traitCollection?.displayScale {
-            attributes["srcset"] = "\(finalImageURL.path) \(scale.rawValue)"
-        }
         if let altText = image.altText {
-            attributes["alt"] = altText
+            imgAttributes["alt"] = altText
         }
+        children.append(.element(named: "img", attributes: imgAttributes))
         
-        return .element(named: "picture", children: [
-            .element(named: "img", attributes: attributes)
-        ])
+        return .element(named: "picture", children: children)
     }
     
     func visitCodeBlock(_ codeBlock: CodeBlock) -> XMLNode {
@@ -310,7 +328,7 @@ struct HTMLMarkupRender: MarkupVisitor {
     mutating func visitTable(_ table: Table) -> XMLNode {
         let element = XMLElement(name: "table")
         
-        var renderer = HTMLMarkupRender(reference: reference, context: context)
+        var renderer = self // ???: Do we need to use a copy here?
         
         if !table.head.isEmpty {
             var column = 0
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 57955770b6..e6e73398c2 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -16,11 +16,85 @@ import FoundationXML
 import Markdown
 import SymbolKit
 
+struct ContextLinkProvider: LinkProvider {
+    let reference: ResolvedTopicReference
+    let context: DocumentationContext
+    
+    func element(for url: URL) -> LinkedElement? {
+        guard url.scheme == "doc",
+              let rawBundleID = url.host,
+              let node = context.documentationCache[ResolvedTopicReference(bundleID: .init(rawValue: rawBundleID), path: url.path, fragment: url.fragment, sourceLanguage: .swift /* The reference's language doesn't matter */)]
+        else {
+            return nil
+        }
+        
+        let names: LinkedElement.Names
+        if let symbol = node.semantic as? Symbol,
+           case .symbol(let primaryTitle) = node.name
+        {
+            let titles = symbol.titleVariants.allValues
+            
+            if titles.contains(where: { _, title in title != primaryTitle }) {
+               // This symbol has multiple unique names
+                let titles = [String: String](
+                    titles.map { trait, title in
+                        ((trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift).id, title)
+                    },
+                    uniquingKeysWith: { _, new in new }
+                )
+                
+                names = .languageSpecificSymbol(titles)
+            } else {
+                // There are multiple names, but the're all the same
+                names = .single(.symbol(primaryTitle))
+            }
+        } else {
+            let name: LinkedElement.Name = switch node.name {
+                case .conceptual(let title):   .conceptual(title)
+                case .symbol(name: let title): .symbol(title)
+            }
+            names = .single(name)
+        }
+        
+        return .init(
+            path: node.reference.url.withoutHostAndPortAndScheme().appendingPathComponent("index.html"),
+            names: names
+        )
+    }
+    
+    func assetNamed(_ assetName: String) -> LinkedAsset? {
+        guard let asset = context.resolveAsset(named: assetName, in: reference) else {
+            return nil
+        }
+        
+        var images = [LinkedAsset.ColorStyle: [Int: URL]]()
+        for (traits, url) in asset.variants {
+            let scale = (traits.displayScale ?? .standard).scaleFactor
+            
+            images[traits.userInterfaceStyle == .dark ? .dark : .light, default: [:]][scale] = url
+        }
+        
+        return .init(images: images)
+    }
+    
+}
+
 struct HTMLRenderer {
     let reference: ResolvedTopicReference
     let context: DocumentationContext
     let renderContext: RenderContext
     
+    private let linkProvider: ContextLinkProvider
+    private let filePath: URL
+    
+    init(reference: ResolvedTopicReference, context: DocumentationContext, renderContext: RenderContext) {
+        self.reference = reference
+        self.context = context
+        self.renderContext = renderContext
+        self.linkProvider = .init(reference: reference, context: context)
+        self.filePath = reference.url.withoutHostAndPortAndScheme().appendingPathComponent("index.html")
+    }
+    
     private func path(to destination: ResolvedTopicReference) -> String {
         (destination.url.relative(to: reference.url)?.path
             ?? destination.path) + "/index.html"
@@ -83,7 +157,7 @@ struct HTMLRenderer {
         
         // Abstract
         if let abstract = article.abstract {
-            var renderer = HTMLMarkupRender(reference: reference, context: context)
+            var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
             let paragraph = renderer.visitParagraph(abstract) as! XMLElement
             
             paragraph.addAttribute(
@@ -235,7 +309,7 @@ struct HTMLRenderer {
         
         // Abstract
         if let abstract = symbol.abstract {
-            var renderer = HTMLMarkupRender(reference: reference, context: context)
+            var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
             let paragraph = renderer.visitParagraph(abstract) as! XMLElement
             
             paragraph.addAttribute(
@@ -332,7 +406,7 @@ struct HTMLRenderer {
         
         // Deprecation message
         if let deprecationSummary = symbol.deprecatedSummary {
-            var renderer = HTMLMarkupRender(reference: reference, context: context)
+            var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
             var children: [XMLNode] = [
                 .element(named: "p", children: [.text("Deprecated")], attributes: ["class": "label"])
             ]
@@ -363,7 +437,7 @@ struct HTMLRenderer {
                 )
             }
             
-            var renderer = HTMLMarkupRender(reference: reference, context: context)
+            var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
             
             let list = XMLElement(name: "dl") // list
             section.addChild(list)
@@ -398,7 +472,7 @@ struct HTMLRenderer {
                 )
             }
             
-            var renderer = HTMLMarkupRender(reference: reference, context: context)
+            var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
             
             for markup in returnsSection.content {
                 section.addChild(
@@ -540,7 +614,7 @@ struct HTMLRenderer {
             )
         }
         
-        var renderer = HTMLMarkupRender(reference: reference, context: context)
+        var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
         
         var remaining = discussion.content[...]
         if let heading = discussion.content.first as? Heading, heading.level == 2 {
@@ -593,7 +667,7 @@ struct HTMLRenderer {
     }
     
     private func makeTopicSectionItem(for reference: ResolvedTopicReference) -> XMLNode? {
-        var renderer = HTMLMarkupRender(reference: reference, context: context)
+        var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
         
         if let local = context.documentationCache[reference] {
             let container = XMLNode.element(named: "div")//, attributes: ["class": className])
diff --git a/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift b/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift
index 6f547b7983..a2d7b9f83a 100644
--- a/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift
+++ b/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift
@@ -329,20 +329,79 @@ final class HTMLMarkupRenderTests: XCTestCase {
         )
     }
     
+    func testRelativeLinksToOtherPages() async throws {
+        // Link to article
+        try await assert(
+            rendering: "<doc://com.example.test/documentation/Something/SomeArticle>", // Simulate a link that's been locally resolved already
+            elementToReturn: .init(
+                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/OtherPage/index.html")),
+                names: .single(.conceptual("Some Article Title"))
+            ),
+            prettyFormatted: true,
+            matches: """
+            <p>
+            <a href="../../OtherPage/index.html">Some Article Title</a>
+            </p>
+            """
+        )
+        
+        // Link to single-language symbol
+        try await assert(
+            rendering: "<doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)>", // Simulate a link that's been locally resolved already
+            elementToReturn: .init(
+                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
+                names: .single(.symbol("someMethod(_:_:)"))
+            ),
+            prettyFormatted: true,
+            matches: """
+            <p>
+            <a href="../../SomeClass/someMethod(_:_:)/index.html">
+                <code>someMethod(_:_:)</code>
+            </a>
+            </p>
+            """
+        )
+        
+        // Link to symbol with multiple language representation
+        try await assert(
+            rendering: "<doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)>", // Simulate a link that's been locally resolved already
+            elementToReturn: .init(
+                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
+                names: .languageSpecificSymbol([
+                    SourceLanguage.swift.id : "doSomething(with:and:)",
+                    SourceLanguage.objectiveC.id: "doSomethingWithFirst:andSecond:",
+                ])
+            ),
+            prettyFormatted: true,
+            matches: """
+            <p>
+            <a href="../../SomeClass/someMethod(_:_:)/index.html">
+                <code class="occ-only">doSomethingWithFirst:andSecond:</code>
+                <code class="swift-only">doSomething(with:and:)</code>
+            </a>
+            </p>
+            """
+        )
+    }
+    
+    
     private func assert(
         rendering markdownContent: String,
+        elementToReturn: LinkedElement? = nil,
+        assetToReturn: LinkedAsset? = nil,
         prettyFormatted: Bool = false,
         matches expectedHTML: String,
         file: StaticString = #filePath,
         line: UInt = #line
     ) async throws {
-        let markup = Document(parsing: markdownContent)
-        
-        let (_, context) = try await testBundleAndContext()
-        let reference = ResolvedTopicReference(bundleID: "com.test", path: "/something", sourceLanguage: .swift)
-        var renderer = HTMLMarkupRender(reference: reference, context: context)
-        
-        let htmlNodes = markup.children.map { renderer.visit($0) }
+        var renderer = HTMLMarkupRender(
+            path: try XCTUnwrap(URL(string: "/documentation/Something/ThisPage/index.html"), file: file, line: line),
+            linkProvider: TestLinkProvider(
+                elementToReturn: elementToReturn,
+                assetToReturn: assetToReturn
+            )
+        )
+        let htmlNodes = Document(parsing: markdownContent).children.map { renderer.visit($0) }
         
         let htmlString = if prettyFormatted {
             htmlNodes.map { $0.xmlString(options: [.nodePrettyPrint, .nodeCompactEmptyElement]) }.joined(separator: "\n")
@@ -353,3 +412,15 @@ final class HTMLMarkupRenderTests: XCTestCase {
         XCTAssertEqual(htmlString, expectedHTML, file: file, line: line)
     }
 }
+
+private struct TestLinkProvider: LinkProvider {
+    var elementToReturn: LinkedElement?
+    func element(for path: URL) -> LinkedElement? {
+        elementToReturn
+    }
+    
+    var assetToReturn: LinkedAsset?
+    func assetNamed(_ assetName: String) -> LinkedAsset? {
+        assetToReturn
+    }
+}

From 2d9bd2df7393d26dc5ff78dc677ef65a8d49f6ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sun, 28 Sep 2025 18:01:22 +0200
Subject: [PATCH 04/68] Avoid encoding <source> elements when they're not
 needed

---
 .../Rendering/HTML/HTMLMarkupRender.swift     | 24 +++---
 .../HTML/HTMLMarkupRenderTests.swift          | 80 +++++++++++++++++++
 2 files changed, 94 insertions(+), 10 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift
index 04568d8e95..8c43e0d70a 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift
@@ -261,8 +261,6 @@ struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
             return .text("") // ???: What do we return for images that won't display anything?
         }
         
-        var children = [XMLNode]()
-        
         func srcAttributes(for images: [Int: URL]) -> [String: String] {
             switch images.count {
                 case 0: [:]
@@ -274,21 +272,27 @@ struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
             }
         }
         
-        // Add light and dark sources
-        for (style, images) in asset.images {
-            var attributes = srcAttributes(for: images)
-            attributes["media"] = "(prefers-color-scheme: \(style.rawValue))"
-            children.append(.element(named: "source", attributes: attributes))
-        }
-        
         var imgAttributes = [
             "decoding": "async",
             "loading": "lazy",
-            // ???: Does the image need a src/srcset for compatibility?
         ]
         if let altText = image.altText {
             imgAttributes["alt"] = altText
         }
+        
+        var children = [XMLNode]()
+        if asset.images.count == 1 {
+            // When all image are either dark/light mode, add them directly on the "img" element
+            imgAttributes.merge(srcAttributes(for: asset.images.first!.value), uniquingKeysWith: { _, new in new })
+        } else {
+            // Define a "source" element for each dark/light style
+            for (style, images) in asset.images.sorted(by: { $0.key.rawValue > $1.key.rawValue }) { // order light images before dark images
+                var attributes = srcAttributes(for: images)
+                attributes["media"] = "(prefers-color-scheme: \(style.rawValue))"
+                children.append(.element(named: "source", attributes: attributes))
+            }
+        }
+        
         children.append(.element(named: "img", attributes: imgAttributes))
         
         return .element(named: "picture", children: children)
diff --git a/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift b/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift
index a2d7b9f83a..c5b5657883 100644
--- a/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift
+++ b/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift
@@ -384,6 +384,86 @@ final class HTMLMarkupRenderTests: XCTestCase {
         )
     }
     
+    func testRelativeLinksToImages() async throws {
+        // Only a single image representation
+        try await assert(
+            rendering: "![Some alt text](some-image.png)",
+            assetToReturn: .init(images: [
+                .light: [1: try XCTUnwrap(URL(string: "images/com.test.example/some-image.png"))]
+            ]),
+            prettyFormatted: true,
+            matches: """
+            <p>
+            <picture>
+                <img alt="Some alt text" decoding="async" loading="lazy" src="../../../../../images/com.test.example/some-image.png"/>
+            </picture>
+            </p>
+            """
+        )
+        
+        // Only light mode image representations
+        try await assert(
+            rendering: "![Some alt text](some-image.png)",
+            assetToReturn: .init(images: [
+                .light: [
+                    1: try XCTUnwrap(URL(string: "images/com.test.example/some-image.png")),
+                    2: try XCTUnwrap(URL(string: "images/com.test.example/some-image@2x.png")),
+                ]
+            ]),
+            prettyFormatted: true,
+            matches: """
+            <p>
+            <picture>
+                <img alt="Some alt text" decoding="async" loading="lazy" srcset="../../../../../images/com.test.example/some-image@2x.png 2x, ../../../../../images/com.test.example/some-image.png 1x"/>
+            </picture>
+            </p>
+            """
+        )
+        
+        // Only a single scale factor
+        try await assert(
+            rendering: "![Some alt text](some-image.png)",
+            assetToReturn: .init(images: [
+                .light: [1: try XCTUnwrap(URL(string: "images/com.test.example/some-image.png"))],
+                .dark:  [1: try XCTUnwrap(URL(string: "images/com.test.example/some-image~dark.png"))],
+            ]),
+            prettyFormatted: true,
+            matches: """
+            <p>
+            <picture>
+                <source media="(prefers-color-scheme: light)" src="../../../../../images/com.test.example/some-image.png"/>
+                <source media="(prefers-color-scheme: dark)" src="../../../../../images/com.test.example/some-image~dark.png"/>
+                <img alt="Some alt text" decoding="async" loading="lazy"/>
+            </picture>
+            </p>
+            """
+        )
+        
+        // Multiple styles and scale factors
+        try await assert(
+            rendering: "![Some alt text](some-image.png)",
+            assetToReturn: .init(images: [
+                .light: [
+                    1: try XCTUnwrap(URL(string: "images/com.test.example/some-image.png")),
+                    2: try XCTUnwrap(URL(string: "images/com.test.example/some-image@2x.png")),
+                ],
+                .dark: [
+                    1: try XCTUnwrap(URL(string: "images/com.test.example/some-image~dark.png")),
+                    2: try XCTUnwrap(URL(string: "images/com.test.example/some-image~dark@2x.png")),
+                ],
+            ]),
+            prettyFormatted: true,
+            matches: """
+            <p>
+            <picture>
+                <source media="(prefers-color-scheme: light)" srcset="../../../../../images/com.test.example/some-image@2x.png 2x, ../../../../../images/com.test.example/some-image.png 1x"/>
+                <source media="(prefers-color-scheme: dark)" srcset="../../../../../images/com.test.example/some-image~dark@2x.png 2x, ../../../../../images/com.test.example/some-image~dark.png 1x"/>
+                <img alt="Some alt text" decoding="async" loading="lazy"/>
+            </picture>
+            </p>
+            """
+        )
+    }
     
     private func assert(
         rendering markdownContent: String,

From 654a1189b7bc9cfda16ad63a6f0a95f79439c6dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sun, 28 Sep 2025 18:36:35 +0200
Subject: [PATCH 05/68] Move core HTML rendering to its own target

---
 Package.swift                                 |  19 ++++
 .../MarkupRenderer.swift}                     | 102 +++++++++++++-----
 Sources/HTML/XMLNode+element.swift            |  42 ++++++++
 .../Model/Rendering/HTML/HTMLRenderer.swift   |  56 +++-------
 .../MarkupRendererTests.swift}                |   9 +-
 5 files changed, 156 insertions(+), 72 deletions(-)
 rename Sources/{SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift => HTML/MarkupRenderer.swift} (83%)
 create mode 100644 Sources/HTML/XMLNode+element.swift
 rename Tests/{SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift => HTMLTests/MarkupRendererTests.swift} (98%)

diff --git a/Package.swift b/Package.swift
index f954d00903..53fc665579 100644
--- a/Package.swift
+++ b/Package.swift
@@ -43,6 +43,7 @@ let package = Package(
         .target(
             name: "SwiftDocC",
             dependencies: [
+                .target(name: "HTML"),
                 .product(name: "Markdown", package: "swift-markdown"),
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
                 .product(name: "CLMDB", package: "swift-lmdb"),
@@ -88,6 +89,24 @@ let package = Package(
             swiftSettings: swiftSettings
         ),
         
+        .target(
+            name: "HTML",
+            dependencies: [
+                .product(name: "Markdown", package: "swift-markdown"),
+            ],
+            swiftSettings: swiftSettings
+        ),
+        .testTarget(
+            name: "HTMLTests",
+            dependencies: [
+                .target(name: "HTML"),
+                .target(name: "SwiftDocC"),
+                .product(name: "Markdown", package: "swift-markdown"),
+                .target(name: "SwiftDocCTestUtilities"),
+            ],
+            swiftSettings: swiftSettings
+        ),
+        
         // Test utility library
         .target(
             name: "SwiftDocCTestUtilities",
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift b/Sources/HTML/MarkupRenderer.swift
similarity index 83%
rename from Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift
rename to Sources/HTML/MarkupRenderer.swift
index 8c43e0d70a..3e5039d8e2 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLMarkupRender.swift
+++ b/Sources/HTML/MarkupRenderer.swift
@@ -8,11 +8,11 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-import Foundation
+package import Foundation
 import Markdown
 
 /// A type that provides information about other pages, and on-page elements, that the rendered page references.
-protocol LinkProvider {
+package protocol LinkProvider {
     /// Provide information about another page or on-page element, or `nil` if the other page can't be found.
     func element(for path: URL) -> LinkedElement?
     
@@ -20,15 +20,21 @@ protocol LinkProvider {
     func assetNamed(_ assetName: String) -> LinkedAsset?
 }
 
-struct LinkedElement {
+package struct LinkedElement {
     /// The path within the output archive to the linked element.
-    var path: URL
+    package var path: URL
     /// The names of the linked element.
     ///
     /// Articles, headings, tutorials, and similar pages have a ``Names/single/conceptual(_:)`` name.
-    ///
-    var names: Names
-    enum Names {
+    /// Symbols can either have a ``Names/single/symbol(_:)`` name or have different names for each language representation (``Names/languageSpecificSymbol``).
+    package var names: Names
+    
+    package init(path: URL, names: Names) {
+        self.path = path
+        self.names = names
+    }
+    
+    package enum Names {
         /// This element has the same name in all language representations
         case single(Name)
         /// This element is a symbol with different names in different languages.
@@ -36,7 +42,7 @@ struct LinkedElement {
         /// Because `@DisplayName` applies to all language representations, these language specific names are always the symbol's subheading declaration and should display in a monospaced font.
         case languageSpecificSymbol([String /* Language ID */: String])
     }
-    enum Name {
+    package enum Name {
         /// The name refers to an article, heading, or custom `@DisplayName` and should display as regular text.
         case conceptual(String)
         /// The name refers to a symbol's subheading declaration and should display in a monospaced font.
@@ -44,22 +50,26 @@ struct LinkedElement {
     }
 }
 
-struct LinkedAsset {
+package struct LinkedAsset {
     /// The path within the output archive to each image variant, by their light/dark style.
-    var images: [ColorStyle: [Int /* display scale*/: URL]]
+    package var images: [ColorStyle: [Int /* display scale*/: URL]]
     
-    enum ColorStyle: String {
+    package init(images: [ColorStyle : [Int : URL]]) {
+        self.images = images
+    }
+    
+    package enum ColorStyle: String {
         case light, dark
     }
 }
 
-struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
+package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
     /// The path within the output archive to the page that this renderer renders.
     let path: URL
     /// A type that provides information about other pages that the rendered page references.
     let linkProvider: Provider
     
-    init(path: URL, linkProvider: Provider) {
+    package init(path: URL, linkProvider: Provider) {
         self.path = path
         self.linkProvider = linkProvider
     }
@@ -70,7 +80,6 @@ struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
     
     //
     
-    
     mutating func visitParagraph(_ paragraph: Paragraph) -> XMLNode {
         .element(named: "p", children: visit(paragraph.children))
     }
@@ -172,7 +181,7 @@ struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
             return .text("")
         }
         
-        if link.hasChildren {
+        if link.childCount > 0 {
             var customTitle = [XMLNode]()
             for child in link.inlineChildren {
                 customTitle.append(visit(child))
@@ -200,7 +209,7 @@ struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
                     }
                     
                 case .languageSpecificSymbol(let namesByLanguageID):
-                    namesByLanguageID.sorted(by: \.key).map { languageID, name in
+                    namesByLanguageID.sorted(by: { $0.key < $1.key }).map { languageID, name in
                             .element(named: "code", children: [.text(name)], attributes: ["class": "\(languageID)-only"])
                     }
             }
@@ -218,8 +227,10 @@ struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
                 attributes: ["href": destination.absoluteString]
             )
         } else {
-            // If this is an unresolved documentation link, try to display only the name of the linked symbol; without the rest of its path and without its disambiguation.
-            return .text(LinkCompletionTools.parse(linkString: destination.path).last?.name ?? "")
+            // FIXME: Add this to the protocol
+//            // If this is an unresolved documentation link, try to display only the name of the linked symbol; without the rest of its path and without its disambiguation.
+//            return .text(LinkCompletionTools.parse(linkString: destination.path).last?.name ?? "")
+            return .text(destination.path)
         }
     }
     
@@ -227,9 +238,11 @@ struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
         guard let destination = symbolLink.destination.flatMap({ URL(string: $0) }),
               let linkedElement = linkProvider.element(for: destination)
         else {
-            // If this is an unresolved symbol link, try to display only the name of the linked symbol; without the rest of its path and without its disambiguation.
-            let name = symbolLink.destination.flatMap { LinkCompletionTools.parse(linkString: $0).last?.name } ?? ""
-            return .element(named: "code", children: [.text(name)])
+            // FIXME: Add this to the protocol
+//            // If this is an unresolved symbol link, try to display only the name of the linked symbol; without the rest of its path and without its disambiguation.
+//            let name = symbolLink.destination.flatMap { LinkCompletionTools.parse(linkString: $0).last?.name } ?? ""
+//            return .element(named: "code", children: [.text(name)])
+            return .element(named: "code", children: [.text(symbolLink.destination ?? "")])
         }
         
         let children: [XMLNode] = switch linkedElement.names {
@@ -240,7 +253,7 @@ struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
                 }
                 
             case .languageSpecificSymbol(let namesByLanguageID):
-                namesByLanguageID.sorted(by: \.key).map { languageID, name in
+                namesByLanguageID.sorted(by: { $0.key < $1.key }).map { languageID, name in
                     .element(named: "code", children: [.text(name)], attributes: ["class": "\(languageID)-only"])
                 }
         }
@@ -252,8 +265,21 @@ struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
         )
     }
     
-    private func path(to otherElement: URL) -> String {
-        (otherElement.relative(to: path)?.path ?? otherElement.path)
+    private func path(to other: URL) -> String {
+        let from = path
+        let to   = other
+        
+        guard from != to else { return to.withoutHostAndPortAndScheme().absoluteString }
+
+        // To be able to compare the components of the two URLs they both need to be absolute and standardized.
+        let fromComponents = from.absoluteURL.standardizedFileURL.pathComponents
+        let toComponents   = to.absoluteURL.standardizedFileURL.pathComponents
+
+        let commonPrefixLength = Array(zip(fromComponents, toComponents).prefix { lhs, rhs in lhs == rhs }).count
+
+        let relativeComponents = repeatElement("..", count: fromComponents.count - commonPrefixLength) + toComponents.dropFirst(commonPrefixLength)
+       
+        return relativeComponents.joined(separator: "/")
     }
     
     func visitImage(_ image: Image) -> XMLNode {
@@ -473,12 +499,14 @@ struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
         return children
     }
     
-    // MARK: Blah
+    // MARK: Directives
     
     func visitBlockDirective(_ blockDirective: BlockDirective) -> XMLNode {
         .text("") // Do nothing for now
     }
     
+    // FIXME: It would be nice if DocC processed these before rendering
+    
     mutating func visitDoxygenNote(_ doxygenNote: DoxygenNote) -> XMLNode {
         .element(named: "p", children: visit(doxygenNote.children))
     }
@@ -497,6 +525,28 @@ struct HTMLMarkupRender<Provider: LinkProvider>: MarkupVisitor {
     
     mutating func visitDoxygenDiscussion(_ doxygenDiscussion: DoxygenDiscussion) -> XMLNode {
         .element(named: "p", children: visit(doxygenDiscussion.children))
-        
+    }
+}
+
+// MARK: Helpers
+
+private extension Image {
+    /// The first element's text if it is a `Markdown.Text` element, otherwise `nil`.
+    var altText: String? {
+        guard let firstText = child(at: 0) as? Text else {
+            return nil
+        }
+        return firstText.string
+    }
+}
+
+private extension URL {
+    /// Returns a copy of the URL without the scheme, host, and port components.
+    func withoutHostAndPortAndScheme() -> URL {
+        var components = URLComponents(url: self, resolvingAgainstBaseURL: false)!
+        components.scheme = nil
+        components.host = nil
+        components.port = nil
+        return components.url!
     }
 }
diff --git a/Sources/HTML/XMLNode+element.swift b/Sources/HTML/XMLNode+element.swift
new file mode 100644
index 0000000000..6c572de670
--- /dev/null
+++ b/Sources/HTML/XMLNode+element.swift
@@ -0,0 +1,42 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+package import Foundation
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+package import FoundationXML
+#endif
+
+extension XMLNode {
+    package static func element(
+        named name: String,
+        children: [XMLNode]? = nil,
+        attributes: [String: String]? = nil,
+    ) -> XMLElement {
+        let attributeNodes: [XMLNode]?
+        if let attributes, !attributes.isEmpty {
+            attributeNodes = attributes.sorted(by: { $0.key < $1.key }).map {
+                XMLNode.attribute(withName: $0.key, stringValue: $0.value) as! XMLNode
+            }
+        } else {
+            attributeNodes = nil
+        }
+        
+        return XMLNode.element(
+            withName: name,
+            children: children,
+            attributes: attributeNodes
+        ) as! XMLElement
+    }
+    
+    package static func text(_ value: some StringProtocol) -> XMLNode {
+        XMLNode.text(withStringValue: String(value)) as! XMLNode
+    }
+}
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index e6e73398c2..b99a1c86e7 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -13,14 +13,15 @@ import Foundation
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 import FoundationXML
 #endif
+import HTML
 import Markdown
 import SymbolKit
 
-struct ContextLinkProvider: LinkProvider {
+struct ContextLinkProvider: HTML.LinkProvider {
     let reference: ResolvedTopicReference
     let context: DocumentationContext
     
-    func element(for url: URL) -> LinkedElement? {
+    func element(for url: URL) -> HTML.LinkedElement? {
         guard url.scheme == "doc",
               let rawBundleID = url.host,
               let node = context.documentationCache[ResolvedTopicReference(bundleID: .init(rawValue: rawBundleID), path: url.path, fragment: url.fragment, sourceLanguage: .swift /* The reference's language doesn't matter */)]
@@ -28,7 +29,7 @@ struct ContextLinkProvider: LinkProvider {
             return nil
         }
         
-        let names: LinkedElement.Names
+        let names: HTML.LinkedElement.Names
         if let symbol = node.semantic as? Symbol,
            case .symbol(let primaryTitle) = node.name
         {
@@ -49,7 +50,7 @@ struct ContextLinkProvider: LinkProvider {
                 names = .single(.symbol(primaryTitle))
             }
         } else {
-            let name: LinkedElement.Name = switch node.name {
+            let name: HTML.LinkedElement.Name = switch node.name {
                 case .conceptual(let title):   .conceptual(title)
                 case .symbol(name: let title): .symbol(title)
             }
@@ -62,12 +63,12 @@ struct ContextLinkProvider: LinkProvider {
         )
     }
     
-    func assetNamed(_ assetName: String) -> LinkedAsset? {
+    func assetNamed(_ assetName: String) -> HTML.LinkedAsset? {
         guard let asset = context.resolveAsset(named: assetName, in: reference) else {
             return nil
         }
         
-        var images = [LinkedAsset.ColorStyle: [Int: URL]]()
+        var images = [HTML.LinkedAsset.ColorStyle: [Int: URL]]()
         for (traits, url) in asset.variants {
             let scale = (traits.displayScale ?? .standard).scaleFactor
             
@@ -76,7 +77,6 @@ struct ContextLinkProvider: LinkProvider {
         
         return .init(images: images)
     }
-    
 }
 
 struct HTMLRenderer {
@@ -157,7 +157,7 @@ struct HTMLRenderer {
         
         // Abstract
         if let abstract = article.abstract {
-            var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
+            var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
             let paragraph = renderer.visitParagraph(abstract) as! XMLElement
             
             paragraph.addAttribute(
@@ -309,7 +309,7 @@ struct HTMLRenderer {
         
         // Abstract
         if let abstract = symbol.abstract {
-            var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
+            var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
             let paragraph = renderer.visitParagraph(abstract) as! XMLElement
             
             paragraph.addAttribute(
@@ -406,7 +406,7 @@ struct HTMLRenderer {
         
         // Deprecation message
         if let deprecationSummary = symbol.deprecatedSummary {
-            var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
+            var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
             var children: [XMLNode] = [
                 .element(named: "p", children: [.text("Deprecated")], attributes: ["class": "label"])
             ]
@@ -437,7 +437,7 @@ struct HTMLRenderer {
                 )
             }
             
-            var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
+            var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
             
             let list = XMLElement(name: "dl") // list
             section.addChild(list)
@@ -472,7 +472,7 @@ struct HTMLRenderer {
                 )
             }
             
-            var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
+            var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
             
             for markup in returnsSection.content {
                 section.addChild(
@@ -614,7 +614,7 @@ struct HTMLRenderer {
             )
         }
         
-        var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
+        var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
         
         var remaining = discussion.content[...]
         if let heading = discussion.content.first as? Heading, heading.level == 2 {
@@ -667,7 +667,7 @@ struct HTMLRenderer {
     }
     
     private func makeTopicSectionItem(for reference: ResolvedTopicReference) -> XMLNode? {
-        var renderer = HTMLMarkupRender(path: filePath, linkProvider: linkProvider)
+        var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
         
         if let local = context.documentationCache[reference] {
             let container = XMLNode.element(named: "div")//, attributes: ["class": className])
@@ -849,34 +849,6 @@ struct HTMLRenderer {
     
 }
 
-// FIXME: Move these extensions to a file or maybe write our own html nodes
-extension XMLNode {
-    static func element(
-        named name: String,
-        children: [XMLNode]? = nil,
-        attributes: [String: String]? = nil,
-    ) -> XMLElement {
-        let attributeNodes: [XMLNode]?
-        if let attributes, !attributes.isEmpty {
-            attributeNodes = attributes.sorted(by: \.key).map {
-                XMLNode.attribute(withName: $0.key, stringValue: $0.value) as! XMLNode
-            }
-        } else {
-            attributeNodes = nil
-        }
-        
-        return XMLNode.element(
-            withName: name,
-            children: children,
-            attributes: attributeNodes
-        ) as! XMLElement
-    }
-    
-    static func text(_ value: some StringProtocol) -> XMLNode {
-        XMLNode.text(withStringValue: String(value)) as! XMLNode
-    }
-}
-
 extension XMLNode {
     static func metaElement(name: String, content: String) -> XMLElement {
         .element(named: "meta", attributes: ["name": name, "content": content])
diff --git a/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift b/Tests/HTMLTests/MarkupRendererTests.swift
similarity index 98%
rename from Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift
rename to Tests/HTMLTests/MarkupRendererTests.swift
index c5b5657883..85815cc5b2 100644
--- a/Tests/SwiftDocCTests/HTML/HTMLMarkupRenderTests.swift
+++ b/Tests/HTMLTests/MarkupRendererTests.swift
@@ -10,10 +10,11 @@
 
 import Foundation
 import XCTest
+import HTML
 @testable import SwiftDocC
 import Markdown
 
-final class HTMLMarkupRenderTests: XCTestCase {
+final class MarkupRendererTests: XCTestCase {
  
     func testRenderParagraphsWithFormattedText() async throws {
         try await assert(
@@ -334,13 +335,13 @@ final class HTMLMarkupRenderTests: XCTestCase {
         try await assert(
             rendering: "<doc://com.example.test/documentation/Something/SomeArticle>", // Simulate a link that's been locally resolved already
             elementToReturn: .init(
-                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/OtherPage/index.html")),
+                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeArticle/index.html")),
                 names: .single(.conceptual("Some Article Title"))
             ),
             prettyFormatted: true,
             matches: """
             <p>
-            <a href="../../OtherPage/index.html">Some Article Title</a>
+            <a href="../../SomeArticle/index.html">Some Article Title</a>
             </p>
             """
         )
@@ -474,7 +475,7 @@ final class HTMLMarkupRenderTests: XCTestCase {
         file: StaticString = #filePath,
         line: UInt = #line
     ) async throws {
-        var renderer = HTMLMarkupRender(
+        var renderer = MarkupRenderer(
             path: try XCTUnwrap(URL(string: "/documentation/Something/ThisPage/index.html"), file: file, line: line),
             linkProvider: TestLinkProvider(
                 elementToReturn: elementToReturn,

From f5eda36bee5812089b8ec316f1b3283eeb2e9dfe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sun, 28 Sep 2025 21:30:55 +0200
Subject: [PATCH 06/68] Add helper to insert word breaks into symbol names

---
 Sources/HTML/MarkupRenderer+WordBreak.swift   | 74 ++++++++++++++++++
 .../MarkupRenderer+WordBreakTests.swift       | 78 +++++++++++++++++++
 Tests/HTMLTests/MarkupRendererTests.swift     |  2 +-
 3 files changed, 153 insertions(+), 1 deletion(-)
 create mode 100644 Sources/HTML/MarkupRenderer+WordBreak.swift
 create mode 100644 Tests/HTMLTests/MarkupRenderer+WordBreakTests.swift

diff --git a/Sources/HTML/MarkupRenderer+WordBreak.swift b/Sources/HTML/MarkupRenderer+WordBreak.swift
new file mode 100644
index 0000000000..7c4ef1ee87
--- /dev/null
+++ b/Sources/HTML/MarkupRenderer+WordBreak.swift
@@ -0,0 +1,74 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+package import Foundation
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+package import FoundationXML
+#endif
+
+extension MarkupRenderer {
+    /// Inserts `<wbr/>` elements into a symbol name so that it can wrap better on the rendered page.
+    ///
+    /// For example, a method call like this (below), inserts line break elements at the highlighted locations:
+    ///
+    ///     do Something< Generic>( with First: and Second:)
+    ///       △          ▲         ▲    △      ▲   △
+    ///       │          ╰─────────┴───╴│╶─────┴──╴│╶─── after syntax
+    ///       ╰─────────────────────────┴──────────┴──── between words
+    package static func wordBreak(symbolName: String) -> [XMLNode] {
+        var result: [XMLNode] = []
+        
+        let utf8View = symbolName.utf8
+        let indices = utf8View.indices
+        
+        var fromIndex = utf8View.startIndex
+        for (index, previousIndex) in zip(indices.dropFirst(), indices) {
+            let previous = utf8View[previousIndex]
+            let current  = utf8View[index]
+            
+            guard previous.isSyntaxSeparator      && !current.isSyntaxSeparator
+               || previous.isLowercaseASCIILetter && current.isUppercaseASCIILetter
+            else {
+                continue
+            }
+            
+            result.append(.text(String(utf8View[fromIndex ..< index])!))
+            if index < utf8View.endIndex {
+                result.append(.element(named: "wbr"))
+            }
+            fromIndex = index
+        }
+        
+        if fromIndex < utf8View.endIndex {
+            result.append(.text(String(utf8View[fromIndex...])!))
+        }
+        
+        return result
+    }
+}
+
+private extension UTF8.CodeUnit {
+    // Because this is only for line breaks, limiting support to ASCII is probably acceptable
+    var isUppercaseASCIILetter: Bool {
+        UTF8.CodeUnit(ascii: "A") <= self && self <= UTF8.CodeUnit(ascii: "Z")
+    }
+    var isLowercaseASCIILetter: Bool {
+        UTF8.CodeUnit(ascii: "a") <= self && self <= UTF8.CodeUnit(ascii: "z")
+    }
+    
+    var isSyntaxSeparator: Bool {
+        return self == UTF8.CodeUnit(ascii: ":")
+            || self == UTF8.CodeUnit(ascii: "(")
+            || self == UTF8.CodeUnit(ascii: ")")
+            || self == UTF8.CodeUnit(ascii: "<")
+            || self == UTF8.CodeUnit(ascii: ">")
+    }
+}
diff --git a/Tests/HTMLTests/MarkupRenderer+WordBreakTests.swift b/Tests/HTMLTests/MarkupRenderer+WordBreakTests.swift
new file mode 100644
index 0000000000..00e7b4a165
--- /dev/null
+++ b/Tests/HTMLTests/MarkupRenderer+WordBreakTests.swift
@@ -0,0 +1,78 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+import XCTest
+import HTML
+
+final class MarkupRenderer_WordBreakTests: XCTestCase {
+    func testWordBreaks() {
+        assertWordBreaks(for: "doSomething<Generic>(withFirst:andSecond:)", matches: """
+        do
+        <wbr/>
+        Something&lt;
+        <wbr/>
+        Generic&gt;(
+        <wbr/>
+        with
+        <wbr/>
+        First:
+        <wbr/>
+        and
+        <wbr/>
+        Second:)
+        """)
+        
+        assertWordBreaks(for: "doSomethingWithFirst:andSecond:", matches: """
+        do
+        <wbr/>
+        Something
+        <wbr/>
+        With
+        <wbr/>
+        First:
+        <wbr/>
+        and
+        <wbr/>
+        Second:
+        """)
+        
+        assertWordBreaks(for: "SomeVeryLongClassName", matches: """
+        Some
+        <wbr/>
+        Very
+        <wbr/>
+        Long
+        <wbr/>
+        Class
+        <wbr/>
+        Name
+        """)
+        
+        assertWordBreaks(for: "TLASomeClass", matches: """
+        TLASome
+        <wbr/>
+        Class
+        """)
+    }
+    
+    private func assertWordBreaks(
+        for symbolName: String,
+        matches expectedHTML: String,
+        file: StaticString = #filePath,
+        line: UInt = #line
+    ) {
+        let withWordBreaks = MarkupRenderer<TestLinkProvider>.wordBreak(symbolName: symbolName)
+            .map { $0.xmlString(options: [.nodePrettyPrint, .nodeCompactEmptyElement] )}
+            .joined(separator: "\n")
+        
+        XCTAssertEqual(withWordBreaks, expectedHTML, file: file, line: line)
+    }
+}
diff --git a/Tests/HTMLTests/MarkupRendererTests.swift b/Tests/HTMLTests/MarkupRendererTests.swift
index 85815cc5b2..8fe3868967 100644
--- a/Tests/HTMLTests/MarkupRendererTests.swift
+++ b/Tests/HTMLTests/MarkupRendererTests.swift
@@ -494,7 +494,7 @@ final class MarkupRendererTests: XCTestCase {
     }
 }
 
-private struct TestLinkProvider: LinkProvider {
+struct TestLinkProvider: LinkProvider {
     var elementToReturn: LinkedElement?
     func element(for path: URL) -> LinkedElement? {
         elementToReturn

From 0e1d6cd76a01ecf0817f2fe6f8084684d566b789 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 4 Oct 2025 14:09:16 +0200
Subject: [PATCH 07/68] Insert word breaks in symbol titles for better wrapping

---
 Sources/HTML/MarkupRenderer.swift             | 14 ++++--
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 49 +++++--------------
 Tests/HTMLTests/MarkupRendererTests.swift     | 47 ++++++++++++++++--
 3 files changed, 66 insertions(+), 44 deletions(-)

diff --git a/Sources/HTML/MarkupRenderer.swift b/Sources/HTML/MarkupRenderer.swift
index 3e5039d8e2..53de05f941 100644
--- a/Sources/HTML/MarkupRenderer.swift
+++ b/Sources/HTML/MarkupRenderer.swift
@@ -184,7 +184,11 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
         if link.childCount > 0 {
             var customTitle = [XMLNode]()
             for child in link.inlineChildren {
-                customTitle.append(visit(child))
+                if let code = child as? InlineCode {
+                    customTitle.append(.element(named: "code", children: Self.wordBreak(symbolName: code.code)))
+                } else {
+                    customTitle.append(visit(child))
+                }
             }
             
             if customTitle != [.text(destination.absoluteString)] {
@@ -205,12 +209,12 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
                 case .single(let name):
                     switch name {
                         case .conceptual(let name): [ .text(name) ]
-                        case .symbol(let name):     [ .element(named: "code", children: [.text(name)]) ]
+                        case .symbol(let name):     [ .element(named: "code", children: Self.wordBreak(symbolName: name)) ]
                     }
                     
                 case .languageSpecificSymbol(let namesByLanguageID):
                     namesByLanguageID.sorted(by: { $0.key < $1.key }).map { languageID, name in
-                            .element(named: "code", children: [.text(name)], attributes: ["class": "\(languageID)-only"])
+                            .element(named: "code", children: Self.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
                     }
             }
             
@@ -249,12 +253,12 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
             case .single(let name):
                 switch name {
                     case .conceptual(let name): [ .text(name) ]
-                    case .symbol(let name):     [ .element(named: "code", children: [.text(name)]) ]
+                    case .symbol(let name):     [ .element(named: "code", children: Self.wordBreak(symbolName: name)) ]
                 }
                 
             case .languageSpecificSymbol(let namesByLanguageID):
                 namesByLanguageID.sorted(by: { $0.key < $1.key }).map { languageID, name in
-                    .element(named: "code", children: [.text(name)], attributes: ["class": "\(languageID)-only"])
+                    .element(named: "code", children: Self.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
                 }
         }
         
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index b99a1c86e7..83e6053985 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -79,6 +79,8 @@ struct ContextLinkProvider: HTML.LinkProvider {
     }
 }
 
+private typealias MarkupRenderer = HTML.MarkupRenderer<ContextLinkProvider>
+
 struct HTMLRenderer {
     let reference: ResolvedTopicReference
     let context: DocumentationContext
@@ -150,14 +152,14 @@ struct HTMLRenderer {
         hero.addChild(
             .element(
                 named: "h1",
-                children: [.text(node.name.plainText.replacingOccurrences(of: ":", with: ":\u{82}"))], // support breaking on parameters
+                children: [.text(node.name.plainText)],
                 attributes: ["class": "title"]
             )
         )
         
         // Abstract
         if let abstract = article.abstract {
-            var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
+            var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
             let paragraph = renderer.visitParagraph(abstract) as! XMLElement
             
             paragraph.addAttribute(
@@ -194,6 +196,7 @@ struct HTMLRenderer {
             separateCurationIfNeeded()
             articleElement.addChild(makeGroupedSection(topics))
         }
+        // Articles don't have automatic topic sections
         
         // See Also
         if let seeAlso = article.seeAlso {
@@ -210,8 +213,6 @@ struct HTMLRenderer {
                     .selfReferencingHeader(title: title)
                 )
             }
-            
-            
             if let heading = taskGroup.title {
                 section.addChild(
                     .selfReferencingHeader(level: 3, title: heading)
@@ -301,7 +302,7 @@ struct HTMLRenderer {
             hero.addChild(
                 .element(
                     named: "h1",
-                    children: makeWordBreakFor(title: variant),
+                    children: MarkupRenderer.wordBreak(symbolName: variant),
                     attributes: attributes
                 )
             )
@@ -309,7 +310,7 @@ struct HTMLRenderer {
         
         // Abstract
         if let abstract = symbol.abstract {
-            var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
+            var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
             let paragraph = renderer.visitParagraph(abstract) as! XMLElement
             
             paragraph.addAttribute(
@@ -406,7 +407,7 @@ struct HTMLRenderer {
         
         // Deprecation message
         if let deprecationSummary = symbol.deprecatedSummary {
-            var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
+            var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
             var children: [XMLNode] = [
                 .element(named: "p", children: [.text("Deprecated")], attributes: ["class": "label"])
             ]
@@ -437,7 +438,7 @@ struct HTMLRenderer {
                 )
             }
             
-            var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
+            var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
             
             let list = XMLElement(name: "dl") // list
             section.addChild(list)
@@ -472,7 +473,7 @@ struct HTMLRenderer {
                 )
             }
             
-            var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
+            var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
             
             for markup in returnsSection.content {
                 section.addChild(
@@ -580,30 +581,6 @@ struct HTMLRenderer {
         return makePage(main: main, title: symbol.title, plainDescription: symbol.abstract?.plainText)
     }
     
-    private func makeWordBreakFor(title: String) -> [XMLNode] {
-        
-        var result: [XMLNode] = []
-        
-        var remaining = title[...]
-        
-        while let splitIndex = remaining.firstIndex(where: { $0 == ":" || $0 == "(" || $0 == ")" }) {
-            var part = remaining[...splitIndex]
-            if part.first?.isWhitespace == true {
-                part = part.dropFirst()
-            }
-            result.append(.text(part))
-            
-            remaining = remaining[splitIndex...].dropFirst()
-            if !remaining.isEmpty {
-                result.append(.element(named: "wbr"))
-            }
-        }
-        
-        result.append(.text(remaining))
-        
-        return result
-    }
-    
     private func makeDiscussion(_ discussion: DiscussionSection, isSymbol: Bool) -> XMLNode {
         let section = XMLElement(name: "section")
         
@@ -614,7 +591,7 @@ struct HTMLRenderer {
             )
         }
         
-        var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
+        var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
         
         var remaining = discussion.content[...]
         if let heading = discussion.content.first as? Heading, heading.level == 2 {
@@ -667,7 +644,7 @@ struct HTMLRenderer {
     }
     
     private func makeTopicSectionItem(for reference: ResolvedTopicReference) -> XMLNode? {
-        var renderer = HTML.MarkupRenderer(path: filePath, linkProvider: linkProvider)
+        var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
         
         if let local = context.documentationCache[reference] {
             let container = XMLNode.element(named: "div")//, attributes: ["class": className])
@@ -701,7 +678,7 @@ struct HTMLRenderer {
                                             "decorator"
                                     }
                                     
-                                    return .element(named: "span", children: makeWordBreakFor(title: fragment.spelling), attributes: ["class": className])
+                                    return .element(named: "span", children: MarkupRenderer.wordBreak(symbolName: fragment.spelling), attributes: ["class": className])
                                 },
                                 attributes: ["class": "\(lang)-only"]
                             )
diff --git a/Tests/HTMLTests/MarkupRendererTests.swift b/Tests/HTMLTests/MarkupRendererTests.swift
index 8fe3868967..ce9d0b9b84 100644
--- a/Tests/HTMLTests/MarkupRendererTests.swift
+++ b/Tests/HTMLTests/MarkupRendererTests.swift
@@ -357,7 +357,10 @@ final class MarkupRendererTests: XCTestCase {
             matches: """
             <p>
             <a href="../../SomeClass/someMethod(_:_:)/index.html">
-                <code>someMethod(_:_:)</code>
+                <code>some<wbr/>
+                    Method(<wbr/>
+                    _:<wbr/>
+                    _:)</code>
             </a>
             </p>
             """
@@ -377,12 +380,50 @@ final class MarkupRendererTests: XCTestCase {
             matches: """
             <p>
             <a href="../../SomeClass/someMethod(_:_:)/index.html">
-                <code class="occ-only">doSomethingWithFirst:andSecond:</code>
-                <code class="swift-only">doSomething(with:and:)</code>
+                <code class="occ-only">do<wbr/>
+                    Something<wbr/>
+                    With<wbr/>
+                    First:<wbr/>
+                    and<wbr/>
+                    Second:</code>
+                <code class="swift-only">do<wbr/>
+                    Something(<wbr/>
+                    with:<wbr/>
+                    and:)</code>
             </a>
             </p>
             """
         )
+        
+        // Link with custom title
+        try await assert(
+            rendering: "[Custom _formatted_ title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
+            elementToReturn: .init(
+                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
+                names: .languageSpecificSymbol([
+                    SourceLanguage.swift.id : "doSomething(with:and:)",
+                    SourceLanguage.objectiveC.id: "doSomethingWithFirst:andSecond:",
+                ])
+            ),
+            matches: """
+            <p><a href="../../SomeClass/someMethod(_:_:)/index.html">Custom <i>formatted</i> title</a></p>
+            """
+        )
+        
+        // Link with custom symbol-like title
+        try await assert(
+            rendering: "[Some `CustomSymbolName` title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
+            elementToReturn: .init(
+                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
+                names: .languageSpecificSymbol([
+                    SourceLanguage.swift.id : "doSomething(with:and:)",
+                    SourceLanguage.objectiveC.id: "doSomethingWithFirst:andSecond:",
+                ])
+            ),
+            matches: """
+            <p><a href="../../SomeClass/someMethod(_:_:)/index.html">Some <code>Custom<wbr/>Symbol<wbr/>Name</code> title</a></p>
+            """
+        )
     }
     
     func testRelativeLinksToImages() async throws {

From 661f585ed1116557982121f2e9022b5481d553c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 4 Oct 2025 14:16:50 +0200
Subject: [PATCH 08/68] Update table test to verify formatted cell content

---
 Sources/HTML/MarkupRenderer.swift         |  8 +++-----
 Tests/HTMLTests/MarkupRendererTests.swift | 14 +++++++++-----
 2 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/Sources/HTML/MarkupRenderer.swift b/Sources/HTML/MarkupRenderer.swift
index 53de05f941..15a1cdc7b2 100644
--- a/Sources/HTML/MarkupRenderer.swift
+++ b/Sources/HTML/MarkupRenderer.swift
@@ -361,9 +361,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
     
     mutating func visitTable(_ table: Table) -> XMLNode {
         let element = XMLElement(name: "table")
-        
-        var renderer = self // ???: Do we need to use a copy here?
-        
+                
         if !table.head.isEmpty {
             var column = 0
             
@@ -394,7 +392,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
                         
                         return .element(
                             named: "th",
-                            children: renderer.visit(cell.children),
+                            children: visit(cell.children),
                             attributes: attributes
                         )
                     })
@@ -431,7 +429,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
                         
                         return .element(
                             named: "td",
-                            children: renderer.visit(cell.children),
+                            children: visit(cell.children),
                             attributes: attributes
                         )
                     })
diff --git a/Tests/HTMLTests/MarkupRendererTests.swift b/Tests/HTMLTests/MarkupRendererTests.swift
index ce9d0b9b84..dfdc07c58d 100644
--- a/Tests/HTMLTests/MarkupRendererTests.swift
+++ b/Tests/HTMLTests/MarkupRendererTests.swift
@@ -91,9 +91,9 @@ final class MarkupRendererTests: XCTestCase {
     func testRenderTables() async throws {
         try await assert(
             rendering: """
-            First  | Second  | 
-            ------ | ------- |
-            One    | Two     | 
+            First   | Second  | 
+            ------- | ------- |
+            **One** | _Two_   | 
             """,
             prettyFormatted: true,
             // It's weird that XMLNode doesn't indent the <table> children
@@ -107,8 +107,12 @@ final class MarkupRendererTests: XCTestCase {
             </thead>
             <tbody>
                 <tr>
-                    <td>One</td>
-                    <td>Two</td>
+                    <td>
+                        <b>One</b>
+                    </td>
+                    <td>
+                        <i>Two</i>
+                    </td>
                 </tr>
             </tbody>
             </table>

From 6c552d68f113bd8d134f5d2847c104ed8222813e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 4 Oct 2025 17:03:41 +0200
Subject: [PATCH 09/68] Add test for rendering page breadcrumbs

---
 .../HTML/MarkupRenderer+PageElements.swift    | 55 ++++++++++++
 Sources/HTML/MarkupRenderer.swift             |  2 +-
 .../MarkupRenderer+PageElementsTests.swift    | 90 +++++++++++++++++++
 .../MarkupRenderer+WordBreakTests.swift       |  2 +-
 Tests/HTMLTests/MarkupRendererTests.swift     | 28 ++++--
 5 files changed, 168 insertions(+), 9 deletions(-)
 create mode 100644 Sources/HTML/MarkupRenderer+PageElements.swift
 create mode 100644 Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift

diff --git a/Sources/HTML/MarkupRenderer+PageElements.swift b/Sources/HTML/MarkupRenderer+PageElements.swift
new file mode 100644
index 0000000000..df18a9f16d
--- /dev/null
+++ b/Sources/HTML/MarkupRenderer+PageElements.swift
@@ -0,0 +1,55 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+package import Foundation
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+package import FoundationXML
+#endif
+
+package extension MarkupRenderer {
+    /// Creates an HTML element for the breadcrumbs leading up to the renderer's reference.
+    func breadcrumbs(references: [URL]) -> XMLNode {
+        // Breadcrumbs handle symbols differently than most elements, so there's no point in sharing _this_ code
+        func names(for element: LinkedElement) -> [XMLNode] {
+            switch element.names {
+            // Breadcrumbs display both symbolic names and conceptual in a default style
+            case .single(.conceptual(let name)), .single(.symbol(let name)):
+                [.text(name)]
+                
+            case .languageSpecificSymbol(let namesByLanguageID):
+                namesByLanguageID.sorted(by: { $0.key < $1.key }).map { languageID, name in
+                    .element(named: "span", children: [
+                        .text(name) // Breadcrumbs display symbol names in a default style (no "code voice")
+                    ], attributes: ["class": "\(languageID)-only"])
+                }
+            }
+        }
+        
+        var items: [XMLNode] = references.compactMap {
+            linkProvider.element(for: $0).map { page in
+                .element(named: "li", children: [
+                    .element(named: "a", children: names(for: page), attributes: ["href": self.path(to: page.path)])
+                ])
+            }
+        }
+        
+        // The current page doesn't display as a link
+        items.append(
+            .element(named: "li", children: names(for: linkProvider.element(for: self.path)! /* The current page is known to exist */))
+        )
+        
+        return .element(
+            named: "nav",
+            children: [.element(named: "ul", children: items)],
+            attributes: ["id": "breadcrumbs"]
+        )
+    }
+}
diff --git a/Sources/HTML/MarkupRenderer.swift b/Sources/HTML/MarkupRenderer.swift
index 15a1cdc7b2..524fe5ed3f 100644
--- a/Sources/HTML/MarkupRenderer.swift
+++ b/Sources/HTML/MarkupRenderer.swift
@@ -269,7 +269,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
         )
     }
     
-    private func path(to other: URL) -> String {
+    func path(to other: URL) -> String {
         let from = path
         let to   = other
         
diff --git a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
new file mode 100644
index 0000000000..fd02d16973
--- /dev/null
+++ b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
@@ -0,0 +1,90 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+import XCTest
+import HTML
+@testable import SwiftDocC
+import Markdown
+
+final class MarkupRenderer_PageElementsTests: XCTestCase {
+    
+    func testRenderBreadcrumbs() throws {
+        let elements = [
+            LinkedElement(
+                path: URL(string: "/documentation/ModuleName/index.html")!,
+                names: .single(.symbol("ModuleName"))
+            ),
+            LinkedElement(
+                path: URL(string: "/documentation/ModuleName/Something/index.html")!,
+                names: .languageSpecificSymbol([
+                    "swift": "Something",
+                    "occ": "TLASomething",
+                ])
+            ),
+        ]
+        let breadcrumbs = makeRenderer(elementsToReturn: elements).breadcrumbs(references: elements.map { $0.path })
+        
+        XCTAssertEqual(breadcrumbs.rendered(prettyFormatted: true), """
+        <nav id="breadcrumbs">
+        <ul>
+            <li>
+                <a href="../../../index.html">ModuleName</a>
+            </li>
+            <li>
+                <a href="../../index.html">
+                    <span class="occ-only">TLASomething</span>
+                    <span class="swift-only">Something</span>
+                </a>
+            </li>
+            <li>ThisPage</li>
+        </ul>
+        </nav>
+        """)
+    }
+    
+    // MARK: -
+    
+    private func makeRenderer(
+        elementsToReturn: [LinkedElement] = [],
+        assetsToReturn: [String: LinkedAsset] = [:],
+        file: StaticString = #filePath,
+        line: UInt = #line
+    ) -> MarkupRenderer<some LinkProvider> {
+        let path = URL(string: "/documentation/ModuleName/Something/ThisPage/index.html")!
+        
+        var elementsByURL = [
+            path: LinkedElement(path: path, names: .single( .symbol("ThisPage") ))
+        ]
+        for element in elementsToReturn {
+            elementsByURL[element.path] = element
+        }
+        
+        return MarkupRenderer(
+            path: path,
+            linkProvider: MultiValueLinkProvider(
+                elementsToReturn: elementsByURL,
+                assetsToReturn: assetsToReturn
+            )
+        )
+    }
+}
+
+struct MultiValueLinkProvider: LinkProvider {
+    var elementsToReturn: [URL: LinkedElement]
+    func element(for path: URL) -> LinkedElement? {
+        elementsToReturn[path]
+    }
+    
+    var assetsToReturn: [String: LinkedAsset]
+    func assetNamed(_ assetName: String) -> LinkedAsset? {
+        assetsToReturn[assetName]
+    }
+}
diff --git a/Tests/HTMLTests/MarkupRenderer+WordBreakTests.swift b/Tests/HTMLTests/MarkupRenderer+WordBreakTests.swift
index 00e7b4a165..806de69cf7 100644
--- a/Tests/HTMLTests/MarkupRenderer+WordBreakTests.swift
+++ b/Tests/HTMLTests/MarkupRenderer+WordBreakTests.swift
@@ -69,7 +69,7 @@ final class MarkupRenderer_WordBreakTests: XCTestCase {
         file: StaticString = #filePath,
         line: UInt = #line
     ) {
-        let withWordBreaks = MarkupRenderer<TestLinkProvider>.wordBreak(symbolName: symbolName)
+        let withWordBreaks = MarkupRenderer<SingleValueLinkProvider>.wordBreak(symbolName: symbolName)
             .map { $0.xmlString(options: [.nodePrettyPrint, .nodeCompactEmptyElement] )}
             .joined(separator: "\n")
         
diff --git a/Tests/HTMLTests/MarkupRendererTests.swift b/Tests/HTMLTests/MarkupRendererTests.swift
index dfdc07c58d..7b3d9a5498 100644
--- a/Tests/HTMLTests/MarkupRendererTests.swift
+++ b/Tests/HTMLTests/MarkupRendererTests.swift
@@ -522,24 +522,38 @@ final class MarkupRendererTests: XCTestCase {
     ) async throws {
         var renderer = MarkupRenderer(
             path: try XCTUnwrap(URL(string: "/documentation/Something/ThisPage/index.html"), file: file, line: line),
-            linkProvider: TestLinkProvider(
+            linkProvider: SingleValueLinkProvider(
                 elementToReturn: elementToReturn,
                 assetToReturn: assetToReturn
             )
         )
         let htmlNodes = Document(parsing: markdownContent).children.map { renderer.visit($0) }
+        let htmlString = htmlNodes.rendered(prettyFormatted: prettyFormatted)
         
-        let htmlString = if prettyFormatted {
-            htmlNodes.map { $0.xmlString(options: [.nodePrettyPrint, .nodeCompactEmptyElement]) }.joined(separator: "\n")
+        XCTAssertEqual(htmlString, expectedHTML, file: file, line: line)
+    }
+}
+
+// MARK: Helpers
+
+extension XMLNode {
+    func rendered(prettyFormatted: Bool) -> String {
+        if prettyFormatted {
+            xmlString(options: [.nodePrettyPrint, .nodeCompactEmptyElement])
         } else {
-            htmlNodes.map { $0.xmlString(options: .nodeCompactEmptyElement) }.joined(separator: "")
+            xmlString(options: .nodeCompactEmptyElement)
         }
-        
-        XCTAssertEqual(htmlString, expectedHTML, file: file, line: line)
     }
 }
 
-struct TestLinkProvider: LinkProvider {
+extension Sequence<XMLNode> {
+    func rendered(prettyFormatted: Bool) -> String {
+        map { $0.rendered(prettyFormatted: prettyFormatted) }
+            .joined(separator: prettyFormatted ? "\n" : "")
+    }
+}
+
+struct SingleValueLinkProvider: LinkProvider {
     var elementToReturn: LinkedElement?
     func element(for path: URL) -> LinkedElement? {
         elementToReturn

From bae2f016b486f28063d43536bb3c2fced5e289fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 4 Oct 2025 17:09:19 +0200
Subject: [PATCH 10/68] Move word breaking to new type

This avoid needing to specify an unused generic to reference this static method
---
 Sources/HTML/MarkupRenderer.swift                      | 10 +++++-----
 ...{MarkupRenderer+WordBreak.swift => WordBreak.swift} |  2 +-
 .../SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift  |  6 ++----
 ...derer+WordBreakTests.swift => WordBreakTests.swift} |  4 ++--
 4 files changed, 10 insertions(+), 12 deletions(-)
 rename Sources/HTML/{MarkupRenderer+WordBreak.swift => WordBreak.swift} (99%)
 rename Tests/HTMLTests/{MarkupRenderer+WordBreakTests.swift => WordBreakTests.swift} (91%)

diff --git a/Sources/HTML/MarkupRenderer.swift b/Sources/HTML/MarkupRenderer.swift
index 524fe5ed3f..712e1a7e9e 100644
--- a/Sources/HTML/MarkupRenderer.swift
+++ b/Sources/HTML/MarkupRenderer.swift
@@ -185,7 +185,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
             var customTitle = [XMLNode]()
             for child in link.inlineChildren {
                 if let code = child as? InlineCode {
-                    customTitle.append(.element(named: "code", children: Self.wordBreak(symbolName: code.code)))
+                    customTitle.append(.element(named: "code", children: RenderHelpers.wordBreak(symbolName: code.code)))
                 } else {
                     customTitle.append(visit(child))
                 }
@@ -209,12 +209,12 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
                 case .single(let name):
                     switch name {
                         case .conceptual(let name): [ .text(name) ]
-                        case .symbol(let name):     [ .element(named: "code", children: Self.wordBreak(symbolName: name)) ]
+                        case .symbol(let name):     [ .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name)) ]
                     }
                     
                 case .languageSpecificSymbol(let namesByLanguageID):
                     namesByLanguageID.sorted(by: { $0.key < $1.key }).map { languageID, name in
-                            .element(named: "code", children: Self.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
+                            .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
                     }
             }
             
@@ -253,12 +253,12 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
             case .single(let name):
                 switch name {
                     case .conceptual(let name): [ .text(name) ]
-                    case .symbol(let name):     [ .element(named: "code", children: Self.wordBreak(symbolName: name)) ]
+                    case .symbol(let name):     [ .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name)) ]
                 }
                 
             case .languageSpecificSymbol(let namesByLanguageID):
                 namesByLanguageID.sorted(by: { $0.key < $1.key }).map { languageID, name in
-                    .element(named: "code", children: Self.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
+                    .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
                 }
         }
         
diff --git a/Sources/HTML/MarkupRenderer+WordBreak.swift b/Sources/HTML/WordBreak.swift
similarity index 99%
rename from Sources/HTML/MarkupRenderer+WordBreak.swift
rename to Sources/HTML/WordBreak.swift
index 7c4ef1ee87..c3c2cd9692 100644
--- a/Sources/HTML/MarkupRenderer+WordBreak.swift
+++ b/Sources/HTML/WordBreak.swift
@@ -14,7 +14,7 @@ package import Foundation
 package import FoundationXML
 #endif
 
-extension MarkupRenderer {
+package enum RenderHelpers {
     /// Inserts `<wbr/>` elements into a symbol name so that it can wrap better on the rendered page.
     ///
     /// For example, a method call like this (below), inserts line break elements at the highlighted locations:
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 83e6053985..67fdc4fd55 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -79,8 +79,6 @@ struct ContextLinkProvider: HTML.LinkProvider {
     }
 }
 
-private typealias MarkupRenderer = HTML.MarkupRenderer<ContextLinkProvider>
-
 struct HTMLRenderer {
     let reference: ResolvedTopicReference
     let context: DocumentationContext
@@ -302,7 +300,7 @@ struct HTMLRenderer {
             hero.addChild(
                 .element(
                     named: "h1",
-                    children: MarkupRenderer.wordBreak(symbolName: variant),
+                    children: RenderHelpers.wordBreak(symbolName: variant),
                     attributes: attributes
                 )
             )
@@ -678,7 +676,7 @@ struct HTMLRenderer {
                                             "decorator"
                                     }
                                     
-                                    return .element(named: "span", children: MarkupRenderer.wordBreak(symbolName: fragment.spelling), attributes: ["class": className])
+                                    return .element(named: "span", children: RenderHelpers.wordBreak(symbolName: fragment.spelling), attributes: ["class": className])
                                 },
                                 attributes: ["class": "\(lang)-only"]
                             )
diff --git a/Tests/HTMLTests/MarkupRenderer+WordBreakTests.swift b/Tests/HTMLTests/WordBreakTests.swift
similarity index 91%
rename from Tests/HTMLTests/MarkupRenderer+WordBreakTests.swift
rename to Tests/HTMLTests/WordBreakTests.swift
index 806de69cf7..693af15c1f 100644
--- a/Tests/HTMLTests/MarkupRenderer+WordBreakTests.swift
+++ b/Tests/HTMLTests/WordBreakTests.swift
@@ -12,7 +12,7 @@ import Foundation
 import XCTest
 import HTML
 
-final class MarkupRenderer_WordBreakTests: XCTestCase {
+final class WordBreakTests: XCTestCase {
     func testWordBreaks() {
         assertWordBreaks(for: "doSomething<Generic>(withFirst:andSecond:)", matches: """
         do
@@ -69,7 +69,7 @@ final class MarkupRenderer_WordBreakTests: XCTestCase {
         file: StaticString = #filePath,
         line: UInt = #line
     ) {
-        let withWordBreaks = MarkupRenderer<SingleValueLinkProvider>.wordBreak(symbolName: symbolName)
+        let withWordBreaks = RenderHelpers.wordBreak(symbolName: symbolName)
             .map { $0.xmlString(options: [.nodePrettyPrint, .nodeCompactEmptyElement] )}
             .joined(separator: "\n")
         

From 005191c77024320a3b46557b4d1ff9d4732724a0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 4 Oct 2025 17:18:09 +0200
Subject: [PATCH 11/68] Sort Swift before other language specific symbol names

---
 Sources/HTML/MarkupRenderer+PageElements.swift     |  2 +-
 Sources/HTML/MarkupRenderer.swift                  |  6 +++---
 Sources/HTML/WordBreak.swift                       | 14 ++++++++++++++
 .../MarkupRenderer+PageElementsTests.swift         |  2 +-
 Tests/HTMLTests/MarkupRendererTests.swift          |  8 ++++----
 5 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/Sources/HTML/MarkupRenderer+PageElements.swift b/Sources/HTML/MarkupRenderer+PageElements.swift
index df18a9f16d..9eb172dd13 100644
--- a/Sources/HTML/MarkupRenderer+PageElements.swift
+++ b/Sources/HTML/MarkupRenderer+PageElements.swift
@@ -25,7 +25,7 @@ package extension MarkupRenderer {
                 [.text(name)]
                 
             case .languageSpecificSymbol(let namesByLanguageID):
-                namesByLanguageID.sorted(by: { $0.key < $1.key }).map { languageID, name in
+                RenderHelpers.sortedLanguageSpecificNames(namesByLanguageID).map { languageID, name in
                     .element(named: "span", children: [
                         .text(name) // Breadcrumbs display symbol names in a default style (no "code voice")
                     ], attributes: ["class": "\(languageID)-only"])
diff --git a/Sources/HTML/MarkupRenderer.swift b/Sources/HTML/MarkupRenderer.swift
index 712e1a7e9e..3b66e8a1c5 100644
--- a/Sources/HTML/MarkupRenderer.swift
+++ b/Sources/HTML/MarkupRenderer.swift
@@ -213,8 +213,8 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
                     }
                     
                 case .languageSpecificSymbol(let namesByLanguageID):
-                    namesByLanguageID.sorted(by: { $0.key < $1.key }).map { languageID, name in
-                            .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
+                    RenderHelpers.sortedLanguageSpecificNames(namesByLanguageID).map { languageID, name in
+                        .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
                     }
             }
             
@@ -257,7 +257,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
                 }
                 
             case .languageSpecificSymbol(let namesByLanguageID):
-                namesByLanguageID.sorted(by: { $0.key < $1.key }).map { languageID, name in
+                RenderHelpers.sortedLanguageSpecificNames(namesByLanguageID).map { languageID, name in
                     .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
                 }
         }
diff --git a/Sources/HTML/WordBreak.swift b/Sources/HTML/WordBreak.swift
index c3c2cd9692..a0e34cdf03 100644
--- a/Sources/HTML/WordBreak.swift
+++ b/Sources/HTML/WordBreak.swift
@@ -53,6 +53,20 @@ package enum RenderHelpers {
         
         return result
     }
+    
+    /// Returns the language specific symbol names sorted by the language.
+    package static func sortedLanguageSpecificNames(_ namesByLanguageID: [String /* language ID */: String]) -> some Sequence<(key: String, value: String)> {
+        namesByLanguageID.sorted(by: { lhs, rhs in
+            // Sort Swift before other languages.
+            if lhs.key == "swift" {
+                return true
+            } else if rhs.key == "swift" {
+                return false
+            }
+            // Otherwise, sort by ID for a stable order.
+            return lhs.key < rhs.key
+        })
+    }
 }
 
 private extension UTF8.CodeUnit {
diff --git a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
index fd02d16973..25c7fdf232 100644
--- a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
+++ b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
@@ -40,8 +40,8 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
             </li>
             <li>
                 <a href="../../index.html">
-                    <span class="occ-only">TLASomething</span>
                     <span class="swift-only">Something</span>
+                    <span class="occ-only">TLASomething</span>
                 </a>
             </li>
             <li>ThisPage</li>
diff --git a/Tests/HTMLTests/MarkupRendererTests.swift b/Tests/HTMLTests/MarkupRendererTests.swift
index 7b3d9a5498..62e9dc08a7 100644
--- a/Tests/HTMLTests/MarkupRendererTests.swift
+++ b/Tests/HTMLTests/MarkupRendererTests.swift
@@ -384,16 +384,16 @@ final class MarkupRendererTests: XCTestCase {
             matches: """
             <p>
             <a href="../../SomeClass/someMethod(_:_:)/index.html">
+                <code class="swift-only">do<wbr/>
+                    Something(<wbr/>
+                    with:<wbr/>
+                    and:)</code>
                 <code class="occ-only">do<wbr/>
                     Something<wbr/>
                     With<wbr/>
                     First:<wbr/>
                     and<wbr/>
                     Second:</code>
-                <code class="swift-only">do<wbr/>
-                    Something(<wbr/>
-                    with:<wbr/>
-                    and:)</code>
             </a>
             </p>
             """

From 5cd607b5f61edf08b8abc80bafb36f9715866468 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 4 Oct 2025 17:41:44 +0200
Subject: [PATCH 12/68] Use new breadcrumbs function when rendering pages

---
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 57 +++++++------------
 1 file changed, 19 insertions(+), 38 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 67fdc4fd55..566e4576fb 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -17,7 +17,7 @@ import HTML
 import Markdown
 import SymbolKit
 
-struct ContextLinkProvider: HTML.LinkProvider {
+private struct ContextLinkProvider: HTML.LinkProvider {
     let reference: ResolvedTopicReference
     let context: DocumentationContext
     
@@ -58,7 +58,7 @@ struct ContextLinkProvider: HTML.LinkProvider {
         }
         
         return .init(
-            path: node.reference.url.withoutHostAndPortAndScheme().appendingPathComponent("index.html"),
+            path: Self.filePath(for: node.reference),
             names: names
         )
     }
@@ -77,6 +77,10 @@ struct ContextLinkProvider: HTML.LinkProvider {
         
         return .init(images: images)
     }
+    
+    static func filePath(for reference: ResolvedTopicReference) -> URL {
+        reference.url.withoutHostAndPortAndScheme().appendingPathComponent("index.html")
+    }
 }
 
 struct HTMLRenderer {
@@ -87,12 +91,17 @@ struct HTMLRenderer {
     private let linkProvider: ContextLinkProvider
     private let filePath: URL
     
+    private var renderer: MarkupRenderer<ContextLinkProvider>
+    
     init(reference: ResolvedTopicReference, context: DocumentationContext, renderContext: RenderContext) {
         self.reference = reference
         self.context = context
         self.renderContext = renderContext
-        self.linkProvider = .init(reference: reference, context: context)
-        self.filePath = reference.url.withoutHostAndPortAndScheme().appendingPathComponent("index.html")
+        let linkProvider = ContextLinkProvider(reference: reference, context: context)
+        self.linkProvider = linkProvider
+        let filePath = reference.url.withoutHostAndPortAndScheme().appendingPathComponent("index.html")
+        self.filePath = filePath
+        self.renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
     }
     
     private func path(to destination: ResolvedTopicReference) -> String {
@@ -105,14 +114,6 @@ struct HTMLRenderer {
         let node = context.documentationCache[reference]!
         
         let main = XMLElement(name: "main")
-        
-        let breadcrumbs = context.shortestFinitePath(to: reference) ?? [context.soleRootModuleReference!]
-        let breadcrumbElements: [XMLNode] = breadcrumbs.map {
-            let node = context.documentationCache[$0]!
-            
-            return .element(named: "a", children: [.text(node.name.plainText)], attributes: ["href": path(to: $0)])
-        }
-        
         let articleElement = XMLElement(name: "article")
         main.addChild(articleElement)
         
@@ -124,15 +125,9 @@ struct HTMLRenderer {
         // Breadcrumbs and Eyebrow
         hero.addChild(
             .element(named: "header", children: [
-                .element(named: "nav", children: [
-                    .element(
-                        named: "ul",
-                        children: (breadcrumbElements + [.text(node.name.plainText)]).map {
-                            .element(named: "li", children: [$0])
-                        },
-                        attributes: ["id": "breadcrumbs"]
-                    )
-                ]),
+                renderer.breadcrumbs(
+                    references: (context.shortestFinitePath(to: reference) ?? [context.soleRootModuleReference!]).map { ContextLinkProvider.filePath(for: $0) }
+                ),
                 
                 .element(
                     named: "span",
@@ -235,14 +230,6 @@ struct HTMLRenderer {
         let isDeprecated = symbol.isDeprecated
         
         let main = XMLElement(name: "main")
-        
-        let breadcrumbs = context.linkResolver.localResolver.breadcrumbs(of: reference, in: reference.sourceLanguage) ?? []
-        let breadcrumbElements: [XMLNode] = breadcrumbs.map {
-            let node = context.documentationCache[$0]!
-            
-            return .element(named: "a", children: [.text(node.name.plainText)], attributes: ["href": path(to: $0)])
-        }
-        
         let articleElement = XMLElement(name: "article")
         main.addChild(articleElement)
         
@@ -259,15 +246,9 @@ struct HTMLRenderer {
         // Breadcrumbs and Eyebrow
         hero.addChild(
             .element(named: "header", children: [
-                .element(named: "nav", children: [
-                    .element(
-                        named: "ul",
-                        children: (breadcrumbElements + [.text(node.name.plainText)]).map {
-                            .element(named: "li", children: [$0], attributes: isDeprecated ? ["class": "deprecated"] : nil)
-                        },
-                        attributes: ["id": "breadcrumbs"]
-                    )
-                ]),
+                renderer.breadcrumbs(
+                    references: (context.linkResolver.localResolver.breadcrumbs(of: reference, in: reference.sourceLanguage) ?? []).map { ContextLinkProvider.filePath(for: $0) }
+                ),
                 
                 .element(
                     named: "span",

From 2746aaf7ebdce8d29e62e88fc9c0462b8d796e6e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 4 Oct 2025 17:51:01 +0200
Subject: [PATCH 13/68] Add test for rendering page availability

---
 .../HTML/MarkupRenderer+PageElements.swift    | 52 +++++++++++++++++++
 .../MarkupRenderer+PageElementsTests.swift    | 16 ++++++
 2 files changed, 68 insertions(+)

diff --git a/Sources/HTML/MarkupRenderer+PageElements.swift b/Sources/HTML/MarkupRenderer+PageElements.swift
index 9eb172dd13..a689643132 100644
--- a/Sources/HTML/MarkupRenderer+PageElements.swift
+++ b/Sources/HTML/MarkupRenderer+PageElements.swift
@@ -52,4 +52,56 @@ package extension MarkupRenderer {
             attributes: ["id": "breadcrumbs"]
         )
     }
+    
+    struct AvailabilityInfo {
+        package var name: String
+        package var introduced, deprecated: String?
+        package var isBeta: Bool
+        
+        package init(name: String, introduced: String? = nil, deprecated: String? = nil, isBeta: Bool) {
+            self.name = name
+            self.introduced = introduced
+            self.deprecated = deprecated
+            self.isBeta = isBeta
+        }
+    }
+    
+    /// Creates an HTML element for the availability information.
+    func availability(_ info: [AvailabilityInfo]) -> XMLNode {
+        let items: [XMLNode] = info.map {
+            var text = $0.name
+            
+            let description: String
+            if let introduced = $0.introduced {
+                if let deprecated  = $0.deprecated{
+                    text += " \(introduced)–\(deprecated)"
+                    description = "Introduced in \($0.name) \(introduced) and deprecated in \($0.name) \(deprecated)"
+                } else {
+                    text += " \(introduced)+"
+                    description = "Available on \(introduced) and later"
+                }
+            } else {
+                description = "Available on \($0.name)"
+            }
+            
+            var attributes = [
+                "role": "text",
+                "aria-label": "\(text), \(description)",
+                "title": description
+            ]
+            if $0.isBeta {
+                attributes["class"] = "beta"
+            } else if $0.deprecated != nil {
+                attributes["class"] = "deprecated"
+            }
+            
+            return .element(named: "li", children: [.text(text)], attributes: attributes)
+        }
+        
+        return .element(
+            named: "ul",
+            children: items,
+            attributes: ["id": "availability"]
+        )
+    }
 }
diff --git a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
index 25c7fdf232..8c95421395 100644
--- a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
+++ b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
@@ -50,6 +50,22 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         """)
     }
     
+    func testRenderAvailability() throws {
+        let availability = makeRenderer().availability([
+            .init(name: "First", introduced: "1.2", deprecated: "3.4", isBeta: false),
+            .init(name: "Second", introduced: "1.2.3", isBeta: false),
+            .init(name: "Third", introduced: "4.5", isBeta: true),
+        ])
+        
+        XCTAssertEqual(availability.rendered(prettyFormatted: true), """
+        <ul id="availability">
+        <li aria-label="First 1.2–3.4, Introduced in First 1.2 and deprecated in First 3.4" class="deprecated" role="text" title="Introduced in First 1.2 and deprecated in First 3.4">First 1.2–3.4</li>
+        <li aria-label="Second 1.2.3+, Available on 1.2.3 and later" role="text" title="Available on 1.2.3 and later">Second 1.2.3+</li>
+        <li aria-label="Third 4.5+, Available on 4.5 and later" class="beta" role="text" title="Available on 4.5 and later">Third 4.5+</li>
+        </ul>
+        """)
+    }
+    
     // MARK: -
     
     private func makeRenderer(

From 8ab20b6e4a041a41c80602fdfd8bc7dc584d3094 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 4 Oct 2025 17:55:41 +0200
Subject: [PATCH 14/68] Use new availability function when rendering pages

---
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 61 ++++---------------
 1 file changed, 12 insertions(+), 49 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 566e4576fb..d0b51f7c90 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -299,56 +299,19 @@ struct HTMLRenderer {
         }
         
         // Availability
-        if let availability = symbol.availability?.availability {
-            // ???: Do we want a div for this?
-            let container = XMLNode.element(named: "div", attributes: ["class": "availability"])
-            hero.addChild(container)
-            
-            for item in availability.filter({ $0.domain != nil }).sorted(by: \.domain!.rawValue) {
-                let name = item.domain!.rawValue
-                
-                let introducedVersion = item.introducedVersion.map {
-                    "\($0.major).\($0.minor)"
-                }
-                let deprecatedVersion = item.deprecatedVersion.map {
-                    "\($0.major).\($0.minor)"
-                }
-                
-                let short: String
-                let description: String
-                if let introducedVersion {
-                    if let deprecatedVersion {
-                        short = " \(introducedVersion)–\(deprecatedVersion)"
-                        description = "Introduced in \(name) \(introducedVersion) and deprecated in \(name) \(deprecatedVersion)"
-                    } else {
-                        short = " \(introducedVersion)+"
-                        description = "Available on \(introducedVersion) and later"
-                    }
-                } else {
-                    short = ""
-                    description = "Available on \(name)"
-                }
-                let text = "\(name) \(short)"
-                
-                var attributes = [
-                    "role": "text",
-                    "aria-label": "\(text), \(description)",
-                    "title": description
-                ]
-                if isDeprecated {
-                    attributes["class"] = "deprecated"
-                }
-                
-                // TODO: Add deprecated and beta badges
-                container.addChild(
-                    .element(
-                        named: "span",
-                        children: [.text(text)],
-                        attributes: attributes
+        if let availability = symbol.availability?.availability.filter({ $0.domain != nil }).sorted(by: \.domain!.rawValue),
+           !availability.isEmpty
+        {
+            hero.addChild(
+                renderer.availability(availability.map { item in
+                    .init(
+                        name: item.domain!.rawValue, // Verified non-empty above
+                        introduced: item.introducedVersion.map { "\($0.major).\($0.minor)" },
+                        deprecated: item.deprecatedVersion.map { "\($0.major).\($0.minor)" },
+                        isBeta: false // FIXME: Derive and pass beta information
                     )
-                )
-            }
-            
+                })
+            )
         }
         
         // Declaration

From 9ce783aa3a275e81836877ebdd29b48da1cbc191 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sun, 5 Oct 2025 19:14:20 +0200
Subject: [PATCH 15/68] Move breadcrumbs and availability helpers to separate
 files

---
 ...wift => MarkupRenderer+Availability.swift} | 38 -------------
 Sources/HTML/MarkupRenderer+Breadcrumbs.swift | 55 +++++++++++++++++++
 2 files changed, 55 insertions(+), 38 deletions(-)
 rename Sources/HTML/{MarkupRenderer+PageElements.swift => MarkupRenderer+Availability.swift} (57%)
 create mode 100644 Sources/HTML/MarkupRenderer+Breadcrumbs.swift

diff --git a/Sources/HTML/MarkupRenderer+PageElements.swift b/Sources/HTML/MarkupRenderer+Availability.swift
similarity index 57%
rename from Sources/HTML/MarkupRenderer+PageElements.swift
rename to Sources/HTML/MarkupRenderer+Availability.swift
index a689643132..d03054e946 100644
--- a/Sources/HTML/MarkupRenderer+PageElements.swift
+++ b/Sources/HTML/MarkupRenderer+Availability.swift
@@ -15,44 +15,6 @@ package import FoundationXML
 #endif
 
 package extension MarkupRenderer {
-    /// Creates an HTML element for the breadcrumbs leading up to the renderer's reference.
-    func breadcrumbs(references: [URL]) -> XMLNode {
-        // Breadcrumbs handle symbols differently than most elements, so there's no point in sharing _this_ code
-        func names(for element: LinkedElement) -> [XMLNode] {
-            switch element.names {
-            // Breadcrumbs display both symbolic names and conceptual in a default style
-            case .single(.conceptual(let name)), .single(.symbol(let name)):
-                [.text(name)]
-                
-            case .languageSpecificSymbol(let namesByLanguageID):
-                RenderHelpers.sortedLanguageSpecificNames(namesByLanguageID).map { languageID, name in
-                    .element(named: "span", children: [
-                        .text(name) // Breadcrumbs display symbol names in a default style (no "code voice")
-                    ], attributes: ["class": "\(languageID)-only"])
-                }
-            }
-        }
-        
-        var items: [XMLNode] = references.compactMap {
-            linkProvider.element(for: $0).map { page in
-                .element(named: "li", children: [
-                    .element(named: "a", children: names(for: page), attributes: ["href": self.path(to: page.path)])
-                ])
-            }
-        }
-        
-        // The current page doesn't display as a link
-        items.append(
-            .element(named: "li", children: names(for: linkProvider.element(for: self.path)! /* The current page is known to exist */))
-        )
-        
-        return .element(
-            named: "nav",
-            children: [.element(named: "ul", children: items)],
-            attributes: ["id": "breadcrumbs"]
-        )
-    }
-    
     struct AvailabilityInfo {
         package var name: String
         package var introduced, deprecated: String?
diff --git a/Sources/HTML/MarkupRenderer+Breadcrumbs.swift b/Sources/HTML/MarkupRenderer+Breadcrumbs.swift
new file mode 100644
index 0000000000..9eb172dd13
--- /dev/null
+++ b/Sources/HTML/MarkupRenderer+Breadcrumbs.swift
@@ -0,0 +1,55 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+package import Foundation
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+package import FoundationXML
+#endif
+
+package extension MarkupRenderer {
+    /// Creates an HTML element for the breadcrumbs leading up to the renderer's reference.
+    func breadcrumbs(references: [URL]) -> XMLNode {
+        // Breadcrumbs handle symbols differently than most elements, so there's no point in sharing _this_ code
+        func names(for element: LinkedElement) -> [XMLNode] {
+            switch element.names {
+            // Breadcrumbs display both symbolic names and conceptual in a default style
+            case .single(.conceptual(let name)), .single(.symbol(let name)):
+                [.text(name)]
+                
+            case .languageSpecificSymbol(let namesByLanguageID):
+                RenderHelpers.sortedLanguageSpecificNames(namesByLanguageID).map { languageID, name in
+                    .element(named: "span", children: [
+                        .text(name) // Breadcrumbs display symbol names in a default style (no "code voice")
+                    ], attributes: ["class": "\(languageID)-only"])
+                }
+            }
+        }
+        
+        var items: [XMLNode] = references.compactMap {
+            linkProvider.element(for: $0).map { page in
+                .element(named: "li", children: [
+                    .element(named: "a", children: names(for: page), attributes: ["href": self.path(to: page.path)])
+                ])
+            }
+        }
+        
+        // The current page doesn't display as a link
+        items.append(
+            .element(named: "li", children: names(for: linkProvider.element(for: self.path)! /* The current page is known to exist */))
+        )
+        
+        return .element(
+            named: "nav",
+            children: [.element(named: "ul", children: items)],
+            attributes: ["id": "breadcrumbs"]
+        )
+    }
+}

From fb0c415209886e215b704b1174152a0f9b969e99 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 11 Oct 2025 10:43:36 +0200
Subject: [PATCH 16/68] Add test for rendering symbol parameters

---
 Sources/HTML/MarkupRenderer+Breadcrumbs.swift |   2 +-
 Sources/HTML/MarkupRenderer+Parameters.swift  | 122 +++++++++++++++
 Sources/HTML/MarkupRenderer.swift             |   4 +-
 Sources/HTML/WordBreak.swift                  |   4 +-
 Sources/HTML/XMLNode+element.swift            |  11 ++
 .../MarkupRenderer+PageElementsTests.swift    | 140 ++++++++++++++++++
 6 files changed, 278 insertions(+), 5 deletions(-)
 create mode 100644 Sources/HTML/MarkupRenderer+Parameters.swift

diff --git a/Sources/HTML/MarkupRenderer+Breadcrumbs.swift b/Sources/HTML/MarkupRenderer+Breadcrumbs.swift
index 9eb172dd13..214f5de8dc 100644
--- a/Sources/HTML/MarkupRenderer+Breadcrumbs.swift
+++ b/Sources/HTML/MarkupRenderer+Breadcrumbs.swift
@@ -25,7 +25,7 @@ package extension MarkupRenderer {
                 [.text(name)]
                 
             case .languageSpecificSymbol(let namesByLanguageID):
-                RenderHelpers.sortedLanguageSpecificNames(namesByLanguageID).map { languageID, name in
+                RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { languageID, name in
                     .element(named: "span", children: [
                         .text(name) // Breadcrumbs display symbol names in a default style (no "code voice")
                     ], attributes: ["class": "\(languageID)-only"])
diff --git a/Sources/HTML/MarkupRenderer+Parameters.swift b/Sources/HTML/MarkupRenderer+Parameters.swift
new file mode 100644
index 0000000000..d2f07fc77d
--- /dev/null
+++ b/Sources/HTML/MarkupRenderer+Parameters.swift
@@ -0,0 +1,122 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+package import Foundation
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+package import FoundationXML
+#endif
+
+package import Markdown
+
+package extension MarkupRenderer {
+    struct ParameterInfo {
+        package var name: String
+        package var content: [any Markup]
+        
+        package init(name: String, content: [any Markup]) {
+            self.name = name
+            self.content = content
+        }
+    }
+    
+    mutating func parameters(_ info: [String: [ParameterInfo]]) -> XMLNode {
+        let info = RenderHelpers.sortedLanguageSpecificValues(info)
+        
+        // Add a heading that references the section before anything the actual parameter list
+        var items: [XMLElement] = [
+            .element(named: "h2", children: [
+                .element(named: "a", children: [.text("Parameters")], attributes: ["href": "#parameters"])
+            ])
+        ]
+        
+        switch info.count {
+        case 1:
+            items.append(
+                _singleLanguageParameters(info.first!.value) // Verified to exist above
+            )
+        case 2:
+            items.append(
+                _dualLanguageParameters(primary: info.first!, secondary: info.last!) // Both verified to exist above
+            )
+        default:
+            // In practice DocC only encounters one or two different languages. If there would be a third one,
+            // produce correct looking pages that may include duplicated markup by not trying to share parameters across languages.
+            items.append(contentsOf: info.map { languageID, info in
+                .element(
+                    named: "dl",
+                    children: _singleLanguageParameterItems(info),
+                    attributes: ["class": "\(languageID)-only"]
+                )
+            })
+        }
+        
+        return .element(named: "section", children: items, attributes: ["id": "parameters"])
+    }
+    
+    private mutating func _singleLanguageParameters(_ parameterInfo: [ParameterInfo]) -> XMLElement {
+        .element(named: "dl", children: _singleLanguageParameterItems(parameterInfo))
+    }
+    
+    private mutating func _singleLanguageParameterItems(_ parameterInfo: [ParameterInfo]) -> [XMLElement] {
+        var items: [XMLElement] = []
+        items.reserveCapacity(parameterInfo.count * 2)
+        for parameter in parameterInfo {
+            // name
+            items.append(
+                .element(named: "dt", children: [
+                    .element(named: "code", children: [.text(parameter.name)])
+                ])
+            )
+            // description
+            items.append(
+                .element(named: "dd", children: parameter.content.map { visit($0) })
+            )
+        }
+        
+        return items
+    }
+    
+    private mutating func _dualLanguageParameters(
+        primary: (key: String, value: [ParameterInfo]),
+        secondary: (key: String, value: [ParameterInfo])
+    ) -> XMLElement {
+        var items = _singleLanguageParameterItems(primary.value)
+        
+        let differences = secondary.value.difference(from: primary.value, by: { $0.name == $1.name })
+        
+        var primaryOnlyIndices = Set<Int>()
+        
+        for case let .remove(offset, _, _) in differences.removals {
+            // This item only exists in the primary parameters
+            primaryOnlyIndices.insert(offset)
+            let index = offset * 2
+            // Mark those items as only being applying to the first language
+            items[index    ].addAttributes(["class": "\(primary.key)-only"])
+            items[index + 1].addAttributes(["class": "\(primary.key)-only"])
+        }
+        
+        for case let .insert(offset, parameter, _) in differences.insertions {
+            // This parameter only exist in the secondary parameters.
+            let index = (offset + primaryOnlyIndices.count(where: { $0 < offset })) * 2
+            // Description first because we're appending twice
+            items.insert(contentsOf: [
+                // Name
+                .element(named: "dt", children: [
+                    .element(named: "code", children: [.text(parameter.name)])
+                ], attributes: ["class": "\(secondary.key)-only"]),
+                // Description
+                .element(named: "dd", children: parameter.content.map { visit($0) }, attributes: ["class": "\(secondary.key)-only"])
+            ], at: index)
+        }
+        
+        return .element(named: "dl", children: items)
+    }
+}
diff --git a/Sources/HTML/MarkupRenderer.swift b/Sources/HTML/MarkupRenderer.swift
index 3b66e8a1c5..bbfd55105e 100644
--- a/Sources/HTML/MarkupRenderer.swift
+++ b/Sources/HTML/MarkupRenderer.swift
@@ -213,7 +213,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
                     }
                     
                 case .languageSpecificSymbol(let namesByLanguageID):
-                    RenderHelpers.sortedLanguageSpecificNames(namesByLanguageID).map { languageID, name in
+                    RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { languageID, name in
                         .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
                     }
             }
@@ -257,7 +257,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
                 }
                 
             case .languageSpecificSymbol(let namesByLanguageID):
-                RenderHelpers.sortedLanguageSpecificNames(namesByLanguageID).map { languageID, name in
+                RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { languageID, name in
                     .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
                 }
         }
diff --git a/Sources/HTML/WordBreak.swift b/Sources/HTML/WordBreak.swift
index a0e34cdf03..7cb072b5e6 100644
--- a/Sources/HTML/WordBreak.swift
+++ b/Sources/HTML/WordBreak.swift
@@ -55,8 +55,8 @@ package enum RenderHelpers {
     }
     
     /// Returns the language specific symbol names sorted by the language.
-    package static func sortedLanguageSpecificNames(_ namesByLanguageID: [String /* language ID */: String]) -> some Sequence<(key: String, value: String)> {
-        namesByLanguageID.sorted(by: { lhs, rhs in
+    package static func sortedLanguageSpecificValues<Value>(_ valuesByLanguageID: [String /* language ID */: Value]) -> [(key: String, value: Value)] {
+        valuesByLanguageID.sorted(by: { lhs, rhs in
             // Sort Swift before other languages.
             if lhs.key == "swift" {
                 return true
diff --git a/Sources/HTML/XMLNode+element.swift b/Sources/HTML/XMLNode+element.swift
index 6c572de670..c30d92a2cb 100644
--- a/Sources/HTML/XMLNode+element.swift
+++ b/Sources/HTML/XMLNode+element.swift
@@ -40,3 +40,14 @@ extension XMLNode {
         XMLNode.text(withStringValue: String(value)) as! XMLNode
     }
 }
+
+extension XMLElement {
+    func addAttributes(_ attributes: [String: String]) {
+        let attributeNodes = attributes.sorted(by: { $0.key < $1.key }).map {
+            XMLNode.attribute(withName: $0.key, stringValue: $0.value) as! XMLNode
+        }
+        for attributeNode in attributeNodes {
+            self.addAttribute(attributeNode)
+        }
+    }
+}
diff --git a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
index 8c95421395..c34d52ad07 100644
--- a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
+++ b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
@@ -66,6 +66,141 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         """)
     }
     
+    func testRenderSingleLanguageParameters() throws {
+        var renderer = makeRenderer()
+        let parameters = renderer.parameters([
+            "swift": [
+                .init(name: "First", content: parseMarkup(string: "Some _formatted_ description with `code`")),
+                .init(name: "Second", content: parseMarkup(string: """
+                Some **other** _formatted_ description
+
+                That spans two paragraphs
+                """)),
+            ]
+        ])
+        XCTAssertEqual(parameters.rendered(prettyFormatted: true), """
+        <section id="parameters">
+        <h2>
+            <a href="#parameters">Parameters</a>
+        </h2>
+        <dl>
+            <dt>
+                <code>First</code>
+            </dt>
+            <dd>
+                <p>Some <i>formatted</i>
+                     description with <code>code</code>
+                </p>
+            </dd>
+            <dt>
+                <code>Second</code>
+            </dt>
+            <dd>
+                <p>Some <b>other</b>
+                     <i>formatted</i>
+                     description</p>
+                <p>That spans two paragraphs</p>
+            </dd>
+        </dl>
+        </section>
+        """)
+    }
+    
+    func testRenderLanguageSpecificParameters() throws {
+        var renderer = makeRenderer()
+        let parameters = renderer.parameters([
+            "swift": [
+                .init(name: "FirstCommon", content: parseMarkup(string: "Available in both languages")),
+                .init(name: "SwiftOnly", content: parseMarkup(string: "Only available in Swift")),
+                .init(name: "SecondCommon", content: parseMarkup(string: "Also available in both languages")),
+            ],
+            "occ": [
+                .init(name: "FirstCommon", content: parseMarkup(string: "Available in both languages")),
+                .init(name: "SecondCommon", content: parseMarkup(string: "Also available in both languages")),
+                .init(name: "ObjectiveCOnly", content: parseMarkup(string: "Only available in Objective-C")),
+            ],
+        ])
+        XCTAssertEqual(parameters.rendered(prettyFormatted: true), """
+        <section id="parameters">
+        <h2>
+            <a href="#parameters">Parameters</a>
+        </h2>
+        <dl>
+            <dt>
+                <code>FirstCommon</code>
+            </dt>
+            <dd>
+                <p>Available in both languages</p>
+            </dd>
+            <dt class="swift-only">
+                <code>SwiftOnly</code>
+            </dt>
+            <dd class="swift-only">
+                <p>Only available in Swift</p>
+            </dd>
+            <dt>
+                <code>SecondCommon</code>
+            </dt>
+            <dd>
+                <p>Also available in both languages</p>
+            </dd>
+            <dt class="occ-only">
+                <code>ObjectiveCOnly</code>
+            </dt>
+            <dd class="occ-only">
+                <p>Only available in Objective-C</p>
+            </dd>
+        </dl>
+        </section>
+        """)
+    }
+    
+    func testRenderManyLanguageSpecificParameters() throws {
+        var renderer = makeRenderer()
+        let parameters = renderer.parameters([
+            "swift": [
+                .init(name: "First", content: parseMarkup(string: "Some description")),
+            ],
+            "occ": [
+                .init(name: "Second", content: parseMarkup(string: "Some description")),
+            ],
+            "data": [
+                .init(name: "Third", content: parseMarkup(string: "Some description")),
+            ],
+        ])
+        XCTAssertEqual(parameters.rendered(prettyFormatted: true), """
+        <section id="parameters">
+        <h2>
+            <a href="#parameters">Parameters</a>
+        </h2>
+        <dl class="swift-only">
+            <dt>
+                <code>First</code>
+            </dt>
+            <dd>
+                <p>Some description</p>
+            </dd>
+        </dl>
+        <dl class="data-only">
+            <dt>
+                <code>Third</code>
+            </dt>
+            <dd>
+                <p>Some description</p>
+            </dd>
+        </dl>
+        <dl class="occ-only">
+            <dt>
+                <code>Second</code>
+            </dt>
+            <dd>
+                <p>Some description</p>
+            </dd>
+        </dl>
+        </section>
+        """)
+    }
+    
     // MARK: -
     
     private func makeRenderer(
@@ -91,6 +226,11 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
             )
         )
     }
+    
+    private func parseMarkup(string: String) -> [any Markup] {
+        let document = Document(parsing: string, options: [.parseBlockDirectives, .parseSymbolLinks])
+        return Array(document.children)
+    }
 }
 
 struct MultiValueLinkProvider: LinkProvider {

From 9fb2588e5e501012edb5b89616590de23aa1682d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 11 Oct 2025 11:06:12 +0200
Subject: [PATCH 17/68] Use new parameters function when rendering pages.

Also, update to support language-specific parameters
---
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 44 ++++++-------------
 1 file changed, 13 insertions(+), 31 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index d0b51f7c90..238b4ad297 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -368,38 +368,20 @@ struct HTMLRenderer {
         
         
         // Parameters
-        if let parameters = symbol.parametersSection, !parameters.parameters.isEmpty {
-            let section = XMLElement(name: "section")
-            section.addAttribute(
-                XMLNode.attribute(withName: "class", stringValue: "parameters") as! XMLNode
-            )
-            
-            if let title = ParametersSection.title {
-                section.addChild(
-                    .selfReferencingHeader(title: title)
-                )
-            }
-            
-            var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
-            
-            let list = XMLElement(name: "dl") // list
-            section.addChild(list)
-            
-            for parameter in parameters.parameters {
-                // name
-                list.addChild(
-                    .element(named: "dt", children: [
-                        .element(named: "code", children: [.text(parameter.name)])
-                    ])
-                )
-                
-                // description
-                list.addChild(
-                    .element(named: "dd", children: parameter.contents.map { renderer.visit($0) })
+        if !symbol.parametersSectionVariants.allValues.isEmpty {
+            articleElement.addChild(
+                renderer.parameters(
+                    .init(
+                        symbol.parametersSectionVariants.allValues.map { trait, parameters in (
+                            key:   trait.interfaceLanguage ?? "swift",
+                            value: parameters.parameters.map {
+                                .init(name: $0.name, content: $0.contents)
+                            }
+                        )},
+                        uniquingKeysWith: { _, new in new }
+                    )
                 )
-            }
-            
-            articleElement.addChild(section)
+            )
         }
         
         // Return value

From 29d717c3fcc31542de8e8f620877c3b04f103c99 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 11 Oct 2025 11:47:50 +0200
Subject: [PATCH 18/68] Make HTML.MarkupRenderer APIs non mutating

---
 Sources/HTML/MarkupRenderer+Parameters.swift  |   8 +-
 Sources/HTML/MarkupRenderer.swift             | 140 +++++++++++++-----
 .../Model/Rendering/HTML/HTMLRenderer.swift   |  17 +--
 .../MarkupRenderer+PageElementsTests.swift    |   9 +-
 Tests/HTMLTests/MarkupRendererTests.swift     |  58 ++++----
 5 files changed, 144 insertions(+), 88 deletions(-)

diff --git a/Sources/HTML/MarkupRenderer+Parameters.swift b/Sources/HTML/MarkupRenderer+Parameters.swift
index d2f07fc77d..9434950bd3 100644
--- a/Sources/HTML/MarkupRenderer+Parameters.swift
+++ b/Sources/HTML/MarkupRenderer+Parameters.swift
@@ -27,7 +27,7 @@ package extension MarkupRenderer {
         }
     }
     
-    mutating func parameters(_ info: [String: [ParameterInfo]]) -> XMLNode {
+    func parameters(_ info: [String: [ParameterInfo]]) -> XMLNode {
         let info = RenderHelpers.sortedLanguageSpecificValues(info)
         
         // Add a heading that references the section before anything the actual parameter list
@@ -61,11 +61,11 @@ package extension MarkupRenderer {
         return .element(named: "section", children: items, attributes: ["id": "parameters"])
     }
     
-    private mutating func _singleLanguageParameters(_ parameterInfo: [ParameterInfo]) -> XMLElement {
+    private func _singleLanguageParameters(_ parameterInfo: [ParameterInfo]) -> XMLElement {
         .element(named: "dl", children: _singleLanguageParameterItems(parameterInfo))
     }
     
-    private mutating func _singleLanguageParameterItems(_ parameterInfo: [ParameterInfo]) -> [XMLElement] {
+    private func _singleLanguageParameterItems(_ parameterInfo: [ParameterInfo]) -> [XMLElement] {
         var items: [XMLElement] = []
         items.reserveCapacity(parameterInfo.count * 2)
         for parameter in parameterInfo {
@@ -84,7 +84,7 @@ package extension MarkupRenderer {
         return items
     }
     
-    private mutating func _dualLanguageParameters(
+    private func _dualLanguageParameters(
         primary: (key: String, value: [ParameterInfo]),
         secondary: (key: String, value: [ParameterInfo])
     ) -> XMLElement {
diff --git a/Sources/HTML/MarkupRenderer.swift b/Sources/HTML/MarkupRenderer.swift
index bbfd55105e..8035bce00d 100644
--- a/Sources/HTML/MarkupRenderer.swift
+++ b/Sources/HTML/MarkupRenderer.swift
@@ -9,7 +9,7 @@
 */
 
 package import Foundation
-import Markdown
+package import Markdown
 
 /// A type that provides information about other pages, and on-page elements, that the rendered page references.
 package protocol LinkProvider {
@@ -63,7 +63,7 @@ package struct LinkedAsset {
     }
 }
 
-package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
+package struct MarkupRenderer<Provider: LinkProvider> {
     /// The path within the output archive to the page that this renderer renders.
     let path: URL
     /// A type that provides information about other pages that the rendered page references.
@@ -74,17 +74,11 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
         self.linkProvider = linkProvider
     }
     
-    mutating func defaultVisit(_ markup: any Markdown.Markup) -> XMLNode {
-        fatalError("A placeholder node also crashes here so we might as well make it explicit")
-    }
-    
-    //
-    
-    mutating func visitParagraph(_ paragraph: Paragraph) -> XMLNode {
+    package func visit(_ paragraph: Paragraph) -> XMLNode {
         .element(named: "p", children: visit(paragraph.children))
     }
     
-    mutating func visitBlockQuote(_ blockQuote: BlockQuote) -> XMLNode {
+    func visit(_ blockQuote: BlockQuote) -> XMLNode {
         let aside = Aside(blockQuote)
         
         var children: [XMLNode] = [
@@ -101,39 +95,39 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
         )
     }
     
-    mutating func visitHeading(_ heading: Heading) -> XMLNode {
+    package func visit(_ heading: Heading) -> XMLNode {
         .element(named: "h\(heading.level)", children: visit(heading.children))
     }
     
-    mutating func visitEmphasis(_ emphasis: Emphasis) -> XMLNode {
+    func visit(_ emphasis: Emphasis) -> XMLNode {
         .element(named: "i", children: visit(emphasis.children))
     }
     
-    mutating func visitStrong(_ strong: Strong) -> XMLNode {
+    func visit(_ strong: Strong) -> XMLNode {
         .element(named: "b", children: visit(strong.children))
     }
     
-    mutating func visitStrikethrough(_ strikethrough: Strikethrough) -> XMLNode {
+    func visit(_ strikethrough: Strikethrough) -> XMLNode {
         .element(named: "s", children: visit(strikethrough.children))
     }
     
-    mutating func visitInlineCode(_ inlineCode: InlineCode) -> XMLNode {
+    func visit(_ inlineCode: InlineCode) -> XMLNode {
         .element(named: "code", children: [.text(inlineCode.code)])
     }
     
-    func visitText(_ text: Text) -> XMLNode {
+    func visit(_ text: Text) -> XMLNode {
         .text(text.string)
     }
     
-    func visitLineBreak(_ lineBreak: LineBreak) -> XMLNode {
+    func visit(_ lineBreak: LineBreak) -> XMLNode {
         .element(named: "br")
     }
     
-    func visitSoftBreak(_ softBreak: SoftBreak) -> XMLNode {
+    func visit(_ softBreak: SoftBreak) -> XMLNode {
         .text(" ") // A soft line break doesn't actually break the content
     }
     
-    func visitThematicBreak(_ thematicBreak: ThematicBreak) -> XMLNode {
+    func visit(_ thematicBreak: ThematicBreak) -> XMLNode {
         .element(named: "hr")
     }
     
@@ -152,7 +146,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
         }
     }
     
-    func visitHTMLBlock(_ html: HTMLBlock) -> XMLNode {
+    func visit(_ html: HTMLBlock) -> XMLNode {
         do {
             let parsed = try XMLElement(xmlString: html.rawHTML)
             _removeComments(from: parsed)
@@ -162,7 +156,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
         }
     }
     
-    func visitInlineHTML(_ html: InlineHTML) -> XMLNode {
+    func visit(_ html: InlineHTML) -> XMLNode {
         // Inline HTML is one tag at a time, meaning that the closing and opening tags are parsed separately
         // Because of this, we can't parse it with `XMLElement` or `XMLParser`.
         
@@ -176,7 +170,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
         return .text(html.rawHTML)
     }
     
-    mutating func visitLink(_ link: Link) -> XMLNode {
+    func visit(_ link: Link) -> XMLNode {
         guard let destination = link.destination.flatMap({ URL(string: $0) }) else {
             return .text("")
         }
@@ -238,7 +232,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
         }
     }
     
-    mutating func visitSymbolLink(_ symbolLink: SymbolLink) -> XMLNode {
+    func visit(_ symbolLink: SymbolLink) -> XMLNode {
         guard let destination = symbolLink.destination.flatMap({ URL(string: $0) }),
               let linkedElement = linkProvider.element(for: destination)
         else {
@@ -286,7 +280,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
         return relativeComponents.joined(separator: "/")
     }
     
-    func visitImage(_ image: Image) -> XMLNode {
+    func visit(_ image: Image) -> XMLNode {
         guard let asset = image.source.flatMap({ linkProvider.assetNamed($0) }), !asset.images.isEmpty else {
             return .text("") // ???: What do we return for images that won't display anything?
         }
@@ -328,7 +322,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
         return .element(named: "picture", children: children)
     }
     
-    func visitCodeBlock(_ codeBlock: CodeBlock) -> XMLNode {
+    func visit(_ codeBlock: CodeBlock) -> XMLNode {
         let attributes = codeBlock.language.map {
             ["class": $0]
         }
@@ -345,21 +339,21 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
     
     // MARK: List
     
-    mutating func visitUnorderedList(_ unorderedList: UnorderedList) -> XMLNode {
+    func visit(_ unorderedList: UnorderedList) -> XMLNode {
         .element(named: "ul", children: visit(unorderedList.children))
     }
     
-    mutating func visitOrderedList(_ orderedList: OrderedList) -> XMLNode {
+    func visit(_ orderedList: OrderedList) -> XMLNode {
         .element(named: "ol", children: visit(orderedList.children))
     }
     
-    mutating func visitListItem(_ listItem: ListItem) -> XMLNode {
+    func visit(_ listItem: ListItem) -> XMLNode {
         .element(named: "li", children: visit(listItem.children))
     }
     
     // MARK: Tables
     
-    mutating func visitTable(_ table: Table) -> XMLNode {
+    func visit(_ table: Table) -> XMLNode {
         let element = XMLElement(name: "table")
                 
         if !table.head.isEmpty {
@@ -442,7 +436,7 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
     
     // MARK: Markup children
     
-    private mutating func visit(_ container: MarkupChildren) -> [XMLNode] {
+    private func visit(_ container: MarkupChildren) -> [XMLNode] {
         var children: [XMLNode] = []
         children.reserveCapacity(container.underestimatedCount)
         
@@ -503,31 +497,105 @@ package struct MarkupRenderer<Provider: LinkProvider>: MarkupVisitor {
     
     // MARK: Directives
     
-    func visitBlockDirective(_ blockDirective: BlockDirective) -> XMLNode {
+    func visit(_ blockDirective: BlockDirective) -> XMLNode {
         .text("") // Do nothing for now
     }
     
     // FIXME: It would be nice if DocC processed these before rendering
     
-    mutating func visitDoxygenNote(_ doxygenNote: DoxygenNote) -> XMLNode {
+    func visit(_ doxygenNote: DoxygenNote) -> XMLNode {
         .element(named: "p", children: visit(doxygenNote.children))
     }
     
-    mutating func visitDoxygenReturns(_ doxygenReturns: DoxygenReturns) -> XMLNode {
+    func visit(_ doxygenReturns: DoxygenReturns) -> XMLNode {
         .element(named: "p", children: visit(doxygenReturns.children))
     }
     
-    mutating func visitDoxygenAbstract(_ doxygenAbstract: DoxygenAbstract) -> XMLNode {
+    func visit(_ doxygenAbstract: DoxygenAbstract) -> XMLNode {
         .element(named: "p", children: visit(doxygenAbstract.children))
     }
     
-    mutating func visitDoxygenParameter(_ doxygenParam: DoxygenParameter) -> XMLNode {
+    func visit(_ doxygenParam: DoxygenParameter) -> XMLNode {
         .element(named: "p", children: visit(doxygenParam.children))
     }
     
-    mutating func visitDoxygenDiscussion(_ doxygenDiscussion: DoxygenDiscussion) -> XMLNode {
+    func visit(_ doxygenDiscussion: DoxygenDiscussion) -> XMLNode {
         .element(named: "p", children: visit(doxygenDiscussion.children))
     }
+    
+    // MARK: Default
+    
+    @_disfavoredOverload
+    package func visit(_ markup: some Markup) -> XMLNode {
+        // Check common markup types first
+        if let paragraph = markup as? Paragraph {
+            return visit(paragraph)
+        } else if let text = markup as? Text {
+            return visit(text)
+        } else if let strong = markup as? Strong {
+            return visit(strong)
+        } else if let emphasis = markup as? Emphasis {
+            return visit(emphasis)
+        } else if let symbolLink = markup as? SymbolLink {
+            return visit(symbolLink)
+        } else if let link = markup as? Link {
+            return visit(link)
+        } else if let inlineCode = markup as? InlineCode {
+            return visit(inlineCode)
+        } else if let image = markup as? Image {
+            return visit(image)
+        } else if let listItem = markup as? ListItem {
+            return visit(listItem)
+        } else if let heading = markup as? Heading {
+            return visit(heading)
+        } else if let orderedList = markup as? OrderedList {
+            return visit(orderedList)
+        } else if let unorderedList = markup as? UnorderedList {
+            return visit(unorderedList)
+        } else if let codeBlock = markup as? CodeBlock {
+            return visit(codeBlock)
+        } else if let blockQuote = markup as? BlockQuote {
+            return visit(blockQuote)
+        } else if let table = markup as? Table {
+            return visit(table)
+        } else if let lineBreak = markup as? LineBreak {
+            return visit(lineBreak)
+        } else if let softBreak = markup as? SoftBreak {
+            return visit(softBreak)
+        } else if let thematicBreak = markup as? ThematicBreak {
+            return visit(thematicBreak)
+        } else if let blockDirective = markup as? BlockDirective {
+            return visit(blockDirective)
+        } else if let inlineHTML = markup as? InlineHTML {
+            return visit(inlineHTML)
+        } else if let html = markup as? HTMLBlock {
+            return visit(html)
+        } else if let strikethrough = markup as? Strikethrough {
+            return visit(strikethrough)
+        } else if let customBlock = markup as? CustomBlock {
+            return visit(customBlock)
+        } else if let document = markup as? Document {
+            return visit(document)
+        } else if let customInline = markup as? CustomInline {
+            return visit(customInline)
+        } else if let attributes = markup as? InlineAttributes {
+            return visit(attributes)
+        } else if let doxygenDiscussion = markup as? DoxygenDiscussion {
+            return visit(doxygenDiscussion)
+        } else if let doxygenNote = markup as? DoxygenNote {
+            return visit(doxygenNote)
+        } else if let doxygenAbstract = markup as? DoxygenAbstract {
+            return visit(doxygenAbstract)
+        } else if let doxygenParam = markup as? DoxygenParameter {
+            return visit(doxygenParam)
+        } else if let doxygenReturns = markup as? DoxygenReturns {
+            return visit(doxygenReturns)
+        } else if markup is Table.Head || markup is Table.Body || markup is Table.Row || markup is Table.Cell {
+            fatalError("This renderer is expected to visit the `Table` element, not it's member. It's a programming error to pass one of its member type directly.")
+        } else {
+            fatalError("Encountered unknown markup element. All supported markup elements should already be defined by the Markdown framework")
+        }
+    }
 }
 
 // MARK: Helpers
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 238b4ad297..2827ed2a34 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -91,7 +91,7 @@ struct HTMLRenderer {
     private let linkProvider: ContextLinkProvider
     private let filePath: URL
     
-    private var renderer: MarkupRenderer<ContextLinkProvider>
+    private let renderer: MarkupRenderer<ContextLinkProvider>
     
     init(reference: ResolvedTopicReference, context: DocumentationContext, renderContext: RenderContext) {
         self.reference = reference
@@ -152,8 +152,7 @@ struct HTMLRenderer {
         
         // Abstract
         if let abstract = article.abstract {
-            var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
-            let paragraph = renderer.visitParagraph(abstract) as! XMLElement
+            let paragraph = renderer.visit(abstract) as! XMLElement
             
             paragraph.addAttribute(
                 XMLNode.attribute(withName: "id", stringValue: "abstract") as! XMLNode
@@ -289,8 +288,7 @@ struct HTMLRenderer {
         
         // Abstract
         if let abstract = symbol.abstract {
-            var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
-            let paragraph = renderer.visitParagraph(abstract) as! XMLElement
+            let paragraph = renderer.visit(abstract) as! XMLElement
             
             paragraph.addAttribute(
                 XMLNode.attribute(withName: "id", stringValue: "abstract") as! XMLNode
@@ -349,7 +347,6 @@ struct HTMLRenderer {
         
         // Deprecation message
         if let deprecationSummary = symbol.deprecatedSummary {
-            var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
             var children: [XMLNode] = [
                 .element(named: "p", children: [.text("Deprecated")], attributes: ["class": "label"])
             ]
@@ -397,8 +394,6 @@ struct HTMLRenderer {
                 )
             }
             
-            var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
-            
             for markup in returnsSection.content {
                 section.addChild(
                     renderer.visit(markup)
@@ -515,8 +510,6 @@ struct HTMLRenderer {
             )
         }
         
-        var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
-        
         var remaining = discussion.content[...]
         if let heading = discussion.content.first as? Heading, heading.level == 2 {
             _ = remaining.removeFirst()
@@ -568,8 +561,6 @@ struct HTMLRenderer {
     }
     
     private func makeTopicSectionItem(for reference: ResolvedTopicReference) -> XMLNode? {
-        var renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
-        
         if let local = context.documentationCache[reference] {
             let container = XMLNode.element(named: "div")//, attributes: ["class": className])
             var className = "link-block"
@@ -624,7 +615,7 @@ struct HTMLRenderer {
             
             // Abstract
             if let abstract = (local.semantic as? any Abstracted)?.abstract {
-                container.addChild(renderer.visitParagraph(abstract))
+                container.addChild(renderer.visit(abstract))
             }
             
             return container
diff --git a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
index c34d52ad07..f434564c16 100644
--- a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
+++ b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
@@ -67,8 +67,7 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
     }
     
     func testRenderSingleLanguageParameters() throws {
-        var renderer = makeRenderer()
-        let parameters = renderer.parameters([
+        let parameters = makeRenderer().parameters([
             "swift": [
                 .init(name: "First", content: parseMarkup(string: "Some _formatted_ description with `code`")),
                 .init(name: "Second", content: parseMarkup(string: """
@@ -107,8 +106,7 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
     }
     
     func testRenderLanguageSpecificParameters() throws {
-        var renderer = makeRenderer()
-        let parameters = renderer.parameters([
+        let parameters = makeRenderer().parameters([
             "swift": [
                 .init(name: "FirstCommon", content: parseMarkup(string: "Available in both languages")),
                 .init(name: "SwiftOnly", content: parseMarkup(string: "Only available in Swift")),
@@ -156,8 +154,7 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
     }
     
     func testRenderManyLanguageSpecificParameters() throws {
-        var renderer = makeRenderer()
-        let parameters = renderer.parameters([
+        let parameters = makeRenderer().parameters([
             "swift": [
                 .init(name: "First", content: parseMarkup(string: "Some description")),
             ],
diff --git a/Tests/HTMLTests/MarkupRendererTests.swift b/Tests/HTMLTests/MarkupRendererTests.swift
index 62e9dc08a7..4fbe6bcdb7 100644
--- a/Tests/HTMLTests/MarkupRendererTests.swift
+++ b/Tests/HTMLTests/MarkupRendererTests.swift
@@ -17,24 +17,24 @@ import Markdown
 final class MarkupRendererTests: XCTestCase {
  
     func testRenderParagraphsWithFormattedText() async throws {
-        try await assert(
+        try assert(
             rendering: "This is a paragraph with _emphasized_ and **strong** text.",
             matches: "<p>This is a paragraph with <i>emphasized</i> and <b>strong</b> text.</p>"
         )
         
-        try await assert(
+        try assert(
             rendering: "This is a paragraph with ~strikethrough~ and `pre-formatted` text.",
             matches: "<p>This is a paragraph with <s>strikethrough</s> and <code>pre-formatted</code> text.</p>"
         )
         
-        try await assert(
+        try assert(
             rendering: #"This is a paragraph with "double" and 'single' quoted text."#,
             matches: "<p>This is a paragraph with “double” and ‘single’ quoted text.</p>"
         )
     }
     
     func testRenderHeadings() async throws {
-        try await assert(
+        try assert(
             rendering: """
             # One
             
@@ -50,7 +50,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try await assert(
+        try assert(
             rendering: """
             One
             ===
@@ -65,7 +65,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try await assert(
+        try assert(
             rendering: """
             # _One_
             
@@ -89,7 +89,7 @@ final class MarkupRendererTests: XCTestCase {
     }
     
     func testRenderTables() async throws {
-        try await assert(
+        try assert(
             rendering: """
             First   | Second  | 
             ------- | ------- |
@@ -119,7 +119,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try await assert(
+        try assert(
             rendering: """
             First | Second | Third |
             ----- | ------ | ----- |
@@ -155,7 +155,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try await assert(
+        try assert(
             rendering: """
             First | Second | Third | Fourth 
             ----- | ------ | ----- | ------
@@ -197,7 +197,7 @@ final class MarkupRendererTests: XCTestCase {
     }
     
     func testRenderLists() async throws {
-        try await assert(
+        try assert(
             rendering: """
             - First
             - Second
@@ -248,7 +248,7 @@ final class MarkupRendererTests: XCTestCase {
     }
     
     func testRenderAsides() async throws {
-        try await assert(
+        try assert(
             rendering: """
             > Note: Something noteworthy
             >
@@ -270,7 +270,7 @@ final class MarkupRendererTests: XCTestCase {
     }
     
     func testRenderCodeBlocks() async throws {
-        try await assert(
+        try assert(
             rendering: """
             ~~~
             Some block of code
@@ -285,7 +285,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try await assert(
+        try assert(
             rendering: """
                 Some block of code
             """,
@@ -298,7 +298,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try await assert(
+        try assert(
             rendering: """
             ```lang
             Some block of code
@@ -316,17 +316,17 @@ final class MarkupRendererTests: XCTestCase {
     }
     
     func testRenderMiscellaneousElements() async throws {
-        try await assert(
+        try assert(
             rendering: "First\nSecond", // new lines usually have no special meaning in markdown...
             matches: "<p>First Second</p>"
         )
         
-        try await assert(
+        try assert(
             rendering: "First  \nSecond", // ... but with two trailing spaces they are treated as line breaks
             matches: "<p>First<br/>Second</p>"
         )
         
-        try await assert(
+        try assert(
             rendering: """
             -------
             """,
@@ -336,7 +336,7 @@ final class MarkupRendererTests: XCTestCase {
     
     func testRelativeLinksToOtherPages() async throws {
         // Link to article
-        try await assert(
+        try assert(
             rendering: "<doc://com.example.test/documentation/Something/SomeArticle>", // Simulate a link that's been locally resolved already
             elementToReturn: .init(
                 path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeArticle/index.html")),
@@ -351,7 +351,7 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Link to single-language symbol
-        try await assert(
+        try assert(
             rendering: "<doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)>", // Simulate a link that's been locally resolved already
             elementToReturn: .init(
                 path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
@@ -371,7 +371,7 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Link to symbol with multiple language representation
-        try await assert(
+        try assert(
             rendering: "<doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)>", // Simulate a link that's been locally resolved already
             elementToReturn: .init(
                 path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
@@ -400,7 +400,7 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Link with custom title
-        try await assert(
+        try assert(
             rendering: "[Custom _formatted_ title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
             elementToReturn: .init(
                 path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
@@ -415,7 +415,7 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Link with custom symbol-like title
-        try await assert(
+        try assert(
             rendering: "[Some `CustomSymbolName` title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
             elementToReturn: .init(
                 path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
@@ -432,7 +432,7 @@ final class MarkupRendererTests: XCTestCase {
     
     func testRelativeLinksToImages() async throws {
         // Only a single image representation
-        try await assert(
+        try assert(
             rendering: "![Some alt text](some-image.png)",
             assetToReturn: .init(images: [
                 .light: [1: try XCTUnwrap(URL(string: "images/com.test.example/some-image.png"))]
@@ -448,7 +448,7 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Only light mode image representations
-        try await assert(
+        try assert(
             rendering: "![Some alt text](some-image.png)",
             assetToReturn: .init(images: [
                 .light: [
@@ -467,7 +467,7 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Only a single scale factor
-        try await assert(
+        try assert(
             rendering: "![Some alt text](some-image.png)",
             assetToReturn: .init(images: [
                 .light: [1: try XCTUnwrap(URL(string: "images/com.test.example/some-image.png"))],
@@ -486,7 +486,7 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Multiple styles and scale factors
-        try await assert(
+        try assert(
             rendering: "![Some alt text](some-image.png)",
             assetToReturn: .init(images: [
                 .light: [
@@ -519,9 +519,9 @@ final class MarkupRendererTests: XCTestCase {
         matches expectedHTML: String,
         file: StaticString = #filePath,
         line: UInt = #line
-    ) async throws {
-        var renderer = MarkupRenderer(
-            path: try XCTUnwrap(URL(string: "/documentation/Something/ThisPage/index.html"), file: file, line: line),
+    ) throws {
+        let renderer = MarkupRenderer(
+            path: URL(string: "/documentation/Something/ThisPage/index.html")!,
             linkProvider: SingleValueLinkProvider(
                 elementToReturn: elementToReturn,
                 assetToReturn: assetToReturn

From 145efc44285f1a2b52837aef4b66b36959a9a060 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 11 Oct 2025 12:17:44 +0200
Subject: [PATCH 19/68] Move HTML.LinkProvider (and its method return types) to
 its own file

---
 Sources/HTML/LinkProvider.swift   | 63 +++++++++++++++++++++++++++++++
 Sources/HTML/MarkupRenderer.swift | 52 -------------------------
 2 files changed, 63 insertions(+), 52 deletions(-)
 create mode 100644 Sources/HTML/LinkProvider.swift

diff --git a/Sources/HTML/LinkProvider.swift b/Sources/HTML/LinkProvider.swift
new file mode 100644
index 0000000000..826f60a4f5
--- /dev/null
+++ b/Sources/HTML/LinkProvider.swift
@@ -0,0 +1,63 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+package import Foundation
+
+/// A type that provides information about other pages, and on-page elements, that the rendered page references.
+package protocol LinkProvider {
+    /// Provide information about another page or on-page element, or `nil` if the other page can't be found.
+    func element(for path: URL) -> LinkedElement?
+    
+    /// Provide information about an asset, or `nil` if the asset can't be found.
+    func assetNamed(_ assetName: String) -> LinkedAsset?
+}
+
+package struct LinkedElement {
+    /// The path within the output archive to the linked element.
+    package var path: URL
+    /// The names of the linked element.
+    ///
+    /// Articles, headings, tutorials, and similar pages have a ``Names/single/conceptual(_:)`` name.
+    /// Symbols can either have a ``Names/single/symbol(_:)`` name or have different names for each language representation (``Names/languageSpecificSymbol``).
+    package var names: Names
+    
+    package init(path: URL, names: Names) {
+        self.path = path
+        self.names = names
+    }
+    
+    package enum Names {
+        /// This element has the same name in all language representations
+        case single(Name)
+        /// This element is a symbol with different names in different languages.
+        ///
+        /// Because `@DisplayName` applies to all language representations, these language specific names are always the symbol's subheading declaration and should display in a monospaced font.
+        case languageSpecificSymbol([String /* Language ID */: String])
+    }
+    package enum Name {
+        /// The name refers to an article, heading, or custom `@DisplayName` and should display as regular text.
+        case conceptual(String)
+        /// The name refers to a symbol's subheading declaration and should display in a monospaced font.
+        case symbol(String)
+    }
+}
+
+package struct LinkedAsset {
+    /// The path within the output archive to each image variant, by their light/dark style.
+    package var images: [ColorStyle: [Int /* display scale*/: URL]]
+    
+    package init(images: [ColorStyle : [Int : URL]]) {
+        self.images = images
+    }
+    
+    package enum ColorStyle: String {
+        case light, dark
+    }
+}
diff --git a/Sources/HTML/MarkupRenderer.swift b/Sources/HTML/MarkupRenderer.swift
index 8035bce00d..63fec3598a 100644
--- a/Sources/HTML/MarkupRenderer.swift
+++ b/Sources/HTML/MarkupRenderer.swift
@@ -11,58 +11,6 @@
 package import Foundation
 package import Markdown
 
-/// A type that provides information about other pages, and on-page elements, that the rendered page references.
-package protocol LinkProvider {
-    /// Provide information about another page or on-page element, or `nil` if the other page can't be found.
-    func element(for path: URL) -> LinkedElement?
-    
-    /// Provide information about an asset, or `nil` if the asset can't be found.
-    func assetNamed(_ assetName: String) -> LinkedAsset?
-}
-
-package struct LinkedElement {
-    /// The path within the output archive to the linked element.
-    package var path: URL
-    /// The names of the linked element.
-    ///
-    /// Articles, headings, tutorials, and similar pages have a ``Names/single/conceptual(_:)`` name.
-    /// Symbols can either have a ``Names/single/symbol(_:)`` name or have different names for each language representation (``Names/languageSpecificSymbol``).
-    package var names: Names
-    
-    package init(path: URL, names: Names) {
-        self.path = path
-        self.names = names
-    }
-    
-    package enum Names {
-        /// This element has the same name in all language representations
-        case single(Name)
-        /// This element is a symbol with different names in different languages.
-        ///
-        /// Because `@DisplayName` applies to all language representations, these language specific names are always the symbol's subheading declaration and should display in a monospaced font.
-        case languageSpecificSymbol([String /* Language ID */: String])
-    }
-    package enum Name {
-        /// The name refers to an article, heading, or custom `@DisplayName` and should display as regular text.
-        case conceptual(String)
-        /// The name refers to a symbol's subheading declaration and should display in a monospaced font.
-        case symbol(String)
-    }
-}
-
-package struct LinkedAsset {
-    /// The path within the output archive to each image variant, by their light/dark style.
-    package var images: [ColorStyle: [Int /* display scale*/: URL]]
-    
-    package init(images: [ColorStyle : [Int : URL]]) {
-        self.images = images
-    }
-    
-    package enum ColorStyle: String {
-        case light, dark
-    }
-}
-
 package struct MarkupRenderer<Provider: LinkProvider> {
     /// The path within the output archive to the page that this renderer renders.
     let path: URL

From fa943e1ac1defa5e09db68c50eabb22c2e778633 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 11 Oct 2025 13:31:02 +0200
Subject: [PATCH 20/68] Add subheadings and abstract to HTML.LinkedElement (for
 topics sections)

---
 Sources/HTML/LinkProvider.swift               | 51 ++++++++++++++-
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 38 ++++++++++-
 .../MarkupRenderer+PageElementsTests.swift    | 27 +++++++-
 Tests/HTMLTests/MarkupRendererTests.swift     | 64 ++++++++++++-------
 4 files changed, 150 insertions(+), 30 deletions(-)

diff --git a/Sources/HTML/LinkProvider.swift b/Sources/HTML/LinkProvider.swift
index 826f60a4f5..ea78fef41a 100644
--- a/Sources/HTML/LinkProvider.swift
+++ b/Sources/HTML/LinkProvider.swift
@@ -9,6 +9,7 @@
 */
 
 package import Foundation
+package import Markdown
 
 /// A type that provides information about other pages, and on-page elements, that the rendered page references.
 package protocol LinkProvider {
@@ -22,17 +23,27 @@ package protocol LinkProvider {
 package struct LinkedElement {
     /// The path within the output archive to the linked element.
     package var path: URL
-    /// The names of the linked element.
+    /// The names of the linked element, for display when the element is referenced in inline content.
     ///
     /// Articles, headings, tutorials, and similar pages have a ``Names/single/conceptual(_:)`` name.
     /// Symbols can either have a ``Names/single/symbol(_:)`` name or have different names for each language representation (``Names/languageSpecificSymbol``).
     package var names: Names
-    
-    package init(path: URL, names: Names) {
+    /// The subheadings of the linked element, for display when the element is referenced in either a Topics section, See Also section, or in a `@Links` directive.
+    ///
+    /// Articles, headings, tutorials, and similar pages have a ``Names/single/conceptual(_:)`` name.
+    /// Symbols can either have a ``Names/single/symbol(_:)`` name or have different names for each language representation (``Names/languageSpecificSymbol``).
+    package var subheadings: Subheadings
+    /// The abstract of the page—to be displayed in either a Topics section, See Also section, or in a `@Links` directive—or `nil` if the linked element doesn't have an abstract.
+    package var abstract: Paragraph?
+
+    package init(path: URL, names: Names, subheadings: Subheadings, abstract: Paragraph?) {
         self.path = path
         self.names = names
+        self.subheadings = subheadings
+        self.abstract = abstract
     }
     
+    /// The single name or language-specific names to use when referring to a linked element in inline content.
     package enum Names {
         /// This element has the same name in all language representations
         case single(Name)
@@ -47,6 +58,40 @@ package struct LinkedElement {
         /// The name refers to a symbol's subheading declaration and should display in a monospaced font.
         case symbol(String)
     }
+    
+    /// The single subheading or language-specific subheadings to use when referring to a linked element in either a Topics section, See Also section, or in a `@Links` directive.
+    package enum Subheadings {
+        /// This element has the same name in all language representations
+        case single(Subheading)
+        /// This element is a symbol with different names in different languages.
+        ///
+        /// Because `@DisplayName` applies to all language representations, these language specific names are always the symbol's subheading declaration and should display in a monospaced font.
+        case languageSpecificSymbol([String /* Language ID */: [SymbolNameFragment]])
+    }
+    package enum Subheading {
+        /// The name refers to an article, heading, or custom `@DisplayName` and should display as regular text.
+        case conceptual(String)
+        /// The name refers to a symbol's subheading declaration and should display in a monospaced font.
+        case symbol([SymbolNameFragment])
+    }
+    
+    /// A fragment in a symbol's name
+    package struct SymbolNameFragment {
+        /// The textual spelling of this fragment
+        package var text: String
+        /// The kind of fragment
+        package var kind: Kind
+        
+        /// The display kind of a single  symbol name fragment
+        package enum Kind: String {
+            case identifier, decorator
+        }
+        
+        package init(text: String, kind: Kind) {
+            self.text = text
+            self.kind = kind
+        }
+    }
 }
 
 package struct LinkedAsset {
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 2827ed2a34..f02ecd2ad8 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -57,9 +57,45 @@ private struct ContextLinkProvider: HTML.LinkProvider {
             names = .single(name)
         }
         
+        func convert(_ fragments: [SymbolGraph.Symbol.DeclarationFragments.Fragment]) -> [LinkedElement.SymbolNameFragment] {
+            // FIXME: Join series of tokens of the same identifier/decorator kind to reduce number of tags in the output
+            fragments.map {
+                let kind: LinkedElement.SymbolNameFragment.Kind = switch $0.kind {
+                    case .identifier, .externalParameter: .identifier
+                    default:                              .decorator
+                }
+                
+                return LinkedElement.SymbolNameFragment(text: $0.spelling, kind: kind)
+            }
+        }
+        
+        let subheadings: HTML.LinkedElement.Subheadings
+        if let symbol = node.semantic as? Symbol {
+            let primarySubheading = symbol.subHeading
+            let allSubheadings = symbol.subHeadingVariants.allValues
+            
+            if allSubheadings.contains(where: { _, title in title != primarySubheading }) {
+                // This symbol has multiple unique names
+                subheadings = .languageSpecificSymbol(.init(
+                    allSubheadings.map { trait, subheading in (
+                        key:   (trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift).id,
+                        value: convert(subheading)
+                    )},
+                    uniquingKeysWith: { _, new in new }
+                ))
+            } else {
+                // There are multiple names, but the're all the same
+                subheadings = .single(.symbol(convert(primarySubheading ?? [])))
+            }
+        } else {
+            subheadings = .single(.conceptual(node.name.plainText))
+        }
+        
         return .init(
             path: Self.filePath(for: node.reference),
-            names: names
+            names: names,
+            subheadings: subheadings,
+            abstract: (node.semantic as? (any Abstracted))?.abstract
         )
     }
     
diff --git a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
index f434564c16..eea234ef82 100644
--- a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
+++ b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
@@ -20,14 +20,27 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         let elements = [
             LinkedElement(
                 path: URL(string: "/documentation/ModuleName/index.html")!,
-                names: .single(.symbol("ModuleName"))
+                names: .single(.symbol("ModuleName")),
+                subheadings: .single(.symbol([.init(text: "ModuleName", kind: .identifier)])),
+                abstract: nil
             ),
             LinkedElement(
                 path: URL(string: "/documentation/ModuleName/Something/index.html")!,
                 names: .languageSpecificSymbol([
                     "swift": "Something",
                     "occ": "TLASomething",
-                ])
+                ]),
+                subheadings: .languageSpecificSymbol([
+                    "swift": [
+                        .init(text: "class ", kind: .decorator),
+                        .init(text: "Something", kind: .identifier),
+                    ],
+                    "occ": [
+                        .init(text: "class ", kind: .decorator),
+                        .init(text: "TLASomething", kind: .identifier),
+                    ],
+                ]),
+                abstract: nil
             ),
         ]
         let breadcrumbs = makeRenderer(elementsToReturn: elements).breadcrumbs(references: elements.map { $0.path })
@@ -209,7 +222,15 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         let path = URL(string: "/documentation/ModuleName/Something/ThisPage/index.html")!
         
         var elementsByURL = [
-            path: LinkedElement(path: path, names: .single( .symbol("ThisPage") ))
+            path: LinkedElement(
+                path: path,
+                names: .single( .symbol("ThisPage") ),
+                subheadings: .single( .symbol([
+                    .init(text: "class ", kind: .decorator),
+                    .init(text: "ThisPage", kind: .identifier),
+                ])),
+                abstract: nil
+            )
         ]
         for element in elementsToReturn {
             elementsByURL[element.path] = element
diff --git a/Tests/HTMLTests/MarkupRendererTests.swift b/Tests/HTMLTests/MarkupRendererTests.swift
index 4fbe6bcdb7..c955269092 100644
--- a/Tests/HTMLTests/MarkupRendererTests.swift
+++ b/Tests/HTMLTests/MarkupRendererTests.swift
@@ -340,7 +340,9 @@ final class MarkupRendererTests: XCTestCase {
             rendering: "<doc://com.example.test/documentation/Something/SomeArticle>", // Simulate a link that's been locally resolved already
             elementToReturn: .init(
                 path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeArticle/index.html")),
-                names: .single(.conceptual("Some Article Title"))
+                names: .single(.conceptual("Some Article Title")),
+                subheadings: .single(.conceptual("Some Article Title")), // Not relevant for inline links
+                abstract: nil // Not relevant for inline links
             ),
             prettyFormatted: true,
             matches: """
@@ -355,7 +357,13 @@ final class MarkupRendererTests: XCTestCase {
             rendering: "<doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)>", // Simulate a link that's been locally resolved already
             elementToReturn: .init(
                 path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
-                names: .single(.symbol("someMethod(_:_:)"))
+                names: .single(.symbol("someMethod(_:_:)")),
+                subheadings: .single(.symbol([ // Not relevant for inline links
+                    .init(text: "func ", kind: .decorator),
+                    .init(text: "someMethod", kind: .identifier),
+                    .init(text: "(_:_:)", kind: .decorator),
+                ])),
+                abstract: nil // Not relevant for inline links
             ),
             prettyFormatted: true,
             matches: """
@@ -373,13 +381,7 @@ final class MarkupRendererTests: XCTestCase {
         // Link to symbol with multiple language representation
         try assert(
             rendering: "<doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)>", // Simulate a link that's been locally resolved already
-            elementToReturn: .init(
-                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
-                names: .languageSpecificSymbol([
-                    SourceLanguage.swift.id : "doSomething(with:and:)",
-                    SourceLanguage.objectiveC.id: "doSomethingWithFirst:andSecond:",
-                ])
-            ),
+            elementToReturn: makeExampleMethodWithDifferentLanguageRepresentations(),
             prettyFormatted: true,
             matches: """
             <p>
@@ -402,13 +404,7 @@ final class MarkupRendererTests: XCTestCase {
         // Link with custom title
         try assert(
             rendering: "[Custom _formatted_ title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
-            elementToReturn: .init(
-                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
-                names: .languageSpecificSymbol([
-                    SourceLanguage.swift.id : "doSomething(with:and:)",
-                    SourceLanguage.objectiveC.id: "doSomethingWithFirst:andSecond:",
-                ])
-            ),
+            elementToReturn: makeExampleMethodWithDifferentLanguageRepresentations(),
             matches: """
             <p><a href="../../SomeClass/someMethod(_:_:)/index.html">Custom <i>formatted</i> title</a></p>
             """
@@ -417,13 +413,7 @@ final class MarkupRendererTests: XCTestCase {
         // Link with custom symbol-like title
         try assert(
             rendering: "[Some `CustomSymbolName` title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
-            elementToReturn: .init(
-                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
-                names: .languageSpecificSymbol([
-                    SourceLanguage.swift.id : "doSomething(with:and:)",
-                    SourceLanguage.objectiveC.id: "doSomethingWithFirst:andSecond:",
-                ])
-            ),
+            elementToReturn: makeExampleMethodWithDifferentLanguageRepresentations(),
             matches: """
             <p><a href="../../SomeClass/someMethod(_:_:)/index.html">Some <code>Custom<wbr/>Symbol<wbr/>Name</code> title</a></p>
             """
@@ -532,6 +522,34 @@ final class MarkupRendererTests: XCTestCase {
         
         XCTAssertEqual(htmlString, expectedHTML, file: file, line: line)
     }
+    
+    private func makeExampleMethodWithDifferentLanguageRepresentations()  -> LinkedElement {
+        LinkedElement(
+            path: URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")!,
+            names: .languageSpecificSymbol([
+                SourceLanguage.swift.id : "doSomething(with:and:)",
+                SourceLanguage.objectiveC.id: "doSomethingWithFirst:andSecond:",
+            ]),
+            subheadings: .languageSpecificSymbol([ // Not relevant for inline links
+                SourceLanguage.swift.id: [
+                    .init(text: "func ", kind: .decorator),
+                    .init(text: "doSomething", kind: .identifier),
+                    .init(text: "(", kind: .decorator),
+                    .init(text: "with", kind: .identifier),
+                    .init(text: ":", kind: .decorator),
+                    .init(text: "and", kind: .identifier),
+                    .init(text: ")", kind: .decorator),
+                ],
+                SourceLanguage.objectiveC.id: [
+                    .init(text: "doSomethingWithFirst", kind: .identifier),
+                    .init(text: ":", kind: .decorator),
+                    .init(text: "andSecond", kind: .identifier),
+                    .init(text: ":", kind: .decorator),
+                ]
+            ]),
+            abstract: nil // Not relevant for inline links
+        )
+    }
 }
 
 // MARK: Helpers

From e9febe075d9c3c625085864d5e27e3ab1b3c9502 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 11 Oct 2025 13:38:36 +0200
Subject: [PATCH 21/68] Avoid emitting multiple subheading fragments of the
 same kind in a row

---
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 23 +++++++++++++++----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index f02ecd2ad8..38521c78ac 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -58,15 +58,28 @@ private struct ContextLinkProvider: HTML.LinkProvider {
         }
         
         func convert(_ fragments: [SymbolGraph.Symbol.DeclarationFragments.Fragment]) -> [LinkedElement.SymbolNameFragment] {
-            // FIXME: Join series of tokens of the same identifier/decorator kind to reduce number of tags in the output
-            fragments.map {
-                let kind: LinkedElement.SymbolNameFragment.Kind = switch $0.kind {
+            func convert(kind: SymbolGraph.Symbol.DeclarationFragments.Fragment.Kind) -> LinkedElement.SymbolNameFragment.Kind {
+                switch kind {
                     case .identifier, .externalParameter: .identifier
                     default:                              .decorator
                 }
-                
-                return LinkedElement.SymbolNameFragment(text: $0.spelling, kind: kind)
             }
+            guard var current = fragments.first.map({ LinkedElement.SymbolNameFragment(text: $0.spelling, kind: convert(kind: $0.kind)) }) else {
+                return []
+            }
+            
+            var result: [LinkedElement.SymbolNameFragment] = []
+            
+            for fragment in fragments.dropFirst() {
+                let kind = convert(kind: fragment.kind)
+                if kind == current.kind  {
+                    current.text += fragment.spelling
+                } else {
+                    result.append(current)
+                    current = .init(text: fragment.spelling, kind: kind)
+                }
+            }
+            return result
         }
         
         let subheadings: HTML.LinkedElement.Subheadings

From d1202a5429ee42ef968b2f6d5e6dae5d6f0c62c4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 11 Oct 2025 14:36:40 +0200
Subject: [PATCH 22/68] Add test for rendering symbol declarations

---
 Package.swift                                 |   1 +
 Sources/HTML/LinkProvider.swift               |   3 +
 Sources/HTML/MarkupRenderer+Declaration.swift |  61 ++++++++
 .../Model/Rendering/HTML/HTMLRenderer.swift   |  10 +-
 .../MarkupRenderer+PageElementsTests.swift    | 139 ++++++++++++++++++
 Tests/HTMLTests/MarkupRendererTests.swift     |   5 +
 6 files changed, 217 insertions(+), 2 deletions(-)
 create mode 100644 Sources/HTML/MarkupRenderer+Declaration.swift

diff --git a/Package.swift b/Package.swift
index 53fc665579..1713f4bc95 100644
--- a/Package.swift
+++ b/Package.swift
@@ -93,6 +93,7 @@ let package = Package(
             name: "HTML",
             dependencies: [
                 .product(name: "Markdown", package: "swift-markdown"),
+                .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
             ],
             swiftSettings: swiftSettings
         ),
diff --git a/Sources/HTML/LinkProvider.swift b/Sources/HTML/LinkProvider.swift
index ea78fef41a..565ab11864 100644
--- a/Sources/HTML/LinkProvider.swift
+++ b/Sources/HTML/LinkProvider.swift
@@ -16,6 +16,9 @@ package protocol LinkProvider {
     /// Provide information about another page or on-page element, or `nil` if the other page can't be found.
     func element(for path: URL) -> LinkedElement?
     
+    /// Provide the path for a symbol based on its unique identifier, or `nil` if the other symbol with that identifier can't be found.
+    func pathForSymbolID(_ usr: String) -> URL?
+    
     /// Provide information about an asset, or `nil` if the asset can't be found.
     func assetNamed(_ assetName: String) -> LinkedAsset?
 }
diff --git a/Sources/HTML/MarkupRenderer+Declaration.swift b/Sources/HTML/MarkupRenderer+Declaration.swift
new file mode 100644
index 0000000000..4df5b0d96a
--- /dev/null
+++ b/Sources/HTML/MarkupRenderer+Declaration.swift
@@ -0,0 +1,61 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+package import Foundation
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+package import FoundationXML
+#endif
+
+package import SymbolKit
+
+package extension MarkupRenderer {
+ 
+    typealias DeclarationFragment = SymbolGraph.Symbol.DeclarationFragments.Fragment
+    
+    func declaration(_ fragmentsByLanguage: [String /* Language ID*/: [DeclarationFragment]]) -> XMLElement {
+        let fragmentsByLanguage = RenderHelpers.sortedLanguageSpecificValues(fragmentsByLanguage)
+        // Note: declarations scroll, so they don't need to word wrap within tokens
+        
+        let declarations: [XMLElement] = if fragmentsByLanguage.count == 1 {
+            [XMLNode.element(named: "code", children: _declarationTokens(for: fragmentsByLanguage.first!.value))]
+        } else {
+            fragmentsByLanguage.map { languageID, fragments in
+                XMLNode.element(named: "code", children: _declarationTokens(for: fragments), attributes: ["class": "\(languageID)-only"])
+            }
+        }
+        return .element(named: "pre", children: declarations, attributes: ["id": "declaration"])
+    }
+    
+    private func _declarationTokens(for fragments: [DeclarationFragment]) -> [XMLNode] {
+        // FIXME: Pretty print declarations for Swift and Objective-C
+        
+        fragments.map { fragment in
+            let elementClass = "token-\(fragment.kind.rawValue)"
+            
+            if fragment.kind == .typeIdentifier,
+               let symbolID = fragment.preciseIdentifier,
+               let reference = linkProvider.pathForSymbolID(symbolID)
+            {
+                // Make a link
+                return .element(named: "a", children: [.text(fragment.spelling)], attributes: [
+                    "href": path(to: reference),
+                    "class": elementClass
+                ])
+            }
+            else if fragment.kind == .text {
+                // ???: Does text need a <span> element?
+                return .text(fragment.spelling)
+            } else {
+                return .element(named: "span", children: [.text(fragment.spelling)], attributes: ["class": elementClass])
+            }
+        }
+    }
+}
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 38521c78ac..faf0ea0115 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -112,6 +112,12 @@ private struct ContextLinkProvider: HTML.LinkProvider {
         )
     }
     
+    func pathForSymbolID(_ usr: String) -> URL? {
+        context.localOrExternalReference(symbolID: usr).map {
+            Self.filePath(for: $0)
+        }
+    }
+    
     func assetNamed(_ assetName: String) -> HTML.LinkedAsset? {
         guard let asset = context.resolveAsset(named: assetName, in: reference) else {
             return nil
@@ -244,7 +250,7 @@ struct HTMLRenderer {
             separateCurationIfNeeded()
             articleElement.addChild(makeGroupedSection(seeAlso))
         }
-        if let taskGroup = AutomaticCuration.seeAlso(for: node, withTraits: [.swift, .objectiveC], context: context, bundle: context.bundle, renderContext: renderContext, renderer: .init(documentationContext: context, bundle: context.bundle)) {
+        if let taskGroup = AutomaticCuration.seeAlso(for: node, withTraits: [.swift, .objectiveC], context: context, renderContext: renderContext, renderer: .init(context: context)) {
             separateCurationIfNeeded()
             // Automatice SeeAlso
             let section = XMLElement(name: "section")
@@ -520,7 +526,7 @@ struct HTMLRenderer {
             articleElement.addChild(makeGroupedSection(seeAlso))
         }
         
-        if let taskGroup = AutomaticCuration.seeAlso(for: node, withTraits: [.swift, .objectiveC], context: context, bundle: context.bundle, renderContext: renderContext, renderer: .init(documentationContext: context, bundle: context.bundle)) {
+        if let taskGroup = AutomaticCuration.seeAlso(for: node, withTraits: [.swift, .objectiveC], context: context, renderContext: renderContext, renderer: .init(context: context)) {
             // Automatice SeeAlso
             let section = XMLElement(name: "section")
             separateCurationIfNeeded()
diff --git a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
index eea234ef82..4412b9ad8a 100644
--- a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
+++ b/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
@@ -211,10 +211,143 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         """)
     }
     
+    func testRenderSwiftDeclaration() throws {
+        let symbolPaths = [
+            "first-parameter-symbol-id":  URL(string: "/documentation/ModuleName/FirstParameterValue/index.html")!,
+            "second-parameter-symbol-id": URL(string: "/documentation/ModuleName/SecondParameterValue/index.html")!,
+            "return-value-symbol-id":     URL(string: "/documentation/ModuleName/ReturnValue/index.html")!,
+        ]
+        
+        let declaration = makeRenderer(pathsToReturn: symbolPaths).declaration([
+            "swift":  [
+                .init(kind: .keyword,           spelling: "func",        preciseIdentifier: nil),
+                .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
+                .init(kind: .identifier,        spelling: "doSomething", preciseIdentifier: nil),
+                .init(kind: .text,              spelling: "(",           preciseIdentifier: nil),
+                .init(kind: .externalParameter, spelling: "with",        preciseIdentifier: nil),
+                .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
+                .init(kind: .internalParameter, spelling: "first",       preciseIdentifier: nil),
+                .init(kind: .text,              spelling: ": ",          preciseIdentifier: nil),
+                .init(kind: .typeIdentifier,    spelling: "FirstParameterValue", preciseIdentifier: "first-parameter-symbol-id"),
+                .init(kind: .text,              spelling: ", ",          preciseIdentifier: nil),
+                .init(kind: .externalParameter, spelling: "and",         preciseIdentifier: nil),
+                .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
+                .init(kind: .internalParameter, spelling: "second",      preciseIdentifier: nil),
+                .init(kind: .text,              spelling: ": ",          preciseIdentifier: nil),
+                .init(kind: .typeIdentifier,    spelling: "SecondParameterValue", preciseIdentifier: "second-parameter-symbol-id"),
+                .init(kind: .text,              spelling: ") ",          preciseIdentifier: nil),
+                .init(kind: .keyword,           spelling: "throws",      preciseIdentifier: nil),
+                .init(kind: .text,              spelling: "-> ",         preciseIdentifier: nil),
+                .init(kind: .typeIdentifier,    spelling: "ReturnValue", preciseIdentifier: "return-value-symbol-id"),
+            ]
+        ])
+        XCTAssertEqual(declaration.rendered(prettyFormatted: true), """
+        <pre id="declaration">
+        <code>
+            <span class="token-keyword">func</span>
+             <span class="token-identifier">doSomething</span>
+            (<span class="token-externalParam">with</span>
+             <span class="token-internalParam">first</span>
+            : <a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
+            , <span class="token-externalParam">and</span>
+             <span class="token-internalParam">second</span>
+            : <a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
+            ) <span class="token-keyword">throws</span>
+            -&gt; <a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
+        </code>
+        </pre>
+        """)
+    }
+    
+    func testRenderLanguageSpecificDeclarations() throws {
+        let symbolPaths = [
+            "first-parameter-symbol-id":  URL(string: "/documentation/ModuleName/FirstParameterValue/index.html")!,
+            "second-parameter-symbol-id": URL(string: "/documentation/ModuleName/SecondParameterValue/index.html")!,
+            "return-value-symbol-id":     URL(string: "/documentation/ModuleName/ReturnValue/index.html")!,
+            "error-parameter-symbol-id":  URL(string: "/documentation/Foundation/NSError/index.html")!,
+        ]
+        
+        let declaration = makeRenderer(pathsToReturn: symbolPaths).declaration([
+            "swift":  [
+                .init(kind: .keyword,           spelling: "func",        preciseIdentifier: nil),
+                .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
+                .init(kind: .identifier,        spelling: "doSomething", preciseIdentifier: nil),
+                .init(kind: .text,              spelling: "(",           preciseIdentifier: nil),
+                .init(kind: .externalParameter, spelling: "with",        preciseIdentifier: nil),
+                .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
+                .init(kind: .internalParameter, spelling: "first",       preciseIdentifier: nil),
+                .init(kind: .text,              spelling: ": ",          preciseIdentifier: nil),
+                .init(kind: .typeIdentifier,    spelling: "FirstParameterValue", preciseIdentifier: "first-parameter-symbol-id"),
+                .init(kind: .text,              spelling: ", ",          preciseIdentifier: nil),
+                .init(kind: .externalParameter, spelling: "and",         preciseIdentifier: nil),
+                .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
+                .init(kind: .internalParameter, spelling: "second",      preciseIdentifier: nil),
+                .init(kind: .text,              spelling: ": ",          preciseIdentifier: nil),
+                .init(kind: .typeIdentifier,    spelling: "SecondParameterValue", preciseIdentifier: "second-parameter-symbol-id"),
+                .init(kind: .text,              spelling: ") ",          preciseIdentifier: nil),
+                .init(kind: .keyword,           spelling: "throws",      preciseIdentifier: nil),
+                .init(kind: .text,              spelling: "-> ",         preciseIdentifier: nil),
+                .init(kind: .typeIdentifier,    spelling: "ReturnValue", preciseIdentifier: "return-value-symbol-id"),
+            ],
+            
+            "occ":  [
+                .init(kind: .text,              spelling: "- (",         preciseIdentifier: nil),
+                .init(kind: .typeIdentifier,    spelling: "ReturnValue", preciseIdentifier: "return-value-symbol-id"),
+                .init(kind: .text,              spelling: ") ",          preciseIdentifier: nil),
+                .init(kind: .identifier,        spelling: "doSomethingWithFirst", preciseIdentifier: nil),
+                .init(kind: .text,              spelling: ": (",         preciseIdentifier: nil),
+                .init(kind: .typeIdentifier,    spelling: "FirstParameterValue", preciseIdentifier: "first-parameter-symbol-id"),
+                .init(kind: .text,              spelling: ") ",          preciseIdentifier: nil),
+                .init(kind: .internalParameter, spelling: "first",       preciseIdentifier: nil),
+                .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
+                .init(kind: .identifier,        spelling: "andSecond",   preciseIdentifier: nil),
+                .init(kind: .text,              spelling: ": (",         preciseIdentifier: nil),
+                .init(kind: .typeIdentifier,    spelling: "SecondParameterValue", preciseIdentifier: "second-parameter-symbol-id"),
+                .init(kind: .text,              spelling: ") ",          preciseIdentifier: nil),
+                .init(kind: .internalParameter, spelling: "second",      preciseIdentifier: nil),
+                .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
+                .init(kind: .identifier,        spelling: "error",       preciseIdentifier: nil),
+                .init(kind: .text,              spelling: ": (",         preciseIdentifier: nil),
+                .init(kind: .typeIdentifier,    spelling: "NSError",     preciseIdentifier: "error-parameter-symbol-id"),
+                .init(kind: .text,              spelling: " **) ",       preciseIdentifier: nil),
+                .init(kind: .internalParameter, spelling: "error",       preciseIdentifier: nil),
+                .init(kind: .text,              spelling: ";",           preciseIdentifier: nil),
+            ]
+        ])
+        XCTAssertEqual(declaration.rendered(prettyFormatted: true), """
+        <pre id="declaration">
+        <code class="swift-only">
+            <span class="token-keyword">func</span>
+             <span class="token-identifier">doSomething</span>
+            (<span class="token-externalParam">with</span>
+             <span class="token-internalParam">first</span>
+            : <a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
+            , <span class="token-externalParam">and</span>
+             <span class="token-internalParam">second</span>
+            : <a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
+            ) <span class="token-keyword">throws</span>
+            -&gt; <a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
+        </code>
+        <code class="occ-only">- (<a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
+            ) <span class="token-identifier">doSomethingWithFirst</span>
+            : (<a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
+            ) <span class="token-internalParam">first</span>
+             <span class="token-identifier">andSecond</span>
+            : (<a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
+            ) <span class="token-internalParam">second</span>
+             <span class="token-identifier">error</span>
+            : (<a class="token-typeIdentifier" href="../../../../Foundation/NSError/index.html">NSError</a>
+             **) <span class="token-internalParam">error</span>
+            ;</code>
+        </pre>
+        """)
+    }
+    
     // MARK: -
     
     private func makeRenderer(
         elementsToReturn: [LinkedElement] = [],
+        pathsToReturn: [String: URL] = [:],
         assetsToReturn: [String: LinkedAsset] = [:],
         file: StaticString = #filePath,
         line: UInt = #line
@@ -240,6 +373,7 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
             path: path,
             linkProvider: MultiValueLinkProvider(
                 elementsToReturn: elementsByURL,
+                pathsToReturn: pathsToReturn,
                 assetsToReturn: assetsToReturn
             )
         )
@@ -257,6 +391,11 @@ struct MultiValueLinkProvider: LinkProvider {
         elementsToReturn[path]
     }
     
+    var pathsToReturn: [String: URL]
+    func pathForSymbolID(_ usr: String) -> URL? {
+        pathsToReturn[usr]
+    }
+    
     var assetsToReturn: [String: LinkedAsset]
     func assetNamed(_ assetName: String) -> LinkedAsset? {
         assetsToReturn[assetName]
diff --git a/Tests/HTMLTests/MarkupRendererTests.swift b/Tests/HTMLTests/MarkupRendererTests.swift
index c955269092..a5246f6fb9 100644
--- a/Tests/HTMLTests/MarkupRendererTests.swift
+++ b/Tests/HTMLTests/MarkupRendererTests.swift
@@ -577,6 +577,11 @@ struct SingleValueLinkProvider: LinkProvider {
         elementToReturn
     }
     
+    var pathToReturn: URL?
+    func pathForSymbolID(_ usr: String) -> URL? {
+        pathToReturn
+    }
+    
     var assetToReturn: LinkedAsset?
     func assetNamed(_ assetName: String) -> LinkedAsset? {
         assetToReturn

From 51c88d2750c9c78309458bb5230467855701d8bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Sat, 11 Oct 2025 14:44:34 +0200
Subject: [PATCH 23/68] Use new declaration function when rendering pages.

---
 .../Model/Rendering/HTML/HTMLRenderer.swift          | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index faf0ea0115..5fb7059081 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -368,6 +368,18 @@ struct HTMLRenderer {
         }
         
         // Declaration
+        if !symbol.declarationVariants.allValues.isEmpty {
+            // FIXME: Display platform specific declarations
+            
+            var fragmentsByLanguageID = [String: [SymbolGraph.Symbol.DeclarationFragments.Fragment]]()
+            for (trait, variant) in symbol.declarationVariants.allValues {
+                guard let languageID = trait.interfaceLanguage else { continue }
+                fragmentsByLanguageID[languageID] = variant.values.first?.declarationFragments
+            }
+            
+            hero.addChild( renderer.declaration(fragmentsByLanguageID) )
+        }
+        
         for (trait, variant) in symbol.declarationVariants.allValues.sorted(by: { $0.trait < $1.trait}) {
             guard let lang = trait.interfaceLanguage else { continue }
             

From 711a07f50872c5bc4d018f8ca72c4b894aec8cc7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 20 Nov 2025 11:33:25 +0000
Subject: [PATCH 24/68] Add DocC prefix to new HTML target

---
 Package.swift                                    |  8 ++++----
 Sources/{HTML => DocCHTML}/LinkProvider.swift    |  0
 .../MarkupRenderer+Availability.swift            |  0
 .../MarkupRenderer+Breadcrumbs.swift             |  0
 .../MarkupRenderer+Declaration.swift             |  0
 .../MarkupRenderer+Parameters.swift              |  0
 Sources/{HTML => DocCHTML}/MarkupRenderer.swift  |  0
 Sources/{HTML => DocCHTML}/WordBreak.swift       |  0
 Sources/{HTML => DocCHTML}/XMLNode+element.swift |  0
 .../Model/Rendering/HTML/HTMLRenderer.swift      | 16 ++++++++--------
 .../MarkupRenderer+PageElementsTests.swift       |  2 +-
 .../MarkupRendererTests.swift                    |  2 +-
 .../WordBreakTests.swift                         |  2 +-
 13 files changed, 15 insertions(+), 15 deletions(-)
 rename Sources/{HTML => DocCHTML}/LinkProvider.swift (100%)
 rename Sources/{HTML => DocCHTML}/MarkupRenderer+Availability.swift (100%)
 rename Sources/{HTML => DocCHTML}/MarkupRenderer+Breadcrumbs.swift (100%)
 rename Sources/{HTML => DocCHTML}/MarkupRenderer+Declaration.swift (100%)
 rename Sources/{HTML => DocCHTML}/MarkupRenderer+Parameters.swift (100%)
 rename Sources/{HTML => DocCHTML}/MarkupRenderer.swift (100%)
 rename Sources/{HTML => DocCHTML}/WordBreak.swift (100%)
 rename Sources/{HTML => DocCHTML}/XMLNode+element.swift (100%)
 rename Tests/{HTMLTests => DocCHTMLTests}/MarkupRenderer+PageElementsTests.swift (99%)
 rename Tests/{HTMLTests => DocCHTMLTests}/MarkupRendererTests.swift (99%)
 rename Tests/{HTMLTests => DocCHTMLTests}/WordBreakTests.swift (99%)

diff --git a/Package.swift b/Package.swift
index c10c4021d5..68480e59d8 100644
--- a/Package.swift
+++ b/Package.swift
@@ -44,7 +44,7 @@ let package = Package(
             name: "SwiftDocC",
             dependencies: [
                 .target(name: "DocCCommon"),
-                .target(name: "HTML"),
+                .target(name: "DocCHTML"),
                 .product(name: "Markdown", package: "swift-markdown"),
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
                 .product(name: "CLMDB", package: "swift-lmdb"),
@@ -136,7 +136,7 @@ let package = Package(
         ),
 
         .target(
-            name: "HTML",
+            name: "DocCHTML",
             dependencies: [
                 .product(name: "Markdown", package: "swift-markdown"),
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
@@ -144,9 +144,9 @@ let package = Package(
             swiftSettings: swiftSettings
         ),
         .testTarget(
-            name: "HTMLTests",
+            name: "DocCHTMLTests",
             dependencies: [
-                .target(name: "HTML"),
+                .target(name: "DocCHTML"),
                 .target(name: "SwiftDocC"),
                 .product(name: "Markdown", package: "swift-markdown"),
                 .target(name: "SwiftDocCTestUtilities"),
diff --git a/Sources/HTML/LinkProvider.swift b/Sources/DocCHTML/LinkProvider.swift
similarity index 100%
rename from Sources/HTML/LinkProvider.swift
rename to Sources/DocCHTML/LinkProvider.swift
diff --git a/Sources/HTML/MarkupRenderer+Availability.swift b/Sources/DocCHTML/MarkupRenderer+Availability.swift
similarity index 100%
rename from Sources/HTML/MarkupRenderer+Availability.swift
rename to Sources/DocCHTML/MarkupRenderer+Availability.swift
diff --git a/Sources/HTML/MarkupRenderer+Breadcrumbs.swift b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
similarity index 100%
rename from Sources/HTML/MarkupRenderer+Breadcrumbs.swift
rename to Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
diff --git a/Sources/HTML/MarkupRenderer+Declaration.swift b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
similarity index 100%
rename from Sources/HTML/MarkupRenderer+Declaration.swift
rename to Sources/DocCHTML/MarkupRenderer+Declaration.swift
diff --git a/Sources/HTML/MarkupRenderer+Parameters.swift b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
similarity index 100%
rename from Sources/HTML/MarkupRenderer+Parameters.swift
rename to Sources/DocCHTML/MarkupRenderer+Parameters.swift
diff --git a/Sources/HTML/MarkupRenderer.swift b/Sources/DocCHTML/MarkupRenderer.swift
similarity index 100%
rename from Sources/HTML/MarkupRenderer.swift
rename to Sources/DocCHTML/MarkupRenderer.swift
diff --git a/Sources/HTML/WordBreak.swift b/Sources/DocCHTML/WordBreak.swift
similarity index 100%
rename from Sources/HTML/WordBreak.swift
rename to Sources/DocCHTML/WordBreak.swift
diff --git a/Sources/HTML/XMLNode+element.swift b/Sources/DocCHTML/XMLNode+element.swift
similarity index 100%
rename from Sources/HTML/XMLNode+element.swift
rename to Sources/DocCHTML/XMLNode+element.swift
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 5fb7059081..5c567f8150 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -13,15 +13,15 @@ import Foundation
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 import FoundationXML
 #endif
-import HTML
+import DocCHTML
 import Markdown
 import SymbolKit
 
-private struct ContextLinkProvider: HTML.LinkProvider {
+private struct ContextLinkProvider: DocCHTML.LinkProvider {
     let reference: ResolvedTopicReference
     let context: DocumentationContext
     
-    func element(for url: URL) -> HTML.LinkedElement? {
+    func element(for url: URL) -> DocCHTML.LinkedElement? {
         guard url.scheme == "doc",
               let rawBundleID = url.host,
               let node = context.documentationCache[ResolvedTopicReference(bundleID: .init(rawValue: rawBundleID), path: url.path, fragment: url.fragment, sourceLanguage: .swift /* The reference's language doesn't matter */)]
@@ -29,7 +29,7 @@ private struct ContextLinkProvider: HTML.LinkProvider {
             return nil
         }
         
-        let names: HTML.LinkedElement.Names
+        let names: DocCHTML.LinkedElement.Names
         if let symbol = node.semantic as? Symbol,
            case .symbol(let primaryTitle) = node.name
         {
@@ -50,7 +50,7 @@ private struct ContextLinkProvider: HTML.LinkProvider {
                 names = .single(.symbol(primaryTitle))
             }
         } else {
-            let name: HTML.LinkedElement.Name = switch node.name {
+            let name: DocCHTML.LinkedElement.Name = switch node.name {
                 case .conceptual(let title):   .conceptual(title)
                 case .symbol(name: let title): .symbol(title)
             }
@@ -82,7 +82,7 @@ private struct ContextLinkProvider: HTML.LinkProvider {
             return result
         }
         
-        let subheadings: HTML.LinkedElement.Subheadings
+        let subheadings: DocCHTML.LinkedElement.Subheadings
         if let symbol = node.semantic as? Symbol {
             let primarySubheading = symbol.subHeading
             let allSubheadings = symbol.subHeadingVariants.allValues
@@ -118,12 +118,12 @@ private struct ContextLinkProvider: HTML.LinkProvider {
         }
     }
     
-    func assetNamed(_ assetName: String) -> HTML.LinkedAsset? {
+    func assetNamed(_ assetName: String) -> DocCHTML.LinkedAsset? {
         guard let asset = context.resolveAsset(named: assetName, in: reference) else {
             return nil
         }
         
-        var images = [HTML.LinkedAsset.ColorStyle: [Int: URL]]()
+        var images = [DocCHTML.LinkedAsset.ColorStyle: [Int: URL]]()
         for (traits, url) in asset.variants {
             let scale = (traits.displayScale ?? .standard).scaleFactor
             
diff --git a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift
similarity index 99%
rename from Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
rename to Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift
index 4412b9ad8a..8fd093cb97 100644
--- a/Tests/HTMLTests/MarkupRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift
@@ -10,7 +10,7 @@
 
 import Foundation
 import XCTest
-import HTML
+import DocCHTML
 @testable import SwiftDocC
 import Markdown
 
diff --git a/Tests/HTMLTests/MarkupRendererTests.swift b/Tests/DocCHTMLTests/MarkupRendererTests.swift
similarity index 99%
rename from Tests/HTMLTests/MarkupRendererTests.swift
rename to Tests/DocCHTMLTests/MarkupRendererTests.swift
index a5246f6fb9..10d6c1d011 100644
--- a/Tests/HTMLTests/MarkupRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkupRendererTests.swift
@@ -10,7 +10,7 @@
 
 import Foundation
 import XCTest
-import HTML
+import DocCHTML
 @testable import SwiftDocC
 import Markdown
 
diff --git a/Tests/HTMLTests/WordBreakTests.swift b/Tests/DocCHTMLTests/WordBreakTests.swift
similarity index 99%
rename from Tests/HTMLTests/WordBreakTests.swift
rename to Tests/DocCHTMLTests/WordBreakTests.swift
index 693af15c1f..fd1cf1203d 100644
--- a/Tests/HTMLTests/WordBreakTests.swift
+++ b/Tests/DocCHTMLTests/WordBreakTests.swift
@@ -10,7 +10,7 @@
 
 import Foundation
 import XCTest
-import HTML
+import DocCHTML
 
 final class WordBreakTests: XCTestCase {
     func testWordBreaks() {

From f1ff73aab321b5e6a3c47175bf9b481e6ca7a152 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 20 Nov 2025 11:45:39 +0000
Subject: [PATCH 25/68] Add CMake list for the new DocCHTML target

---
 Package.swift                    |  2 ++
 Sources/CMakeLists.txt           |  1 +
 Sources/DocCHTML/CMakeLists.txt  | 21 +++++++++++++++++++++
 Sources/SwiftDocC/CMakeLists.txt |  2 ++
 4 files changed, 26 insertions(+)
 create mode 100644 Sources/DocCHTML/CMakeLists.txt

diff --git a/Package.swift b/Package.swift
index 68480e59d8..3d3ae2422d 100644
--- a/Package.swift
+++ b/Package.swift
@@ -123,6 +123,7 @@ let package = Package(
                 // This target shouldn't have any local dependencies so that all other targets can depend on it.
                 // We can add dependencies on SymbolKit and Markdown here but they're not needed yet.
             ],
+            exclude: ["CMakeLists.txt"],
             swiftSettings: [.swiftLanguageMode(.v6)]
         ),
         
@@ -141,6 +142,7 @@ let package = Package(
                 .product(name: "Markdown", package: "swift-markdown"),
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
             ],
+            exclude: ["CMakeLists.txt"],
             swiftSettings: swiftSettings
         ),
         .testTarget(
diff --git a/Sources/CMakeLists.txt b/Sources/CMakeLists.txt
index 840812426a..f021d6df4c 100644
--- a/Sources/CMakeLists.txt
+++ b/Sources/CMakeLists.txt
@@ -8,6 +8,7 @@ See https://swift.org/LICENSE.txt for license information
 #]]
 
 add_subdirectory(DocCCommon)
+add_subdirectory(DocCHTML)
 add_subdirectory(SwiftDocC)
 add_subdirectory(SwiftDocCUtilities)
 add_subdirectory(docc)
diff --git a/Sources/DocCHTML/CMakeLists.txt b/Sources/DocCHTML/CMakeLists.txt
new file mode 100644
index 0000000000..41c84f5c46
--- /dev/null
+++ b/Sources/DocCHTML/CMakeLists.txt
@@ -0,0 +1,21 @@
+#[[
+This source file is part of the Swift open source project
+
+Copyright © 2014 - 2025 Apple Inc. and the Swift project authors
+Licensed under Apache License v2.0 with Runtime Library Exception
+
+See https://swift.org/LICENSE.txt for license information
+#]]
+
+add_library(DocCHTML STATIC
+  LinkProvider.swift
+  MarkupRenderer+Availability.swift
+  MarkupRenderer+Breadcrumbs.swift
+  MarkupRenderer+Declaration.swift
+  MarkupRenderer+Parameters.swift
+  MarkupRenderer.swift
+  WordBreak.swift
+  XMLNode+element.swift)
+target_link_libraries(DocCHTML PUBLIC
+  SwiftMarkdown::Markdown
+  DocC::SymbolKit)
diff --git a/Sources/SwiftDocC/CMakeLists.txt b/Sources/SwiftDocC/CMakeLists.txt
index c5e6ef0e26..ff8bbca0e3 100644
--- a/Sources/SwiftDocC/CMakeLists.txt
+++ b/Sources/SwiftDocC/CMakeLists.txt
@@ -465,6 +465,8 @@ add_library(SwiftDocC
   Utility/Version.swift)
 target_link_libraries(SwiftDocC PRIVATE
   DocCCommon)
+target_link_libraries(SwiftDocC PRIVATE
+  DocCHTML)
 target_link_libraries(SwiftDocC PUBLIC
   SwiftMarkdown::Markdown
   DocC::SymbolKit

From 999291f329b90a54a236aeeedc6e0d76b11592c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 20 Nov 2025 13:24:56 +0000
Subject: [PATCH 26/68] Use Swift 6 language mode for new DocCHTML target

---
 Package.swift | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Package.swift b/Package.swift
index 3d3ae2422d..ceb0f804e6 100644
--- a/Package.swift
+++ b/Package.swift
@@ -143,7 +143,7 @@ let package = Package(
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
             ],
             exclude: ["CMakeLists.txt"],
-            swiftSettings: swiftSettings
+            swiftSettings: [.swiftLanguageMode(.v6)]
         ),
         .testTarget(
             name: "DocCHTMLTests",
@@ -153,7 +153,7 @@ let package = Package(
                 .product(name: "Markdown", package: "swift-markdown"),
                 .target(name: "SwiftDocCTestUtilities"),
             ],
-            swiftSettings: swiftSettings
+            swiftSettings: [.swiftLanguageMode(.v6)]
         ),
 
         // Test app for SwiftDocCUtilities

From ed290c0b0a74990f97d662d1548dc54b50429ac6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 20 Nov 2025 13:36:14 +0000
Subject: [PATCH 27/68] Use Swift Testing for DocCHTMLTests

---
 .../MarkupRenderer+PageElementsTests.swift    |  45 +++----
 Tests/DocCHTMLTests/MarkupRendererTests.swift | 112 +++++++++---------
 Tests/DocCHTMLTests/WordBreakTests.swift      |   9 +-
 3 files changed, 88 insertions(+), 78 deletions(-)

diff --git a/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift
index 8fd093cb97..80b2262aa9 100644
--- a/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift
@@ -9,14 +9,14 @@
 */
 
 import Foundation
-import XCTest
+import Testing
 import DocCHTML
 @testable import SwiftDocC
 import Markdown
 
-final class MarkupRenderer_PageElementsTests: XCTestCase {
-    
-    func testRenderBreadcrumbs() throws {
+struct MarkupRenderer_PageElementsTests {
+    @Test
+    func testRenderBreadcrumbs() {
         let elements = [
             LinkedElement(
                 path: URL(string: "/documentation/ModuleName/index.html")!,
@@ -45,7 +45,7 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         ]
         let breadcrumbs = makeRenderer(elementsToReturn: elements).breadcrumbs(references: elements.map { $0.path })
         
-        XCTAssertEqual(breadcrumbs.rendered(prettyFormatted: true), """
+        #expect(breadcrumbs.rendered(prettyFormatted: true) == """
         <nav id="breadcrumbs">
         <ul>
             <li>
@@ -63,14 +63,14 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         """)
     }
     
-    func testRenderAvailability() throws {
+    @Test
+    func testRenderAvailability() {
         let availability = makeRenderer().availability([
             .init(name: "First", introduced: "1.2", deprecated: "3.4", isBeta: false),
             .init(name: "Second", introduced: "1.2.3", isBeta: false),
             .init(name: "Third", introduced: "4.5", isBeta: true),
         ])
-        
-        XCTAssertEqual(availability.rendered(prettyFormatted: true), """
+        #expect(availability.rendered(prettyFormatted: true) == """
         <ul id="availability">
         <li aria-label="First 1.2–3.4, Introduced in First 1.2 and deprecated in First 3.4" class="deprecated" role="text" title="Introduced in First 1.2 and deprecated in First 3.4">First 1.2–3.4</li>
         <li aria-label="Second 1.2.3+, Available on 1.2.3 and later" role="text" title="Available on 1.2.3 and later">Second 1.2.3+</li>
@@ -79,7 +79,8 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         """)
     }
     
-    func testRenderSingleLanguageParameters() throws {
+    @Test
+    func testRenderSingleLanguageParameters() {
         let parameters = makeRenderer().parameters([
             "swift": [
                 .init(name: "First", content: parseMarkup(string: "Some _formatted_ description with `code`")),
@@ -90,7 +91,7 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
                 """)),
             ]
         ])
-        XCTAssertEqual(parameters.rendered(prettyFormatted: true), """
+        #expect(parameters.rendered(prettyFormatted: true) == """
         <section id="parameters">
         <h2>
             <a href="#parameters">Parameters</a>
@@ -118,7 +119,8 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         """)
     }
     
-    func testRenderLanguageSpecificParameters() throws {
+    @Test
+    func testRenderLanguageSpecificParameters() {
         let parameters = makeRenderer().parameters([
             "swift": [
                 .init(name: "FirstCommon", content: parseMarkup(string: "Available in both languages")),
@@ -131,7 +133,7 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
                 .init(name: "ObjectiveCOnly", content: parseMarkup(string: "Only available in Objective-C")),
             ],
         ])
-        XCTAssertEqual(parameters.rendered(prettyFormatted: true), """
+        #expect(parameters.rendered(prettyFormatted: true) == """
         <section id="parameters">
         <h2>
             <a href="#parameters">Parameters</a>
@@ -166,7 +168,8 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         """)
     }
     
-    func testRenderManyLanguageSpecificParameters() throws {
+    @Test
+    func testRenderManyLanguageSpecificParameters() {
         let parameters = makeRenderer().parameters([
             "swift": [
                 .init(name: "First", content: parseMarkup(string: "Some description")),
@@ -178,7 +181,7 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
                 .init(name: "Third", content: parseMarkup(string: "Some description")),
             ],
         ])
-        XCTAssertEqual(parameters.rendered(prettyFormatted: true), """
+        #expect(parameters.rendered(prettyFormatted: true) == """
         <section id="parameters">
         <h2>
             <a href="#parameters">Parameters</a>
@@ -211,7 +214,8 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         """)
     }
     
-    func testRenderSwiftDeclaration() throws {
+    @Test
+    func testRenderSwiftDeclaration() {
         let symbolPaths = [
             "first-parameter-symbol-id":  URL(string: "/documentation/ModuleName/FirstParameterValue/index.html")!,
             "second-parameter-symbol-id": URL(string: "/documentation/ModuleName/SecondParameterValue/index.html")!,
@@ -241,7 +245,7 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
                 .init(kind: .typeIdentifier,    spelling: "ReturnValue", preciseIdentifier: "return-value-symbol-id"),
             ]
         ])
-        XCTAssertEqual(declaration.rendered(prettyFormatted: true), """
+        #expect(declaration.rendered(prettyFormatted: true) == """
         <pre id="declaration">
         <code>
             <span class="token-keyword">func</span>
@@ -259,7 +263,8 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
         """)
     }
     
-    func testRenderLanguageSpecificDeclarations() throws {
+    @Test
+    func testRenderLanguageSpecificDeclarations() {
         let symbolPaths = [
             "first-parameter-symbol-id":  URL(string: "/documentation/ModuleName/FirstParameterValue/index.html")!,
             "second-parameter-symbol-id": URL(string: "/documentation/ModuleName/SecondParameterValue/index.html")!,
@@ -314,7 +319,7 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
                 .init(kind: .text,              spelling: ";",           preciseIdentifier: nil),
             ]
         ])
-        XCTAssertEqual(declaration.rendered(prettyFormatted: true), """
+        #expect(declaration.rendered(prettyFormatted: true) == """
         <pre id="declaration">
         <code class="swift-only">
             <span class="token-keyword">func</span>
@@ -348,9 +353,7 @@ final class MarkupRenderer_PageElementsTests: XCTestCase {
     private func makeRenderer(
         elementsToReturn: [LinkedElement] = [],
         pathsToReturn: [String: URL] = [:],
-        assetsToReturn: [String: LinkedAsset] = [:],
-        file: StaticString = #filePath,
-        line: UInt = #line
+        assetsToReturn: [String: LinkedAsset] = [:]
     ) -> MarkupRenderer<some LinkProvider> {
         let path = URL(string: "/documentation/ModuleName/Something/ThisPage/index.html")!
         
diff --git a/Tests/DocCHTMLTests/MarkupRendererTests.swift b/Tests/DocCHTMLTests/MarkupRendererTests.swift
index 10d6c1d011..f9f89f165f 100644
--- a/Tests/DocCHTMLTests/MarkupRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkupRendererTests.swift
@@ -9,32 +9,33 @@
 */
 
 import Foundation
-import XCTest
+import Testing
 import DocCHTML
 @testable import SwiftDocC
 import Markdown
 
-final class MarkupRendererTests: XCTestCase {
- 
-    func testRenderParagraphsWithFormattedText() async throws {
-        try assert(
+struct MarkupRendererTests {
+    @Test
+    func testRenderParagraphsWithFormattedText() {
+        assert(
             rendering: "This is a paragraph with _emphasized_ and **strong** text.",
             matches: "<p>This is a paragraph with <i>emphasized</i> and <b>strong</b> text.</p>"
         )
         
-        try assert(
+        assert(
             rendering: "This is a paragraph with ~strikethrough~ and `pre-formatted` text.",
             matches: "<p>This is a paragraph with <s>strikethrough</s> and <code>pre-formatted</code> text.</p>"
         )
         
-        try assert(
+        assert(
             rendering: #"This is a paragraph with "double" and 'single' quoted text."#,
             matches: "<p>This is a paragraph with “double” and ‘single’ quoted text.</p>"
         )
     }
     
-    func testRenderHeadings() async throws {
-        try assert(
+    @Test
+    func testRenderHeadings() {
+        assert(
             rendering: """
             # One
             
@@ -50,7 +51,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try assert(
+        assert(
             rendering: """
             One
             ===
@@ -65,7 +66,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try assert(
+        assert(
             rendering: """
             # _One_
             
@@ -88,8 +89,9 @@ final class MarkupRendererTests: XCTestCase {
         )
     }
     
-    func testRenderTables() async throws {
-        try assert(
+    @Test
+    func testRenderTables() {
+        assert(
             rendering: """
             First   | Second  | 
             ------- | ------- |
@@ -119,7 +121,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try assert(
+        assert(
             rendering: """
             First | Second | Third |
             ----- | ------ | ----- |
@@ -155,7 +157,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try assert(
+        assert(
             rendering: """
             First | Second | Third | Fourth 
             ----- | ------ | ----- | ------
@@ -196,8 +198,9 @@ final class MarkupRendererTests: XCTestCase {
         )
     }
     
-    func testRenderLists() async throws {
-        try assert(
+    @Test
+    func testRenderLists() {
+        assert(
             rendering: """
             - First
             - Second
@@ -247,8 +250,9 @@ final class MarkupRendererTests: XCTestCase {
         )
     }
     
+    @Test
     func testRenderAsides() async throws {
-        try assert(
+        assert(
             rendering: """
             > Note: Something noteworthy
             >
@@ -269,8 +273,9 @@ final class MarkupRendererTests: XCTestCase {
         )
     }
     
+    @Test
     func testRenderCodeBlocks() async throws {
-        try assert(
+        assert(
             rendering: """
             ~~~
             Some block of code
@@ -285,7 +290,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try assert(
+        assert(
             rendering: """
                 Some block of code
             """,
@@ -298,7 +303,7 @@ final class MarkupRendererTests: XCTestCase {
             """
         )
         
-        try assert(
+        assert(
             rendering: """
             ```lang
             Some block of code
@@ -312,21 +317,21 @@ final class MarkupRendererTests: XCTestCase {
             </pre>
             """
         )
-        
     }
     
-    func testRenderMiscellaneousElements() async throws {
-        try assert(
+    @Test
+    func testRenderMiscellaneousElements() {
+        assert(
             rendering: "First\nSecond", // new lines usually have no special meaning in markdown...
             matches: "<p>First Second</p>"
         )
         
-        try assert(
+        assert(
             rendering: "First  \nSecond", // ... but with two trailing spaces they are treated as line breaks
             matches: "<p>First<br/>Second</p>"
         )
         
-        try assert(
+        assert(
             rendering: """
             -------
             """,
@@ -334,12 +339,13 @@ final class MarkupRendererTests: XCTestCase {
         )
     }
     
-    func testRelativeLinksToOtherPages() async throws {
+    @Test
+    func testRelativeLinksToOtherPages() throws {
         // Link to article
-        try assert(
+        assert(
             rendering: "<doc://com.example.test/documentation/Something/SomeArticle>", // Simulate a link that's been locally resolved already
             elementToReturn: .init(
-                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeArticle/index.html")),
+                path: try #require(URL(string: "doc://com.example.test/documentation/Something/SomeArticle/index.html")),
                 names: .single(.conceptual("Some Article Title")),
                 subheadings: .single(.conceptual("Some Article Title")), // Not relevant for inline links
                 abstract: nil // Not relevant for inline links
@@ -353,10 +359,10 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Link to single-language symbol
-        try assert(
+        assert(
             rendering: "<doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)>", // Simulate a link that's been locally resolved already
             elementToReturn: .init(
-                path: try XCTUnwrap(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
+                path: try #require(URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")),
                 names: .single(.symbol("someMethod(_:_:)")),
                 subheadings: .single(.symbol([ // Not relevant for inline links
                     .init(text: "func ", kind: .decorator),
@@ -379,7 +385,7 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Link to symbol with multiple language representation
-        try assert(
+        assert(
             rendering: "<doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)>", // Simulate a link that's been locally resolved already
             elementToReturn: makeExampleMethodWithDifferentLanguageRepresentations(),
             prettyFormatted: true,
@@ -402,7 +408,7 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Link with custom title
-        try assert(
+        assert(
             rendering: "[Custom _formatted_ title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
             elementToReturn: makeExampleMethodWithDifferentLanguageRepresentations(),
             matches: """
@@ -411,7 +417,7 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Link with custom symbol-like title
-        try assert(
+        assert(
             rendering: "[Some `CustomSymbolName` title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
             elementToReturn: makeExampleMethodWithDifferentLanguageRepresentations(),
             matches: """
@@ -420,12 +426,13 @@ final class MarkupRendererTests: XCTestCase {
         )
     }
     
-    func testRelativeLinksToImages() async throws {
+    @Test
+    func testRelativeLinksToImages() throws {
         // Only a single image representation
-        try assert(
+        assert(
             rendering: "![Some alt text](some-image.png)",
             assetToReturn: .init(images: [
-                .light: [1: try XCTUnwrap(URL(string: "images/com.test.example/some-image.png"))]
+                .light: [1: try #require(URL(string: "images/com.test.example/some-image.png"))]
             ]),
             prettyFormatted: true,
             matches: """
@@ -438,12 +445,12 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Only light mode image representations
-        try assert(
+        assert(
             rendering: "![Some alt text](some-image.png)",
             assetToReturn: .init(images: [
                 .light: [
-                    1: try XCTUnwrap(URL(string: "images/com.test.example/some-image.png")),
-                    2: try XCTUnwrap(URL(string: "images/com.test.example/some-image@2x.png")),
+                    1: try #require(URL(string: "images/com.test.example/some-image.png")),
+                    2: try #require(URL(string: "images/com.test.example/some-image@2x.png")),
                 ]
             ]),
             prettyFormatted: true,
@@ -457,11 +464,11 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Only a single scale factor
-        try assert(
+        assert(
             rendering: "![Some alt text](some-image.png)",
             assetToReturn: .init(images: [
-                .light: [1: try XCTUnwrap(URL(string: "images/com.test.example/some-image.png"))],
-                .dark:  [1: try XCTUnwrap(URL(string: "images/com.test.example/some-image~dark.png"))],
+                .light: [1: try #require(URL(string: "images/com.test.example/some-image.png"))],
+                .dark:  [1: try #require(URL(string: "images/com.test.example/some-image~dark.png"))],
             ]),
             prettyFormatted: true,
             matches: """
@@ -476,16 +483,16 @@ final class MarkupRendererTests: XCTestCase {
         )
         
         // Multiple styles and scale factors
-        try assert(
+        assert(
             rendering: "![Some alt text](some-image.png)",
             assetToReturn: .init(images: [
                 .light: [
-                    1: try XCTUnwrap(URL(string: "images/com.test.example/some-image.png")),
-                    2: try XCTUnwrap(URL(string: "images/com.test.example/some-image@2x.png")),
+                    1: try #require(URL(string: "images/com.test.example/some-image.png")),
+                    2: try #require(URL(string: "images/com.test.example/some-image@2x.png")),
                 ],
                 .dark: [
-                    1: try XCTUnwrap(URL(string: "images/com.test.example/some-image~dark.png")),
-                    2: try XCTUnwrap(URL(string: "images/com.test.example/some-image~dark@2x.png")),
+                    1: try #require(URL(string: "images/com.test.example/some-image~dark.png")),
+                    2: try #require(URL(string: "images/com.test.example/some-image~dark@2x.png")),
                 ],
             ]),
             prettyFormatted: true,
@@ -507,9 +514,8 @@ final class MarkupRendererTests: XCTestCase {
         assetToReturn: LinkedAsset? = nil,
         prettyFormatted: Bool = false,
         matches expectedHTML: String,
-        file: StaticString = #filePath,
-        line: UInt = #line
-    ) throws {
+        sourceLocation: Testing.SourceLocation = #_sourceLocation
+    ) {
         let renderer = MarkupRenderer(
             path: URL(string: "/documentation/Something/ThisPage/index.html")!,
             linkProvider: SingleValueLinkProvider(
@@ -520,10 +526,10 @@ final class MarkupRendererTests: XCTestCase {
         let htmlNodes = Document(parsing: markdownContent).children.map { renderer.visit($0) }
         let htmlString = htmlNodes.rendered(prettyFormatted: prettyFormatted)
         
-        XCTAssertEqual(htmlString, expectedHTML, file: file, line: line)
+        #expect(htmlString == expectedHTML, sourceLocation: sourceLocation)
     }
     
-    private func makeExampleMethodWithDifferentLanguageRepresentations()  -> LinkedElement {
+    private func makeExampleMethodWithDifferentLanguageRepresentations() -> LinkedElement {
         LinkedElement(
             path: URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")!,
             names: .languageSpecificSymbol([
diff --git a/Tests/DocCHTMLTests/WordBreakTests.swift b/Tests/DocCHTMLTests/WordBreakTests.swift
index fd1cf1203d..892f1ddc56 100644
--- a/Tests/DocCHTMLTests/WordBreakTests.swift
+++ b/Tests/DocCHTMLTests/WordBreakTests.swift
@@ -9,10 +9,11 @@
 */
 
 import Foundation
-import XCTest
+import Testing
 import DocCHTML
 
-final class WordBreakTests: XCTestCase {
+struct WordBreakTests {
+    @Test
     func testWordBreaks() {
         assertWordBreaks(for: "doSomething<Generic>(withFirst:andSecond:)", matches: """
         do
@@ -66,13 +67,13 @@ final class WordBreakTests: XCTestCase {
     private func assertWordBreaks(
         for symbolName: String,
         matches expectedHTML: String,
-        file: StaticString = #filePath,
+        sourceLocation: SourceLocation = #_sourceLocation,
         line: UInt = #line
     ) {
         let withWordBreaks = RenderHelpers.wordBreak(symbolName: symbolName)
             .map { $0.xmlString(options: [.nodePrettyPrint, .nodeCompactEmptyElement] )}
             .joined(separator: "\n")
         
-        XCTAssertEqual(withWordBreaks, expectedHTML, file: file, line: line)
+        #expect(withWordBreaks == expectedHTML, sourceLocation: sourceLocation)
     }
 }

From 22395a9fe91d7127e3f2a64e0ed71c147f84ba49 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 21 Nov 2025 20:45:55 +0000
Subject: [PATCH 28/68] Pass the current pages name rather than look it up for
 the breadcrumbs

---
 .../DocCHTML/MarkupRenderer+Breadcrumbs.swift | 10 ++++-----
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 21 ++++++++++++++++---
 .../MarkupRenderer+PageElementsTests.swift    |  2 +-
 3 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
index 214f5de8dc..24bf4aead8 100644
--- a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
@@ -16,10 +16,10 @@ package import FoundationXML
 
 package extension MarkupRenderer {
     /// Creates an HTML element for the breadcrumbs leading up to the renderer's reference.
-    func breadcrumbs(references: [URL]) -> XMLNode {
+    func breadcrumbs(references: [URL], currentPageNames: LinkedElement.Names) -> XMLNode {
         // Breadcrumbs handle symbols differently than most elements, so there's no point in sharing _this_ code
-        func names(for element: LinkedElement) -> [XMLNode] {
-            switch element.names {
+        func nameElements(for names: LinkedElement.Names) -> [XMLNode] {
+            switch names {
             // Breadcrumbs display both symbolic names and conceptual in a default style
             case .single(.conceptual(let name)), .single(.symbol(let name)):
                 [.text(name)]
@@ -36,14 +36,14 @@ package extension MarkupRenderer {
         var items: [XMLNode] = references.compactMap {
             linkProvider.element(for: $0).map { page in
                 .element(named: "li", children: [
-                    .element(named: "a", children: names(for: page), attributes: ["href": self.path(to: page.path)])
+                    .element(named: "a", children: nameElements(for: page.names), attributes: ["href": self.path(to: page.path)])
                 ])
             }
         }
         
         // The current page doesn't display as a link
         items.append(
-            .element(named: "li", children: names(for: linkProvider.element(for: self.path)! /* The current page is known to exist */))
+            .element(named: "li", children: nameElements(for: currentPageNames))
         )
         
         return .element(
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 5c567f8150..f623db5731 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -154,7 +154,7 @@ struct HTMLRenderer {
         self.renderContext = renderContext
         let linkProvider = ContextLinkProvider(reference: reference, context: context)
         self.linkProvider = linkProvider
-        let filePath = reference.url.withoutHostAndPortAndScheme().appendingPathComponent("index.html")
+        let filePath = ContextLinkProvider.filePath(for: reference)
         self.filePath = filePath
         self.renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
     }
@@ -181,7 +181,8 @@ struct HTMLRenderer {
         hero.addChild(
             .element(named: "header", children: [
                 renderer.breadcrumbs(
-                    references: (context.shortestFinitePath(to: reference) ?? [context.soleRootModuleReference!]).map { ContextLinkProvider.filePath(for: $0) }
+                    references: (context.shortestFinitePath(to: reference) ?? [context.soleRootModuleReference!]).map { ContextLinkProvider.filePath(for: $0) },
+                    currentPageNames: .single(.conceptual(node.name.plainText))
                 ),
                 
                 .element(
@@ -297,11 +298,25 @@ struct HTMLRenderer {
             articleElement.addChild(hero)
         }
         
+        let names: LinkedElement.Names
+        if case .conceptual(title: let title) = node.name {
+            names = .single(.conceptual(title))
+        } else {
+            names = .languageSpecificSymbol([String: String](
+                symbol.titleVariants.allValues.compactMap({ trait, title in
+                    guard let lang = trait.interfaceLanguage else { return nil }
+                    return (key: lang, value: title)
+                }),
+                uniquingKeysWith: { _, new in new }
+            ))
+        }
+        
         // Breadcrumbs and Eyebrow
         hero.addChild(
             .element(named: "header", children: [
                 renderer.breadcrumbs(
-                    references: (context.linkResolver.localResolver.breadcrumbs(of: reference, in: reference.sourceLanguage) ?? []).map { ContextLinkProvider.filePath(for: $0) }
+                    references: (context.linkResolver.localResolver.breadcrumbs(of: reference, in: reference.sourceLanguage) ?? []).map { ContextLinkProvider.filePath(for: $0) },
+                    currentPageNames: names
                 ),
                 
                 .element(
diff --git a/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift
index 80b2262aa9..6b18d419b8 100644
--- a/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift
@@ -43,7 +43,7 @@ struct MarkupRenderer_PageElementsTests {
                 abstract: nil
             ),
         ]
-        let breadcrumbs = makeRenderer(elementsToReturn: elements).breadcrumbs(references: elements.map { $0.path })
+        let breadcrumbs = makeRenderer(elementsToReturn: elements).breadcrumbs(references: elements.map { $0.path }, currentPageNames: .single(.conceptual("ThisPage")))
         
         #expect(breadcrumbs.rendered(prettyFormatted: true) == """
         <nav id="breadcrumbs">

From 746a9610ea64e4e9bb38d39473173509c1ae55e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 26 Nov 2025 10:14:15 +0100
Subject: [PATCH 29/68] Add a CLI feature flag for adding content to the HTML
 template files

---
 .../ConvertActionConverter.swift              |  38 ++-
 .../ConvertOutputConsumer.swift               |   3 -
 .../Rendering/HTML/HTMLContentConsumer.swift  |  36 +++
 .../Model/Rendering/HTML/HTMLRenderer.swift   |  29 ++-
 .../Actions/Convert/ConvertAction.swift       |  16 +-
 .../Convert/ConvertFileWritingConsumer.swift  |   8 -
 .../FileWritingHTMLContentConsumer.swift      |  96 ++++++++
 .../ConvertAction+CommandInitialization.swift |   1 +
 .../ArgumentParsing/Subcommands/Convert.swift |   9 +
 ...recatedDiagnosticsDigestWarningTests.swift |   2 +
 .../Indexing/ExternalRenderNodeTests.swift    |   1 +
 .../TestRenderNodeOutputConsumer.swift        |   1 +
 .../ConvertActionStaticHostableTests.swift    |   1 +
 .../FileWritingHTMLContentConsumerTests.swift | 218 ++++++++++++++++++
 .../MergeActionTests.swift                    |   2 +-
 15 files changed, 432 insertions(+), 29 deletions(-)
 create mode 100644 Sources/SwiftDocC/Model/Rendering/HTML/HTMLContentConsumer.swift
 create mode 100644 Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
 create mode 100644 Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift

diff --git a/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift b/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
index 6844616c88..18a92484a6 100644
--- a/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
+++ b/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
@@ -26,6 +26,7 @@ package enum ConvertActionConverter {
     /// - Parameters:
     ///   - context: The context that the bundle is a part of.
     ///   - outputConsumer: The consumer that the conversion passes outputs of the conversion to.
+    ///   - htmlContentConsumer: The consumer for HTML content that the conversion produces, or `nil` if the conversion shouldn't produce any HTML content.
     ///   - sourceRepository: The source repository where the documentation's sources are hosted.
     ///   - emitDigest: Whether the conversion should pass additional metadata output––such as linkable entities information, indexing information, or asset references by asset type––to the consumer.
     ///   - documentationCoverageOptions: The level of experimental documentation coverage information that the conversion should pass to the consumer.
@@ -33,6 +34,7 @@ package enum ConvertActionConverter {
     package static func convert(
         context: DocumentationContext,
         outputConsumer: some ConvertOutputConsumer & ExternalNodeConsumer,
+        htmlContentConsumer: (any HTMLContentConsumer)?,
         sourceRepository: SourceRepository?,
         emitDigest: Bool,
         documentationCoverageOptions: DocumentationCoverageOptions
@@ -103,25 +105,26 @@ package enum ConvertActionConverter {
 
         let renderSignpostHandle = signposter.beginInterval("Render", id: signposter.makeSignpostID(), "Render \(context.knownPages.count) pages")
         
-        var conversionProblems: [Problem] = context.knownPages.concurrentPerform { identifier, results in
+        var conversionProblems: [Problem] = context.knownPages.concurrentPerform { [htmlContentConsumer] identifier, results in
             // If cancelled skip all concurrent conversion work in this block.
             guard !Task.isCancelled else { return }
             
             // Wrap JSON encoding in an autorelease pool to avoid retaining the autoreleased ObjC objects returned by `JSONSerialization`
             autoreleasepool {
                 do {
-                    // FIXME: This needs a feature flag instead of being hard-coded like this
-                    var renderer = HTMLRenderer(reference: identifier, context: context, renderContext: renderContext)
-                    
                     let entity = try context.entity(with: identifier)
-                    if let symbol = entity.semantic as? Symbol {
-                        let html = renderer.renderSymbol(symbol)
-                        try outputConsumer.consume(page: html, for: identifier)
-                    } else if let article = entity.semantic as? Article {
-                        let html = renderer.renderArticle(article)
-                        try outputConsumer.consume(page: html, for: identifier)
+                    
+                    if let htmlContentConsumer {
+                        var renderer = HTMLRenderer(reference: identifier, context: context, renderContext: renderContext)
+                        
+                        if let symbol = entity.semantic as? Symbol {
+                            let renderedPageInfo = renderer.renderSymbol(symbol)
+                            try htmlContentConsumer.consume(pageInfo: renderedPageInfo, forPage: identifier)
+                        } else if let article = entity.semantic as? Article {
+                            let renderedPageInfo = renderer.renderArticle(article)
+                            try htmlContentConsumer.consume(pageInfo: renderedPageInfo, forPage: identifier)
+                        }
                     }
-                    return
                     
                     guard let renderNode = converter.renderNode(for: entity) else {
                         // No render node was produced for this entity, so just skip it.
@@ -258,3 +261,16 @@ package enum ConvertActionConverter {
         return conversionProblems
     }
 }
+
+private extension HTMLContentConsumer {
+    func consume(pageInfo: HTMLRenderer.RenderedPageInfo, forPage reference: ResolvedTopicReference) throws {
+        try consume(
+            mainContent: pageInfo.content,
+            metadata: (
+                title: pageInfo.metadata.title,
+                description: pageInfo.metadata.plainDescription
+            ),
+            forPage: reference
+        )
+    }
+}
diff --git a/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift b/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift
index 5915d58bd1..d15e16b77d 100644
--- a/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift
+++ b/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift
@@ -23,9 +23,6 @@ public protocol ConvertOutputConsumer {
     /// > Warning: This method might be called concurrently.
     func consume(renderNode: RenderNode) throws
     
-    // FIXME: I don't know if the same consumer should handle both kinds of output
-    func consume(page: XMLNode, for reference: ResolvedTopicReference) throws
-    
     /// Consumes a documentation bundle with the purpose of extracting its on-disk assets.
     func consume(assetsInBundle bundle: DocumentationBundle) throws
     
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLContentConsumer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLContentConsumer.swift
new file mode 100644
index 0000000000..28a3ecf4ff
--- /dev/null
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLContentConsumer.swift
@@ -0,0 +1,36 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+package import Foundation
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+package import FoundationXML
+#endif
+
+/// A consumer for HTML content produced during documentation conversion.
+package protocol HTMLContentConsumer {
+    /// Consumes the HTML content and metadata for a given page.
+    ///
+    /// The content and metadata doesn't make up a full valid HTML page.
+    /// It's the consumers responsibility to insert the information into a template or skeletal structure to produce a valid HTML file for each page.
+    ///
+    /// - Parameters:
+    ///   - mainContent: The contents for this page as an XHTML node.
+    ///   - metadata: Metadata information (title and description) about this page.
+    ///   - reference: The resolved topic reference that identifies this page.
+    func consume(
+        mainContent: XMLNode,
+        metadata: (
+            title: String,
+            description: String?
+        ),
+        forPage reference: ResolvedTopicReference
+    ) throws
+}
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index f623db5731..5117bc50aa 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -164,8 +164,16 @@ struct HTMLRenderer {
             ?? destination.path) + "/index.html"
     }
     
+    struct RenderedPageInfo {
+        var content: XMLNode
+        var metadata: Metadata
+        struct Metadata {
+            var title: String
+            var plainDescription: String?
+        }
+    }
     
-    mutating func renderArticle(_ article: Article) -> XMLNode {
+    mutating func renderArticle(_ article: Article) -> RenderedPageInfo {
         let node = context.documentationCache[reference]!
         
         let main = XMLElement(name: "main")
@@ -276,10 +284,16 @@ struct HTMLRenderer {
             articleElement.addChild(section)
         }
         
-        return makePage(main: main, title: article.title?.plainText ?? node.name.plainText, plainDescription: article.abstract?.plainText)
+        return RenderedPageInfo(
+            content: main,
+            metadata: .init(
+                title: article.title?.plainText ?? node.name.plainText,
+                plainDescription: article.abstract?.plainText
+            )
+        )
     }
     
-    mutating func renderSymbol(_ symbol: Symbol) -> XMLNode {
+    mutating func renderSymbol(_ symbol: Symbol) -> RenderedPageInfo {
         let node = context.documentationCache[reference]!
         
         let isDeprecated = symbol.isDeprecated
@@ -579,7 +593,13 @@ struct HTMLRenderer {
             articleElement.addChild(section)
         }
         
-        return makePage(main: main, title: symbol.title, plainDescription: symbol.abstract?.plainText)
+        return RenderedPageInfo(
+            content: main,
+            metadata: .init(
+                title: symbol.title,
+                plainDescription: symbol.abstract?.plainText
+            )
+        )
     }
     
     private func makeDiscussion(_ discussion: DiscussionSection, isSymbol: Bool) -> XMLNode {
@@ -726,6 +746,7 @@ struct HTMLRenderer {
         return nil
     }
     
+    // FIXME: There's currently nothing calling this. Instead, the 2 `render...` methods return a `RenderedPageInfo` value.
     private func makePage(main: XMLNode, title: String, plainDescription: String?) -> XMLNode {
         let head = XMLElement(name: "head")
         head.setChildren([
diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
index b6c98ecedd..5c2cc9e008 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
@@ -30,6 +30,7 @@ public struct ConvertAction: AsyncAction {
     let diagnosticEngine: DiagnosticEngine
 
     private let transformForStaticHosting: Bool
+    private let includeContentInEachHTMLFile: Bool
     private let hostingBasePath: String?
     
     let sourceRepository: SourceRepository?
@@ -64,6 +65,7 @@ public struct ConvertAction: AsyncAction {
     ///   - experimentalEnableCustomTemplates: `true` if the convert action should enable support for custom "header.html" and "footer.html" template files, otherwise `false`.
     ///   - experimentalModifyCatalogWithGeneratedCuration: `true` if the convert action should write documentation extension files containing markdown representations of DocC's automatic curation into the `documentationBundleURL`, otherwise `false`.
     ///   - transformForStaticHosting: `true` if the convert action should process the build documentation archive so that it supports a static hosting environment, otherwise `false`.
+    ///   - includeContentInEachHTMLFile: `true` if the convert action should process each static hosting HTML file so that it contains documentation content for environments without JavaScript enabled, otherwise `false`.
     ///   - allowArbitraryCatalogDirectories: `true` if the convert action should consider the root location as a documentation bundle if it doesn't discover another bundle, otherwise `false`.
     ///   - hostingBasePath: The base path where the built documentation archive will be hosted at.
     ///   - sourceRepository: The source repository where the documentation's sources are hosted.
@@ -91,6 +93,7 @@ public struct ConvertAction: AsyncAction {
         experimentalEnableCustomTemplates: Bool = false,
         experimentalModifyCatalogWithGeneratedCuration: Bool = false,
         transformForStaticHosting: Bool = false,
+        includeContentInEachHTMLFile: Bool = false,
         allowArbitraryCatalogDirectories: Bool = false,
         hostingBasePath: String? = nil,
         sourceRepository: SourceRepository? = nil,
@@ -105,6 +108,7 @@ public struct ConvertAction: AsyncAction {
         self.temporaryDirectory = temporaryDirectory
         self.documentationCoverageOptions = documentationCoverageOptions
         self.transformForStaticHosting = transformForStaticHosting
+        self.includeContentInEachHTMLFile = includeContentInEachHTMLFile
         self.hostingBasePath = hostingBasePath
         self.sourceRepository = sourceRepository
         
@@ -248,7 +252,7 @@ public struct ConvertAction: AsyncAction {
 //        }
 
         let indexHTML: URL?
-        if let htmlTemplateDirectory {
+        if let htmlTemplateDirectory, transformForStaticHosting, !includeContentInEachHTMLFile {
             let indexHTMLUrl = temporaryFolder.appendingPathComponent(
                 HTMLTemplate.indexFileName.rawValue,
                 isDirectory: false
@@ -299,9 +303,16 @@ public struct ConvertAction: AsyncAction {
             context: context,
             indexer: indexer,
             enableCustomTemplates: experimentalEnableCustomTemplates,
-            transformForStaticHostingIndexHTML: transformForStaticHosting ? indexHTML : nil,
+            transformForStaticHostingIndexHTML: indexHTML,
             bundleID: inputs.id
         )
+        
+        let htmlConsumer: FileWritingHTMLContentConsumer?
+        if includeContentInEachHTMLFile, let indexHTML {
+            htmlConsumer = try FileWritingHTMLContentConsumer(targetFolder: temporaryFolder, fileManager: fileManager, htmlTemplate: indexHTML)
+        } else {
+            htmlConsumer = nil
+        }
 
         if experimentalModifyCatalogWithGeneratedCuration, let catalogURL = rootURL {
             let writer = GeneratedCurationWriter(context: context, catalogURL: catalogURL, outputURL: catalogURL)
@@ -320,6 +331,7 @@ public struct ConvertAction: AsyncAction {
                 try ConvertActionConverter.convert(
                     context: context,
                     outputConsumer: outputConsumer,
+                    htmlContentConsumer: htmlConsumer,
                     sourceRepository: sourceRepository,
                     emitDigest: emitDigest,
                     documentationCoverageOptions: documentationCoverageOptions
diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift
index 76fa22c3d5..56e4925851 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift
@@ -68,14 +68,6 @@ struct ConvertFileWritingConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
         indexer?.index(renderNode)
     }
     
-    func consume(page: XMLNode, for reference: ResolvedTopicReference) throws {
-        let htmlString = page.xmlString//(options: .nodePrettyPrint)
-        
-        let url = targetFolder.appendingPathComponent(reference.path)
-        try? fileManager.createDirectory(at: url, withIntermediateDirectories: true, attributes: nil)
-        try htmlString.write(to: url.appendingPathComponent("index.html"), atomically: true, encoding: .utf8)
-    }
-    
     func consume(externalRenderNode: ExternalRenderNode) throws {
         // Index the external node, if indexing is enabled.
         indexer?.index(externalRenderNode)
diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
new file mode 100644
index 0000000000..701fc277cc
--- /dev/null
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
@@ -0,0 +1,96 @@
+/*
+This source file is part of the Swift.org open source project
+
+Copyright (c) 2025 Apple Inc. and the Swift project authors
+Licensed under Apache License v2.0 with Runtime Library Exception
+
+See https://swift.org/LICENSE.txt for license information
+See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+import SwiftDocC
+
+struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
+    var targetFolder: URL
+    var bundleRootFolder: URL?
+    var fileManager: any FileManagerProtocol
+    var prettyPrintOutput: Bool
+    
+    private struct HTMLTemplate {
+        var beforeTitle: String
+        var fromTitleToNoScript: String
+        var afterNoScript: String
+        
+        init(data: Data) throws {
+            let content = String(decoding: data, as: UTF8.self)
+            
+            // FIXME: If the template doesn't already contain a <noscript> tag, add one to the start of the <body>
+            let noScriptStart = content.utf8.firstRange(of: "<noscript>".utf8)!.upperBound
+            let noScriptEnd   = content.utf8.firstRange(of: "</noscript>".utf8)!.lowerBound
+            
+            let prefix = content[..<noScriptStart]
+            
+            // FIXME: If the template doesn't already contain a <title> tag, add one to the end of the <head>
+            let titleStart = content.utf8.firstRange(of: "<title>".utf8)!.upperBound
+            let titleEnd   = content.utf8.firstRange(of: "</title>".utf8)!.lowerBound
+            
+            // ???: Should we parse the content with XMLParser instead? If so, what do we do if it's not valid XHTML?
+            
+            beforeTitle         = String( prefix[..<titleStart] )
+            fromTitleToNoScript = String( prefix[titleEnd...] )
+            afterNoScript       = String( content[noScriptEnd...] )
+        }
+        
+        func makeContent(
+            content: XMLNode,
+            title: String,
+            plainDescription _: String?, // FIXME: Insert the description in the <head>
+            prettyPrint: Bool
+        ) -> String {
+            beforeTitle + title + fromTitleToNoScript + content.rendered(prettyPrinted: prettyPrint) + afterNoScript
+        }
+    }
+    private var htmlTemplate: HTMLTemplate
+    
+    init(
+        targetFolder: URL,
+        bundleRootFolder: URL? = nil,
+        fileManager: some FileManagerProtocol,
+        htmlTemplate: URL,
+        prettyPrintOutput: Bool = shouldPrettyPrintOutputJSON
+    ) throws {
+        self.targetFolder = targetFolder
+        self.bundleRootFolder = bundleRootFolder
+        self.fileManager = fileManager
+        self.htmlTemplate = try HTMLTemplate(data: fileManager.contents(of: htmlTemplate))
+        self.prettyPrintOutput = prettyPrintOutput
+    }
+    
+    func consume(
+        mainContent: XMLNode,
+        metadata: (title: String, description: String?),
+        forPage reference: ResolvedTopicReference
+    ) throws {
+        let htmlString = htmlTemplate.makeContent(
+            content: mainContent,
+            title: metadata.title,
+            plainDescription: metadata.description,
+            prettyPrint: prettyPrintOutput
+        )
+        
+        let url = targetFolder.appendingPathComponent(reference.path)
+        try? fileManager.createDirectory(at: url, withIntermediateDirectories: true, attributes: nil)
+        try fileManager.createFile(at: url.appendingPathComponent("index.html"), contents: Data(htmlString.utf8), options: .atomic)
+    }
+}
+
+private extension XMLNode {
+    func rendered(prettyPrinted: Bool) -> String {
+        if prettyPrinted {
+            xmlString(options: [.nodePrettyPrint, .nodeCompactEmptyElement])
+        } else {
+            xmlString(options: .nodeCompactEmptyElement)
+        }
+    }
+}
diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
index 4d7272d3a2..8ea1c161f1 100644
--- a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
+++ b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
@@ -78,6 +78,7 @@ extension ConvertAction {
             experimentalEnableCustomTemplates: convert.experimentalEnableCustomTemplates,
             experimentalModifyCatalogWithGeneratedCuration: convert.experimentalModifyCatalogWithGeneratedCuration,
             transformForStaticHosting: convert.transformForStaticHosting,
+            includeContentInEachHTMLFile: convert.experimentalTransformForStaticHostingWithContent,
             allowArbitraryCatalogDirectories: convert.allowArbitraryCatalogDirectories,
             hostingBasePath: convert.hostingBasePath,
             sourceRepository: SourceRepository(from: convert.sourceRepositoryArguments),
diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift
index a33715a625..bea17bb653 100644
--- a/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift
+++ b/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift
@@ -184,6 +184,9 @@ extension Docc {
                 help: "Produce a DocC archive that supports static hosting environments."
             )
             var transformForStaticHosting = true
+            
+            @Flag(help: "Include documentation content in each HTML file for static hosting environments.")
+            var experimentalTransformForStaticHostingWithContent = false
         }
         
         /// A Boolean value that is true if the DocC archive produced by this conversion will support static hosting environments.
@@ -194,6 +197,12 @@ extension Docc {
             set { hostingOptions.transformForStaticHosting = newValue }
         }
         
+        /// A Boolean value that is true if the DocC archive produced by this conversion will browsing without JavaScript enabled.
+        public var experimentalTransformForStaticHostingWithContent: Bool {
+            get { hostingOptions.experimentalTransformForStaticHostingWithContent }
+            set { hostingOptions.experimentalTransformForStaticHostingWithContent = newValue }
+        }
+        
         /// A user-provided relative path to be used in the archived output
         var hostingBasePath: String? {
             hostingOptions.hostingBasePath
diff --git a/Tests/SwiftDocCTests/DeprecatedDiagnosticsDigestWarningTests.swift b/Tests/SwiftDocCTests/DeprecatedDiagnosticsDigestWarningTests.swift
index 8cfbad65db..6b145d1e91 100644
--- a/Tests/SwiftDocCTests/DeprecatedDiagnosticsDigestWarningTests.swift
+++ b/Tests/SwiftDocCTests/DeprecatedDiagnosticsDigestWarningTests.swift
@@ -29,6 +29,7 @@ class DeprecatedDiagnosticsDigestWarningTests: XCTestCase {
         _ = try ConvertActionConverter.convert(
             context: context,
             outputConsumer: outputConsumer,
+            htmlContentConsumer: nil,
             sourceRepository: nil,
             emitDigest: true,
             documentationCoverageOptions: .noCoverage
@@ -53,6 +54,7 @@ class DeprecatedDiagnosticsDigestWarningTests: XCTestCase {
         _ = try ConvertActionConverter.convert(
             context: context,
             outputConsumer: outputConsumer,
+            htmlContentConsumer: nil,
             sourceRepository: nil,
             emitDigest: true,
             documentationCoverageOptions: .noCoverage
diff --git a/Tests/SwiftDocCTests/Indexing/ExternalRenderNodeTests.swift b/Tests/SwiftDocCTests/Indexing/ExternalRenderNodeTests.swift
index 588c979ebd..7f2c070486 100644
--- a/Tests/SwiftDocCTests/Indexing/ExternalRenderNodeTests.swift
+++ b/Tests/SwiftDocCTests/Indexing/ExternalRenderNodeTests.swift
@@ -563,6 +563,7 @@ class ExternalRenderNodeTests: XCTestCase {
         let problems = try ConvertActionConverter.convert(
             context: context,
             outputConsumer: outputConsumer,
+            htmlContentConsumer: nil,
             sourceRepository: nil,
             emitDigest: false,
             documentationCoverageOptions: .noCoverage
diff --git a/Tests/SwiftDocCTests/TestRenderNodeOutputConsumer.swift b/Tests/SwiftDocCTests/TestRenderNodeOutputConsumer.swift
index c9eca9a9e9..39d0091746 100644
--- a/Tests/SwiftDocCTests/TestRenderNodeOutputConsumer.swift
+++ b/Tests/SwiftDocCTests/TestRenderNodeOutputConsumer.swift
@@ -98,6 +98,7 @@ extension XCTestCase {
         _ = try ConvertActionConverter.convert(
             context: context,
             outputConsumer: outputConsumer,
+            htmlContentConsumer: nil,
             sourceRepository: sourceRepository,
             emitDigest: false,
             documentationCoverageOptions: .noCoverage
diff --git a/Tests/SwiftDocCUtilitiesTests/ConvertActionStaticHostableTests.swift b/Tests/SwiftDocCUtilitiesTests/ConvertActionStaticHostableTests.swift
index 0c2c0498b1..ba0c739e8d 100644
--- a/Tests/SwiftDocCUtilitiesTests/ConvertActionStaticHostableTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/ConvertActionStaticHostableTests.swift
@@ -42,6 +42,7 @@ class ConvertActionStaticHostableTests: StaticHostingBaseTests {
             currentPlatforms: nil,
             temporaryDirectory: try createTemporaryDirectory(),
             transformForStaticHosting: true,
+            includeContentInEachHTMLFile: false,
             hostingBasePath: basePath
         )
         _ = try await action.perform(logHandle: .none)
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
new file mode 100644
index 0000000000..bfde5b779f
--- /dev/null
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -0,0 +1,218 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+
+import Foundation
+@testable import SwiftDocCUtilities
+import SwiftDocC
+import SymbolKit
+import XCTest
+import SwiftDocCTestUtilities
+
+final class FileWritingHTMLContentConsumerTests: XCTestCase {
+    
+    func testWritesContentInsideHTMLTemplate() async throws {
+        let catalog = Folder(name: "unit-test.docc", content: [
+            JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(moduleName: "ModuleName", symbols: [
+                makeSymbol(id: "some-symbol-id", kind: .class, pathComponents: ["SomeClass"], docComment: """
+                Some in-source description of this class
+                """, otherMixins: [
+                    SymbolGraph.Symbol.DeclarationFragments.init(declarationFragments: [
+                        .init(kind: .keyword,    spelling: "class",     preciseIdentifier: nil),
+                        .init(kind: .text,       spelling: " ",         preciseIdentifier: nil),
+                        .init(kind: .identifier, spelling: "SomeClass", preciseIdentifier: nil),
+                    ])
+                ])
+            ])),
+            
+            TextFile(name: "ModuleName.md", utf8Content: """
+            # ``ModuleName``
+            
+            Some description of this module
+            """)
+        ])
+        
+        let htmlTemplate = TextFile(name: "index.html", utf8Content: """
+        <html>
+          <head>
+            <meta charset="utf-8" />
+            <link rel="icon" href="/favicon.ico" />
+            <title>Documentation</title>
+            <script>var baseUrl = "/"</script>
+          </head>
+          <body>
+            <noscript>
+              <p>Some existing information inside the no script tag</p>
+            </noscript>
+            <div id="app"></div>
+          </body>
+        </html>
+        """)
+        
+        let fileSystem = try TestFileSystem(folders: [
+            Folder(name: "path", content: [
+                Folder(name: "to", content: [
+                    catalog
+                ])
+            ]),
+            Folder(name: "template", content: [
+                htmlTemplate
+            ]),
+            Folder(name: "output-dir", content: [])
+        ])
+        
+        let (bundle, dataProvider) = try DocumentationContext.InputsProvider(fileManager: fileSystem)
+            .inputsAndDataProvider(startingPoint: URL(fileURLWithPath: "/path/to/\(catalog.name)"), options: .init())
+        
+        let context = try await DocumentationContext(bundle: bundle, dataProvider: dataProvider, configuration: .init())
+        
+        let htmlConsumer = try FileWritingHTMLContentConsumer(
+            targetFolder: URL(fileURLWithPath: "/output-dir"),
+            fileManager: fileSystem,
+            htmlTemplate: URL(fileURLWithPath: "/template/index.html"),
+            prettyPrintOutput: true
+        )
+        
+        _ = try ConvertActionConverter.convert(
+            context: context,
+            outputConsumer: TestOutputConsumer(),
+            htmlContentConsumer: htmlConsumer,
+            sourceRepository: nil,
+            emitDigest: false,
+            documentationCoverageOptions: .noCoverage
+        )
+        
+        // Because the TestOutputConsumer below, doesn't create any files, we only expect the HTML files in the output directory
+        XCTAssertEqual(fileSystem.dump(subHierarchyFrom: "/output"), """
+        output-dir/
+        ╰─ documentation/
+           ╰─ ModuleName/
+              ├─ SomeClass/
+              │  ╰─ index.html
+              ╰─ index.html
+        """)
+        
+        
+        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/ModuleName/index.html")), encoding: .utf8)), """
+        <html>
+          <head>
+            <meta charset="utf-8" />
+            <link rel="icon" href="/favicon.ico" />
+            <title>ModuleName</title>
+            <script>var baseUrl = "/"</script>
+          </head>
+          <body>
+            <noscript><main>
+        <article>
+            <div id="hero-module">
+                <section>
+                    <header>
+                        <nav id="breadcrumbs">
+                            <ul>
+                                <li>
+                                    <span class="swift-only">ModuleName</span>
+                                </li>
+                            </ul>
+                        </nav>
+                        <span class="eyebrow">Framework</span>
+                    </header>
+                    <h1>Module<wbr/>
+                        Name</h1>
+                    <p id="abstract">Some description of this module</p>
+                    <pre id="declaration"/>
+                </section>
+            </div>
+            <section>
+                <h2 id="Topics">
+                    <a href="#Topics">Topics</a>
+                </h2>
+                <h3 id="Classes">
+                    <a href="#Classes">Classes</a>
+                </h3>
+                <div class="link-block">
+                    <a href="SomeClass/index.html">
+                        <code class="swift-only">
+                            <span class="identifier">Some<wbr/>
+                                Class</span>
+                        </code>
+                    </a>
+                    <p>Some in-source description of this class</p>
+                </div>
+            </section>
+        </article>
+        </main></noscript>
+            <div id="app"></div>
+          </body>
+        </html>
+        """)
+        
+        // FIXME: This output contains some unexpected duplication for the declaration.
+        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/ModuleName/SomeClass/index.html")), encoding: .utf8)), """
+        <html>
+          <head>
+            <meta charset="utf-8" />
+            <link rel="icon" href="/favicon.ico" />
+            <title>SomeClass</title>
+            <script>var baseUrl = "/"</script>
+          </head>
+          <body>
+            <noscript><main>
+        <article>
+            <section class="separated">
+                <header>
+                    <nav id="breadcrumbs">
+                        <ul>
+                            <li>
+                                <span class="swift-only">SomeClass</span>
+                            </li>
+                        </ul>
+                    </nav>
+                    <span class="eyebrow">Class</span>
+                </header>
+                <h1>Some<wbr/>
+                    Class</h1>
+                <p id="abstract">Some in-source description of this class</p>
+                <pre id="declaration">
+                    <code>
+                        <span class="token-keyword">class</span>
+                         <span class="token-identifier">SomeClass</span>
+                    </code>
+                </pre>
+                <pre class="swift-only">
+                    <code>
+                        <span class="token-keyword">class</span>
+                        <span class="token-text"> </span>
+                        <span class="token-identifier">SomeClass</span>
+                    </code>
+                </pre>
+            </section>
+        </article>
+        </main></noscript>
+            <div id="app"></div>
+          </body>
+        </html>
+        """)
+    }
+
+}
+
+private class TestOutputConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
+    func consume(renderNode: RenderNode) throws { }
+    func consume(assetsInBundle bundle: DocumentationBundle) throws { }
+    func consume(linkableElementSummaries: [LinkDestinationSummary]) throws { }
+    func consume(indexingRecords: [IndexingRecord]) throws { }
+    func consume(assets: [RenderReferenceType: [any RenderReference]]) throws { }
+    func consume(benchmarks: Benchmark) throws { }
+    func consume(documentationCoverageInfo: [CoverageDataEntry]) throws { }
+    func consume(renderReferenceStore: RenderReferenceStore) throws { }
+    func consume(buildMetadata: BuildMetadata) throws { }
+    func consume(linkResolutionInformation: SerializableLinkResolutionInformation) throws { }
+    func consume(externalRenderNode: ExternalRenderNode) throws { }
+}
diff --git a/Tests/SwiftDocCUtilitiesTests/MergeActionTests.swift b/Tests/SwiftDocCUtilitiesTests/MergeActionTests.swift
index 88acc2a5c2..a54d36221a 100644
--- a/Tests/SwiftDocCUtilitiesTests/MergeActionTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/MergeActionTests.swift
@@ -940,7 +940,7 @@ class MergeActionTests: XCTestCase {
             
             let outputConsumer = ConvertFileWritingConsumer(targetFolder: outputPath, bundleRootFolder: catalogDir, fileManager: fileSystem, context: context, indexer: indexer, transformForStaticHostingIndexHTML: nil, bundleID: inputs.id)
             
-            let convertProblems = try ConvertActionConverter.convert(context: context, outputConsumer: outputConsumer, sourceRepository: nil, emitDigest: false, documentationCoverageOptions: .noCoverage)
+            let convertProblems = try ConvertActionConverter.convert(context: context, outputConsumer: outputConsumer, htmlContentConsumer: nil, sourceRepository: nil, emitDigest: false, documentationCoverageOptions: .noCoverage)
             XCTAssert(convertProblems.isEmpty, "Unexpected problems: \(context.problems.map(\.diagnostic.summary).joined(separator: "\n"))", file: file, line: line)
             
             let navigatorProblems = indexer.finalize(emitJSON: true, emitLMDB: false)

From bffc1c581c50a3711cbbf71fbd9600111332484c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 26 Nov 2025 10:37:31 +0100
Subject: [PATCH 30/68] Rename MarkupRender to MarkdownRenderer

---
 .../{MarkupRenderer.swift => MarkdownRenderer.swift}      | 5 ++++-
 Sources/DocCHTML/MarkupRenderer+Availability.swift        | 2 +-
 Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift         | 2 +-
 Sources/DocCHTML/MarkupRenderer+Declaration.swift         | 2 +-
 Sources/DocCHTML/MarkupRenderer+Parameters.swift          | 2 +-
 Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift | 4 ++--
 ...sts.swift => MarkdownRenderer+PageElementsTests.swift} | 8 +++-----
 ...kupRendererTests.swift => MarkdownRendererTests.swift} | 4 ++--
 8 files changed, 15 insertions(+), 14 deletions(-)
 rename Sources/DocCHTML/{MarkupRenderer.swift => MarkdownRenderer.swift} (98%)
 rename Tests/DocCHTMLTests/{MarkupRenderer+PageElementsTests.swift => MarkdownRenderer+PageElementsTests.swift} (98%)
 rename Tests/DocCHTMLTests/{MarkupRendererTests.swift => MarkdownRendererTests.swift} (99%)

diff --git a/Sources/DocCHTML/MarkupRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
similarity index 98%
rename from Sources/DocCHTML/MarkupRenderer.swift
rename to Sources/DocCHTML/MarkdownRenderer.swift
index 63fec3598a..f28deceb27 100644
--- a/Sources/DocCHTML/MarkupRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -11,7 +11,10 @@
 package import Foundation
 package import Markdown
 
-package struct MarkupRenderer<Provider: LinkProvider> {
+/// An HTML renderer for DocC markdown content.
+///
+/// Markdown elements that have different meaning depending on where they occur in the page structure (for example links in prose vs. links in topic sections) should be handled at a layer above this plain markdown renderer.
+package struct MarkdownRenderer<Provider: LinkProvider> {
     /// The path within the output archive to the page that this renderer renders.
     let path: URL
     /// A type that provides information about other pages that the rendered page references.
diff --git a/Sources/DocCHTML/MarkupRenderer+Availability.swift b/Sources/DocCHTML/MarkupRenderer+Availability.swift
index d03054e946..40bae389cf 100644
--- a/Sources/DocCHTML/MarkupRenderer+Availability.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Availability.swift
@@ -14,7 +14,7 @@ package import Foundation
 package import FoundationXML
 #endif
 
-package extension MarkupRenderer {
+package extension MarkdownRenderer {
     struct AvailabilityInfo {
         package var name: String
         package var introduced, deprecated: String?
diff --git a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
index 24bf4aead8..8c1d1672fe 100644
--- a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
@@ -14,7 +14,7 @@ package import Foundation
 package import FoundationXML
 #endif
 
-package extension MarkupRenderer {
+package extension MarkdownRenderer {
     /// Creates an HTML element for the breadcrumbs leading up to the renderer's reference.
     func breadcrumbs(references: [URL], currentPageNames: LinkedElement.Names) -> XMLNode {
         // Breadcrumbs handle symbols differently than most elements, so there's no point in sharing _this_ code
diff --git a/Sources/DocCHTML/MarkupRenderer+Declaration.swift b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
index 4df5b0d96a..db2c59b28c 100644
--- a/Sources/DocCHTML/MarkupRenderer+Declaration.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
@@ -16,7 +16,7 @@ package import FoundationXML
 
 package import SymbolKit
 
-package extension MarkupRenderer {
+package extension MarkdownRenderer {
  
     typealias DeclarationFragment = SymbolGraph.Symbol.DeclarationFragments.Fragment
     
diff --git a/Sources/DocCHTML/MarkupRenderer+Parameters.swift b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
index 9434950bd3..d2e2d5ba41 100644
--- a/Sources/DocCHTML/MarkupRenderer+Parameters.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
@@ -16,7 +16,7 @@ package import FoundationXML
 
 package import Markdown
 
-package extension MarkupRenderer {
+package extension MarkdownRenderer {
     struct ParameterInfo {
         package var name: String
         package var content: [any Markup]
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 5117bc50aa..5dbf546df9 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -146,7 +146,7 @@ struct HTMLRenderer {
     private let linkProvider: ContextLinkProvider
     private let filePath: URL
     
-    private let renderer: MarkupRenderer<ContextLinkProvider>
+    private let renderer: MarkdownRenderer<ContextLinkProvider>
     
     init(reference: ResolvedTopicReference, context: DocumentationContext, renderContext: RenderContext) {
         self.reference = reference
@@ -156,7 +156,7 @@ struct HTMLRenderer {
         self.linkProvider = linkProvider
         let filePath = ContextLinkProvider.filePath(for: reference)
         self.filePath = filePath
-        self.renderer = MarkupRenderer(path: filePath, linkProvider: linkProvider)
+        self.renderer = MarkdownRenderer(path: filePath, linkProvider: linkProvider)
     }
     
     private func path(to destination: ResolvedTopicReference) -> String {
diff --git a/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
similarity index 98%
rename from Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift
rename to Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index 6b18d419b8..9f537e1da6 100644
--- a/Tests/DocCHTMLTests/MarkupRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -14,7 +14,7 @@ import DocCHTML
 @testable import SwiftDocC
 import Markdown
 
-struct MarkupRenderer_PageElementsTests {
+struct MarkdownRenderer_PageElementsTests {
     @Test
     func testRenderBreadcrumbs() {
         let elements = [
@@ -353,8 +353,7 @@ struct MarkupRenderer_PageElementsTests {
     private func makeRenderer(
         elementsToReturn: [LinkedElement] = [],
         pathsToReturn: [String: URL] = [:],
-        assetsToReturn: [String: LinkedAsset] = [:]
-    ) -> MarkupRenderer<some LinkProvider> {
+    ) -> MarkdownRenderer<some LinkProvider> {
         let path = URL(string: "/documentation/ModuleName/Something/ThisPage/index.html")!
         
         var elementsByURL = [
@@ -372,12 +371,11 @@ struct MarkupRenderer_PageElementsTests {
             elementsByURL[element.path] = element
         }
         
-        return MarkupRenderer(
+        return MarkdownRenderer(
             path: path,
             linkProvider: MultiValueLinkProvider(
                 elementsToReturn: elementsByURL,
                 pathsToReturn: pathsToReturn,
-                assetsToReturn: assetsToReturn
             )
         )
     }
diff --git a/Tests/DocCHTMLTests/MarkupRendererTests.swift b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
similarity index 99%
rename from Tests/DocCHTMLTests/MarkupRendererTests.swift
rename to Tests/DocCHTMLTests/MarkdownRendererTests.swift
index f9f89f165f..01ebbb47a8 100644
--- a/Tests/DocCHTMLTests/MarkupRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
@@ -14,7 +14,7 @@ import DocCHTML
 @testable import SwiftDocC
 import Markdown
 
-struct MarkupRendererTests {
+struct MarkdownRendererTests {
     @Test
     func testRenderParagraphsWithFormattedText() {
         assert(
@@ -516,7 +516,7 @@ struct MarkupRendererTests {
         matches expectedHTML: String,
         sourceLocation: Testing.SourceLocation = #_sourceLocation
     ) {
-        let renderer = MarkupRenderer(
+        let renderer = MarkdownRenderer(
             path: URL(string: "/documentation/Something/ThisPage/index.html")!,
             linkProvider: SingleValueLinkProvider(
                 elementToReturn: elementToReturn,

From 75f45153ce9d9deafa95d79912b33ea8e8a346b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 26 Nov 2025 10:42:28 +0100
Subject: [PATCH 31/68] Remove the (JSON) RenderContext parameter

---
 .../ConvertActionConverter.swift              |  2 +-
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 56 +------------------
 2 files changed, 4 insertions(+), 54 deletions(-)

diff --git a/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift b/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
index 18a92484a6..1bb919da58 100644
--- a/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
+++ b/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
@@ -115,7 +115,7 @@ package enum ConvertActionConverter {
                     let entity = try context.entity(with: identifier)
                     
                     if let htmlContentConsumer {
-                        var renderer = HTMLRenderer(reference: identifier, context: context, renderContext: renderContext)
+                        var renderer = HTMLRenderer(reference: identifier, context: context)
                         
                         if let symbol = entity.semantic as? Symbol {
                             let renderedPageInfo = renderer.renderSymbol(symbol)
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 5dbf546df9..2d770369cc 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -141,17 +141,15 @@ private struct ContextLinkProvider: DocCHTML.LinkProvider {
 struct HTMLRenderer {
     let reference: ResolvedTopicReference
     let context: DocumentationContext
-    let renderContext: RenderContext
     
     private let linkProvider: ContextLinkProvider
     private let filePath: URL
     
     private let renderer: MarkdownRenderer<ContextLinkProvider>
     
-    init(reference: ResolvedTopicReference, context: DocumentationContext, renderContext: RenderContext) {
+    init(reference: ResolvedTopicReference, context: DocumentationContext) {
         self.reference = reference
         self.context = context
-        self.renderContext = renderContext
         let linkProvider = ContextLinkProvider(reference: reference, context: context)
         self.linkProvider = linkProvider
         let filePath = ContextLinkProvider.filePath(for: reference)
@@ -259,30 +257,7 @@ struct HTMLRenderer {
             separateCurationIfNeeded()
             articleElement.addChild(makeGroupedSection(seeAlso))
         }
-        if let taskGroup = AutomaticCuration.seeAlso(for: node, withTraits: [.swift, .objectiveC], context: context, renderContext: renderContext, renderer: .init(context: context)) {
-            separateCurationIfNeeded()
-            // Automatice SeeAlso
-            let section = XMLElement(name: "section")
-            
-            if let title = SeeAlsoSection.title {
-                section.addChild(
-                    .selfReferencingHeader(title: title)
-                )
-            }
-            if let heading = taskGroup.title {
-                section.addChild(
-                    .selfReferencingHeader(level: 3, title: heading)
-                )
-            }
-            
-            for link in taskGroup.references {
-                if let element = self.makeTopicSectionItem(for: link) {
-                    section.addChild(element)
-                }
-            }
-            
-            articleElement.addChild(section)
-        }
+        // TODO: Add a way of determining the _automatic_ SeeAlso sections that doesn't query the JSON RenderContext for information.
         
         return RenderedPageInfo(
             content: main,
@@ -566,32 +541,7 @@ struct HTMLRenderer {
             separateCurationIfNeeded()
             articleElement.addChild(makeGroupedSection(seeAlso))
         }
-        
-        if let taskGroup = AutomaticCuration.seeAlso(for: node, withTraits: [.swift, .objectiveC], context: context, renderContext: renderContext, renderer: .init(context: context)) {
-            // Automatice SeeAlso
-            let section = XMLElement(name: "section")
-            separateCurationIfNeeded()
-            
-            if let title = SeeAlsoSection.title {
-                section.addChild(
-                    .selfReferencingHeader(title: title)
-                )
-            }
-            
-            if let heading = taskGroup.title {
-                section.addChild(
-                    .selfReferencingHeader(level: 3, title: heading)
-                )
-            }
-            
-            for link in taskGroup.references {
-                if let element = self.makeTopicSectionItem(for: link) {
-                    section.addChild(element)
-                }
-            }
-            
-            articleElement.addChild(section)
-        }
+        // TODO: Add a way of determining the _automatic_ SeeAlso sections that doesn't query the JSON RenderContext for information.
         
         return RenderedPageInfo(
             content: main,

From 4307f2970c1a2bb1ef46e22f22238d5e6eb5a1c6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 26 Nov 2025 11:11:47 +0100
Subject: [PATCH 32/68] Display a nicer link text as a fallback for unresolved
 links

---
 Sources/DocCHTML/LinkProvider.swift           |  3 ++
 Sources/DocCHTML/MarkdownRenderer.swift       | 13 +++----
 .../Model/Rendering/HTML/HTMLRenderer.swift   |  5 +++
 .../MarkdownRenderer+PageElementsTests.swift  |  9 +++++
 .../DocCHTMLTests/MarkdownRendererTests.swift | 34 +++++++++++++++++--
 5 files changed, 53 insertions(+), 11 deletions(-)

diff --git a/Sources/DocCHTML/LinkProvider.swift b/Sources/DocCHTML/LinkProvider.swift
index 565ab11864..e4ee519b6e 100644
--- a/Sources/DocCHTML/LinkProvider.swift
+++ b/Sources/DocCHTML/LinkProvider.swift
@@ -21,6 +21,9 @@ package protocol LinkProvider {
     
     /// Provide information about an asset, or `nil` if the asset can't be found.
     func assetNamed(_ assetName: String) -> LinkedAsset?
+    
+    /// Fallback link text for a link string that the provider couldn't provide any information for.
+    func fallbackLinkText(linkString: String) -> String
 }
 
 package struct LinkedElement {
diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index f28deceb27..3fde25596a 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -176,10 +176,8 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
                 attributes: ["href": destination.absoluteString]
             )
         } else {
-            // FIXME: Add this to the protocol
-//            // If this is an unresolved documentation link, try to display only the name of the linked symbol; without the rest of its path and without its disambiguation.
-//            return .text(LinkCompletionTools.parse(linkString: destination.path).last?.name ?? "")
-            return .text(destination.path)
+            // If this is an unresolved documentation link, try to display only the name of the linked symbol; without the rest of its path and without its disambiguation
+            return .text(linkProvider.fallbackLinkText(linkString: destination.path))
         }
     }
     
@@ -187,11 +185,8 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
         guard let destination = symbolLink.destination.flatMap({ URL(string: $0) }),
               let linkedElement = linkProvider.element(for: destination)
         else {
-            // FIXME: Add this to the protocol
-//            // If this is an unresolved symbol link, try to display only the name of the linked symbol; without the rest of its path and without its disambiguation.
-//            let name = symbolLink.destination.flatMap { LinkCompletionTools.parse(linkString: $0).last?.name } ?? ""
-//            return .element(named: "code", children: [.text(name)])
-            return .element(named: "code", children: [.text(symbolLink.destination ?? "")])
+            // If this is an unresolved symbol link, try to display only the name of the linked symbol; without the rest of its path and without its disambiguation.
+            return .element(named: "code", children: [.text(linkProvider.fallbackLinkText(linkString: symbolLink.destination ?? ""))])
         }
         
         let children: [XMLNode] = switch linkedElement.names {
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 2d770369cc..effd8440cc 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -133,6 +133,11 @@ private struct ContextLinkProvider: DocCHTML.LinkProvider {
         return .init(images: images)
     }
     
+    func fallbackLinkText(linkString: String) -> String {
+        // For unresolved links, especially to symbols, prefer to display only the the last link component without its disambiguation
+        PathHierarchy.PathParser.parse(path: linkString).components.last.map { String($0.name) } ?? linkString
+    }
+    
     static func filePath(for reference: ResolvedTopicReference) -> URL {
         reference.url.withoutHostAndPortAndScheme().appendingPathComponent("index.html")
     }
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index 9f537e1da6..10c9a00e8b 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -353,6 +353,8 @@ struct MarkdownRenderer_PageElementsTests {
     private func makeRenderer(
         elementsToReturn: [LinkedElement] = [],
         pathsToReturn: [String: URL] = [:],
+        assetsToReturn: [String: LinkedAsset] = [:],
+        fallbackLinkTextsToReturn: [String: String] = [:]
     ) -> MarkdownRenderer<some LinkProvider> {
         let path = URL(string: "/documentation/ModuleName/Something/ThisPage/index.html")!
         
@@ -376,6 +378,8 @@ struct MarkdownRenderer_PageElementsTests {
             linkProvider: MultiValueLinkProvider(
                 elementsToReturn: elementsByURL,
                 pathsToReturn: pathsToReturn,
+                assetsToReturn: assetsToReturn,
+                fallbackLinkTextsToReturn: fallbackLinkTextsToReturn
             )
         )
     }
@@ -401,4 +405,9 @@ struct MultiValueLinkProvider: LinkProvider {
     func assetNamed(_ assetName: String) -> LinkedAsset? {
         assetsToReturn[assetName]
     }
+    
+    var fallbackLinkTextsToReturn: [String: String]
+    func fallbackLinkText(linkString: String) -> String {
+        fallbackLinkTextsToReturn[linkString] ?? linkString
+    }
 }
diff --git a/Tests/DocCHTMLTests/MarkdownRendererTests.swift b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
index 01ebbb47a8..2efde5cd3d 100644
--- a/Tests/DocCHTMLTests/MarkdownRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
@@ -424,6 +424,29 @@ struct MarkdownRendererTests {
             <p><a href="../../SomeClass/someMethod(_:_:)/index.html">Some <code>Custom<wbr/>Symbol<wbr/>Name</code> title</a></p>
             """
         )
+        
+        // Unresolved documentation link with fallback link text
+        assert(
+            rendering: "<doc://com.example.test/documentation/Something/NotFound>", // Simulate a link that's unresolved
+            elementToReturn: nil,
+            fallbackLinkTextToReturn: "Some fallback link text",
+            prettyFormatted: true,
+            matches: """
+            <p>Some fallback link text</p>
+            """
+        )
+        // Unresolved _symbol_ link with fallback link text
+        assert(
+            rendering: "``ModuleName/NotFoundClass/someMethod(_:)-h1a2s3h``", // Simulate a symbol link that's unresolved
+            elementToReturn: nil,
+            fallbackLinkTextToReturn: "Some fallback link text",
+            prettyFormatted: true,
+            matches: """
+            <p>
+            <code>Some fallback link text</code>
+            </p>
+            """
+        )
     }
     
     @Test
@@ -512,6 +535,7 @@ struct MarkdownRendererTests {
         rendering markdownContent: String,
         elementToReturn: LinkedElement? = nil,
         assetToReturn: LinkedAsset? = nil,
+        fallbackLinkTextToReturn: String? = nil,
         prettyFormatted: Bool = false,
         matches expectedHTML: String,
         sourceLocation: Testing.SourceLocation = #_sourceLocation
@@ -520,10 +544,11 @@ struct MarkdownRendererTests {
             path: URL(string: "/documentation/Something/ThisPage/index.html")!,
             linkProvider: SingleValueLinkProvider(
                 elementToReturn: elementToReturn,
-                assetToReturn: assetToReturn
+                assetToReturn: assetToReturn,
+                fallbackLinkTextToReturn: fallbackLinkTextToReturn
             )
         )
-        let htmlNodes = Document(parsing: markdownContent).children.map { renderer.visit($0) }
+        let htmlNodes = Document(parsing: markdownContent, options: .parseSymbolLinks).children.map { renderer.visit($0) }
         let htmlString = htmlNodes.rendered(prettyFormatted: prettyFormatted)
         
         #expect(htmlString == expectedHTML, sourceLocation: sourceLocation)
@@ -592,4 +617,9 @@ struct SingleValueLinkProvider: LinkProvider {
     func assetNamed(_ assetName: String) -> LinkedAsset? {
         assetToReturn
     }
+    
+    var fallbackLinkTextToReturn: String?
+    func fallbackLinkText(linkString: String) -> String {
+        fallbackLinkTextToReturn ?? linkString
+    }
 }

From de5289fabbb3a82ead327ceda56873fd5fe8443f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 26 Nov 2025 11:47:03 +0100
Subject: [PATCH 33/68] Prefer SourceLanguage type over string identifiers for
 languages

---
 Package.swift                                 |  1 +
 Sources/DocCHTML/LinkProvider.swift           |  5 ++--
 Sources/DocCHTML/MarkdownRenderer.swift       |  8 +++---
 .../DocCHTML/MarkupRenderer+Breadcrumbs.swift |  4 +--
 .../DocCHTML/MarkupRenderer+Declaration.swift |  7 ++---
 .../DocCHTML/MarkupRenderer+Parameters.swift  | 27 +++++++++++--------
 Sources/DocCHTML/WordBreak.swift              | 15 +++--------
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 19 +++++++------
 .../MarkdownRenderer+PageElementsTests.swift  | 26 +++++++++---------
 .../DocCHTMLTests/MarkdownRendererTests.swift |  8 +++---
 10 files changed, 60 insertions(+), 60 deletions(-)

diff --git a/Package.swift b/Package.swift
index ceb0f804e6..b1d3e3fbd7 100644
--- a/Package.swift
+++ b/Package.swift
@@ -139,6 +139,7 @@ let package = Package(
         .target(
             name: "DocCHTML",
             dependencies: [
+                .target(name: "DocCCommon"),
                 .product(name: "Markdown", package: "swift-markdown"),
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
             ],
diff --git a/Sources/DocCHTML/LinkProvider.swift b/Sources/DocCHTML/LinkProvider.swift
index e4ee519b6e..b44dda554f 100644
--- a/Sources/DocCHTML/LinkProvider.swift
+++ b/Sources/DocCHTML/LinkProvider.swift
@@ -10,6 +10,7 @@
 
 package import Foundation
 package import Markdown
+package import DocCCommon
 
 /// A type that provides information about other pages, and on-page elements, that the rendered page references.
 package protocol LinkProvider {
@@ -56,7 +57,7 @@ package struct LinkedElement {
         /// This element is a symbol with different names in different languages.
         ///
         /// Because `@DisplayName` applies to all language representations, these language specific names are always the symbol's subheading declaration and should display in a monospaced font.
-        case languageSpecificSymbol([String /* Language ID */: String])
+        case languageSpecificSymbol([SourceLanguage: String])
     }
     package enum Name {
         /// The name refers to an article, heading, or custom `@DisplayName` and should display as regular text.
@@ -72,7 +73,7 @@ package struct LinkedElement {
         /// This element is a symbol with different names in different languages.
         ///
         /// Because `@DisplayName` applies to all language representations, these language specific names are always the symbol's subheading declaration and should display in a monospaced font.
-        case languageSpecificSymbol([String /* Language ID */: [SymbolNameFragment]])
+        case languageSpecificSymbol([SourceLanguage: [SymbolNameFragment]])
     }
     package enum Subheading {
         /// The name refers to an article, heading, or custom `@DisplayName` and should display as regular text.
diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index 3fde25596a..42b2449149 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -158,8 +158,8 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
                     }
                     
                 case .languageSpecificSymbol(let namesByLanguageID):
-                    RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { languageID, name in
-                        .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
+                    RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { language, name in
+                        .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(language.id)-only"])
                     }
             }
             
@@ -197,8 +197,8 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
                 }
                 
             case .languageSpecificSymbol(let namesByLanguageID):
-                RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { languageID, name in
-                    .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(languageID)-only"])
+                RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { language, name in
+                    .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(language.id)-only"])
                 }
         }
         
diff --git a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
index 8c1d1672fe..c904f55813 100644
--- a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
@@ -25,10 +25,10 @@ package extension MarkdownRenderer {
                 [.text(name)]
                 
             case .languageSpecificSymbol(let namesByLanguageID):
-                RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { languageID, name in
+                RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { language, name in
                     .element(named: "span", children: [
                         .text(name) // Breadcrumbs display symbol names in a default style (no "code voice")
-                    ], attributes: ["class": "\(languageID)-only"])
+                    ], attributes: ["class": "\(language.id)-only"])
                 }
             }
         }
diff --git a/Sources/DocCHTML/MarkupRenderer+Declaration.swift b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
index db2c59b28c..710489c9fa 100644
--- a/Sources/DocCHTML/MarkupRenderer+Declaration.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
@@ -14,21 +14,22 @@ package import Foundation
 package import FoundationXML
 #endif
 
+package import DocCCommon
 package import SymbolKit
 
 package extension MarkdownRenderer {
  
     typealias DeclarationFragment = SymbolGraph.Symbol.DeclarationFragments.Fragment
     
-    func declaration(_ fragmentsByLanguage: [String /* Language ID*/: [DeclarationFragment]]) -> XMLElement {
+    func declaration(_ fragmentsByLanguage: [SourceLanguage: [DeclarationFragment]]) -> XMLElement {
         let fragmentsByLanguage = RenderHelpers.sortedLanguageSpecificValues(fragmentsByLanguage)
         // Note: declarations scroll, so they don't need to word wrap within tokens
         
         let declarations: [XMLElement] = if fragmentsByLanguage.count == 1 {
             [XMLNode.element(named: "code", children: _declarationTokens(for: fragmentsByLanguage.first!.value))]
         } else {
-            fragmentsByLanguage.map { languageID, fragments in
-                XMLNode.element(named: "code", children: _declarationTokens(for: fragments), attributes: ["class": "\(languageID)-only"])
+            fragmentsByLanguage.map { language, fragments in
+                XMLNode.element(named: "code", children: _declarationTokens(for: fragments), attributes: ["class": "\(language.id)-only"])
             }
         }
         return .element(named: "pre", children: declarations, attributes: ["id": "declaration"])
diff --git a/Sources/DocCHTML/MarkupRenderer+Parameters.swift b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
index d2e2d5ba41..6e4c30544b 100644
--- a/Sources/DocCHTML/MarkupRenderer+Parameters.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
@@ -15,6 +15,7 @@ package import FoundationXML
 #endif
 
 package import Markdown
+package import DocCCommon
 
 package extension MarkdownRenderer {
     struct ParameterInfo {
@@ -27,7 +28,7 @@ package extension MarkdownRenderer {
         }
     }
     
-    func parameters(_ info: [String: [ParameterInfo]]) -> XMLNode {
+    func parameters(_ info: [SourceLanguage: [ParameterInfo]]) -> XMLNode {
         let info = RenderHelpers.sortedLanguageSpecificValues(info)
         
         // Add a heading that references the section before anything the actual parameter list
@@ -49,11 +50,11 @@ package extension MarkdownRenderer {
         default:
             // In practice DocC only encounters one or two different languages. If there would be a third one,
             // produce correct looking pages that may include duplicated markup by not trying to share parameters across languages.
-            items.append(contentsOf: info.map { languageID, info in
+            items.append(contentsOf: info.map { language, info in
                 .element(
                     named: "dl",
                     children: _singleLanguageParameterItems(info),
-                    attributes: ["class": "\(languageID)-only"]
+                    attributes: ["class": "\(language.id)-only"]
                 )
             })
         }
@@ -85,12 +86,16 @@ package extension MarkdownRenderer {
     }
     
     private func _dualLanguageParameters(
-        primary: (key: String, value: [ParameterInfo]),
-        secondary: (key: String, value: [ParameterInfo])
+        primary:   (key: SourceLanguage, value: [ParameterInfo]),
+        secondary: (key: SourceLanguage, value: [ParameterInfo])
     ) -> XMLElement {
-        var items = _singleLanguageParameterItems(primary.value)
+        // Shadow the parameters with more descriptive tuple labels
+        let primary   = (language: primary.key,   parameters: primary.value)
+        let secondary = (language: secondary.key, parameters: secondary.value)
         
-        let differences = secondary.value.difference(from: primary.value, by: { $0.name == $1.name })
+        var items = _singleLanguageParameterItems(primary.parameters)
+        
+        let differences = secondary.parameters.difference(from: primary.parameters, by: { $0.name == $1.name })
         
         var primaryOnlyIndices = Set<Int>()
         
@@ -99,8 +104,8 @@ package extension MarkdownRenderer {
             primaryOnlyIndices.insert(offset)
             let index = offset * 2
             // Mark those items as only being applying to the first language
-            items[index    ].addAttributes(["class": "\(primary.key)-only"])
-            items[index + 1].addAttributes(["class": "\(primary.key)-only"])
+            items[index    ].addAttributes(["class": "\(primary.language.id)-only"])
+            items[index + 1].addAttributes(["class": "\(primary.language.id)-only"])
         }
         
         for case let .insert(offset, parameter, _) in differences.insertions {
@@ -111,9 +116,9 @@ package extension MarkdownRenderer {
                 // Name
                 .element(named: "dt", children: [
                     .element(named: "code", children: [.text(parameter.name)])
-                ], attributes: ["class": "\(secondary.key)-only"]),
+                ], attributes: ["class": "\(secondary.language.id)-only"]),
                 // Description
-                .element(named: "dd", children: parameter.content.map { visit($0) }, attributes: ["class": "\(secondary.key)-only"])
+                .element(named: "dd", children: parameter.content.map { visit($0) }, attributes: ["class": "\(secondary.language.id)-only"])
             ], at: index)
         }
         
diff --git a/Sources/DocCHTML/WordBreak.swift b/Sources/DocCHTML/WordBreak.swift
index 7cb072b5e6..d8b9ddad8c 100644
--- a/Sources/DocCHTML/WordBreak.swift
+++ b/Sources/DocCHTML/WordBreak.swift
@@ -14,6 +14,8 @@ package import Foundation
 package import FoundationXML
 #endif
 
+package import DocCCommon
+
 package enum RenderHelpers {
     /// Inserts `<wbr/>` elements into a symbol name so that it can wrap better on the rendered page.
     ///
@@ -55,17 +57,8 @@ package enum RenderHelpers {
     }
     
     /// Returns the language specific symbol names sorted by the language.
-    package static func sortedLanguageSpecificValues<Value>(_ valuesByLanguageID: [String /* language ID */: Value]) -> [(key: String, value: Value)] {
-        valuesByLanguageID.sorted(by: { lhs, rhs in
-            // Sort Swift before other languages.
-            if lhs.key == "swift" {
-                return true
-            } else if rhs.key == "swift" {
-                return false
-            }
-            // Otherwise, sort by ID for a stable order.
-            return lhs.key < rhs.key
-        })
+    package static func sortedLanguageSpecificValues<Value>(_ valuesByLanguageID: [SourceLanguage: Value]) -> [(key: SourceLanguage, value: Value)] {
+        valuesByLanguageID.sorted(by: { lhs, rhs in lhs.key < rhs.key })
     }
 }
 
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index effd8440cc..750c9b7bcf 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -37,9 +37,9 @@ private struct ContextLinkProvider: DocCHTML.LinkProvider {
             
             if titles.contains(where: { _, title in title != primaryTitle }) {
                // This symbol has multiple unique names
-                let titles = [String: String](
+                let titles = [SourceLanguage: String](
                     titles.map { trait, title in
-                        ((trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift).id, title)
+                        ((trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift), title)
                     },
                     uniquingKeysWith: { _, new in new }
                 )
@@ -91,7 +91,7 @@ private struct ContextLinkProvider: DocCHTML.LinkProvider {
                 // This symbol has multiple unique names
                 subheadings = .languageSpecificSymbol(.init(
                     allSubheadings.map { trait, subheading in (
-                        key:   (trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift).id,
+                        key:   (trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift),
                         value: convert(subheading)
                     )},
                     uniquingKeysWith: { _, new in new }
@@ -296,10 +296,10 @@ struct HTMLRenderer {
         if case .conceptual(title: let title) = node.name {
             names = .single(.conceptual(title))
         } else {
-            names = .languageSpecificSymbol([String: String](
+            names = .languageSpecificSymbol([SourceLanguage: String](
                 symbol.titleVariants.allValues.compactMap({ trait, title in
-                    guard let lang = trait.interfaceLanguage else { return nil }
-                    return (key: lang, value: title)
+                    guard let languageID = trait.interfaceLanguage else { return nil }
+                    return (key: SourceLanguage(id: languageID), value: title)
                 }),
                 uniquingKeysWith: { _, new in new }
             ))
@@ -380,10 +380,10 @@ struct HTMLRenderer {
         if !symbol.declarationVariants.allValues.isEmpty {
             // FIXME: Display platform specific declarations
             
-            var fragmentsByLanguageID = [String: [SymbolGraph.Symbol.DeclarationFragments.Fragment]]()
+            var fragmentsByLanguageID = [SourceLanguage: [SymbolGraph.Symbol.DeclarationFragments.Fragment]]()
             for (trait, variant) in symbol.declarationVariants.allValues {
                 guard let languageID = trait.interfaceLanguage else { continue }
-                fragmentsByLanguageID[languageID] = variant.values.first?.declarationFragments
+                fragmentsByLanguageID[SourceLanguage(id: languageID)] = variant.values.first?.declarationFragments
             }
             
             hero.addChild( renderer.declaration(fragmentsByLanguageID) )
@@ -439,14 +439,13 @@ struct HTMLRenderer {
             )
         }
         
-        
         // Parameters
         if !symbol.parametersSectionVariants.allValues.isEmpty {
             articleElement.addChild(
                 renderer.parameters(
                     .init(
                         symbol.parametersSectionVariants.allValues.map { trait, parameters in (
-                            key:   trait.interfaceLanguage ?? "swift",
+                            key:   trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift,
                             value: parameters.parameters.map {
                                 .init(name: $0.name, content: $0.contents)
                             }
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index 10c9a00e8b..99ddcc7e92 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -27,15 +27,15 @@ struct MarkdownRenderer_PageElementsTests {
             LinkedElement(
                 path: URL(string: "/documentation/ModuleName/Something/index.html")!,
                 names: .languageSpecificSymbol([
-                    "swift": "Something",
-                    "occ": "TLASomething",
+                    .swift:      "Something",
+                    .objectiveC: "TLASomething",
                 ]),
                 subheadings: .languageSpecificSymbol([
-                    "swift": [
+                    .swift: [
                         .init(text: "class ", kind: .decorator),
                         .init(text: "Something", kind: .identifier),
                     ],
-                    "occ": [
+                    .objectiveC: [
                         .init(text: "class ", kind: .decorator),
                         .init(text: "TLASomething", kind: .identifier),
                     ],
@@ -82,7 +82,7 @@ struct MarkdownRenderer_PageElementsTests {
     @Test
     func testRenderSingleLanguageParameters() {
         let parameters = makeRenderer().parameters([
-            "swift": [
+            .swift: [
                 .init(name: "First", content: parseMarkup(string: "Some _formatted_ description with `code`")),
                 .init(name: "Second", content: parseMarkup(string: """
                 Some **other** _formatted_ description
@@ -122,12 +122,12 @@ struct MarkdownRenderer_PageElementsTests {
     @Test
     func testRenderLanguageSpecificParameters() {
         let parameters = makeRenderer().parameters([
-            "swift": [
+            .swift: [
                 .init(name: "FirstCommon", content: parseMarkup(string: "Available in both languages")),
                 .init(name: "SwiftOnly", content: parseMarkup(string: "Only available in Swift")),
                 .init(name: "SecondCommon", content: parseMarkup(string: "Also available in both languages")),
             ],
-            "occ": [
+            .objectiveC: [
                 .init(name: "FirstCommon", content: parseMarkup(string: "Available in both languages")),
                 .init(name: "SecondCommon", content: parseMarkup(string: "Also available in both languages")),
                 .init(name: "ObjectiveCOnly", content: parseMarkup(string: "Only available in Objective-C")),
@@ -171,13 +171,13 @@ struct MarkdownRenderer_PageElementsTests {
     @Test
     func testRenderManyLanguageSpecificParameters() {
         let parameters = makeRenderer().parameters([
-            "swift": [
+            .swift: [
                 .init(name: "First", content: parseMarkup(string: "Some description")),
             ],
-            "occ": [
+            .objectiveC: [
                 .init(name: "Second", content: parseMarkup(string: "Some description")),
             ],
-            "data": [
+            .data: [
                 .init(name: "Third", content: parseMarkup(string: "Some description")),
             ],
         ])
@@ -223,7 +223,7 @@ struct MarkdownRenderer_PageElementsTests {
         ]
         
         let declaration = makeRenderer(pathsToReturn: symbolPaths).declaration([
-            "swift":  [
+            .swift:  [
                 .init(kind: .keyword,           spelling: "func",        preciseIdentifier: nil),
                 .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
                 .init(kind: .identifier,        spelling: "doSomething", preciseIdentifier: nil),
@@ -273,7 +273,7 @@ struct MarkdownRenderer_PageElementsTests {
         ]
         
         let declaration = makeRenderer(pathsToReturn: symbolPaths).declaration([
-            "swift":  [
+            .swift:  [
                 .init(kind: .keyword,           spelling: "func",        preciseIdentifier: nil),
                 .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
                 .init(kind: .identifier,        spelling: "doSomething", preciseIdentifier: nil),
@@ -295,7 +295,7 @@ struct MarkdownRenderer_PageElementsTests {
                 .init(kind: .typeIdentifier,    spelling: "ReturnValue", preciseIdentifier: "return-value-symbol-id"),
             ],
             
-            "occ":  [
+            .objectiveC:  [
                 .init(kind: .text,              spelling: "- (",         preciseIdentifier: nil),
                 .init(kind: .typeIdentifier,    spelling: "ReturnValue", preciseIdentifier: "return-value-symbol-id"),
                 .init(kind: .text,              spelling: ") ",          preciseIdentifier: nil),
diff --git a/Tests/DocCHTMLTests/MarkdownRendererTests.swift b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
index 2efde5cd3d..f96916bb82 100644
--- a/Tests/DocCHTMLTests/MarkdownRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
@@ -558,11 +558,11 @@ struct MarkdownRendererTests {
         LinkedElement(
             path: URL(string: "doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:)/index.html")!,
             names: .languageSpecificSymbol([
-                SourceLanguage.swift.id : "doSomething(with:and:)",
-                SourceLanguage.objectiveC.id: "doSomethingWithFirst:andSecond:",
+                .swift:      "doSomething(with:and:)",
+                .objectiveC: "doSomethingWithFirst:andSecond:",
             ]),
             subheadings: .languageSpecificSymbol([ // Not relevant for inline links
-                SourceLanguage.swift.id: [
+                .swift: [
                     .init(text: "func ", kind: .decorator),
                     .init(text: "doSomething", kind: .identifier),
                     .init(text: "(", kind: .decorator),
@@ -571,7 +571,7 @@ struct MarkdownRendererTests {
                     .init(text: "and", kind: .identifier),
                     .init(text: ")", kind: .decorator),
                 ],
-                SourceLanguage.objectiveC.id: [
+                .objectiveC: [
                     .init(text: "doSomethingWithFirst", kind: .identifier),
                     .init(text: ":", kind: .decorator),
                     .init(text: "andSecond", kind: .identifier),

From cb318b55ba34843ada488f91dffaa5d5eba9bfea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 26 Nov 2025 15:28:35 +0100
Subject: [PATCH 34/68] Support creating a minimal/concise HTML content for
 machine consumption

---
 Sources/DocCHTML/MarkdownRenderer.swift       |  15 +-
 .../MarkupRenderer+Availability.swift         |   2 +-
 .../DocCHTML/MarkupRenderer+Breadcrumbs.swift |  31 ++-
 .../DocCHTML/MarkupRenderer+Declaration.swift |   9 +
 .../DocCHTML/MarkupRenderer+Parameters.swift  |  12 +-
 .../ConvertActionConverter.swift              |   2 +-
 .../Model/Rendering/HTML/HTMLRenderer.swift   |  14 +-
 .../MarkdownRenderer+PageElementsTests.swift  | 246 +++++++++++-------
 .../DocCHTMLTests/MarkdownRendererTests.swift |   1 +
 9 files changed, 213 insertions(+), 119 deletions(-)

diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index 42b2449149..1593ce87b9 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -11,17 +11,30 @@
 package import Foundation
 package import Markdown
 
+/// The primary goal for the rendered HTML output.
+package enum RenderGoal {
+    /// The rendered output should prioritize quality, optimizing for human consumption.
+    ///
+    /// The rendered output might include explicit work-breaks, syntax highlighted code, etc.
+    case quality
+    /// The minimalistic rendered output should prioritize conciseness, optimizing for consumption by machines such as SEO indexers or LLMs.
+    case conciseness
+}
+
 /// An HTML renderer for DocC markdown content.
 ///
 /// Markdown elements that have different meaning depending on where they occur in the page structure (for example links in prose vs. links in topic sections) should be handled at a layer above this plain markdown renderer.
 package struct MarkdownRenderer<Provider: LinkProvider> {
     /// The path within the output archive to the page that this renderer renders.
     let path: URL
+    /// The goal of the rendered HTML output.
+    let goal: RenderGoal
     /// A type that provides information about other pages that the rendered page references.
     let linkProvider: Provider
     
-    package init(path: URL, linkProvider: Provider) {
+    package init(path: URL, goal: RenderGoal, linkProvider: Provider) {
         self.path = path
+        self.goal = goal
         self.linkProvider = linkProvider
     }
     
diff --git a/Sources/DocCHTML/MarkupRenderer+Availability.swift b/Sources/DocCHTML/MarkupRenderer+Availability.swift
index 40bae389cf..90d6b85c2f 100644
--- a/Sources/DocCHTML/MarkupRenderer+Availability.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Availability.swift
@@ -57,7 +57,7 @@ package extension MarkdownRenderer {
                 attributes["class"] = "deprecated"
             }
             
-            return .element(named: "li", children: [.text(text)], attributes: attributes)
+            return .element(named: "li", children: [.text(text)], attributes: goal == .quality ? attributes : [:])
         }
         
         return .element(
diff --git a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
index c904f55813..b350065df4 100644
--- a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
@@ -22,13 +22,22 @@ package extension MarkdownRenderer {
             switch names {
             // Breadcrumbs display both symbolic names and conceptual in a default style
             case .single(.conceptual(let name)), .single(.symbol(let name)):
-                [.text(name)]
+                return [.text(name)]
                 
             case .languageSpecificSymbol(let namesByLanguageID):
-                RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { language, name in
-                    .element(named: "span", children: [
-                        .text(name) // Breadcrumbs display symbol names in a default style (no "code voice")
-                    ], attributes: ["class": "\(language.id)-only"])
+                let names = RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID)
+                return switch goal {
+                case .quality:
+                    names.map { language, name in
+                        .element(named: "span", children: [
+                            .text(name) // Breadcrumbs display symbol names in a default style (no "code voice")
+                        ], attributes: ["class": "\(language.id)-only"])
+                    }
+                case .conciseness:
+                    // If the goal is conciseness, only display the primary language's name
+                    names.first.map { _, name in
+                        [.text(name)]
+                    } ?? []
                 }
             }
         }
@@ -45,11 +54,13 @@ package extension MarkdownRenderer {
         items.append(
             .element(named: "li", children: nameElements(for: currentPageNames))
         )
+        let list = XMLNode.element(named: "ul", children: items)
         
-        return .element(
-            named: "nav",
-            children: [.element(named: "ul", children: items)],
-            attributes: ["id": "breadcrumbs"]
-        )
+        return switch goal {
+        case .conciseness:
+            list
+        case .quality:
+            .element(named: "nav", children: [list], attributes: ["id": "breadcrumbs"])
+        }
     }
 }
diff --git a/Sources/DocCHTML/MarkupRenderer+Declaration.swift b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
index 710489c9fa..22116d9869 100644
--- a/Sources/DocCHTML/MarkupRenderer+Declaration.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
@@ -23,6 +23,15 @@ package extension MarkdownRenderer {
     
     func declaration(_ fragmentsByLanguage: [SourceLanguage: [DeclarationFragment]]) -> XMLElement {
         let fragmentsByLanguage = RenderHelpers.sortedLanguageSpecificValues(fragmentsByLanguage)
+        
+        guard goal == .quality else {
+            // If the goal is conciseness, display only the primary language's plain text declaration in a <code> block
+            let plainTextDeclaration: [XMLNode] = fragmentsByLanguage.first.map { _, fragments in
+                [.element(named: "code", children: [.text(fragments.map(\.spelling).joined())])]
+            } ?? []
+            return .element(named: "pre", children: plainTextDeclaration, attributes: ["id": "declaration"])
+        }
+        
         // Note: declarations scroll, so they don't need to word wrap within tokens
         
         let declarations: [XMLElement] = if fragmentsByLanguage.count == 1 {
diff --git a/Sources/DocCHTML/MarkupRenderer+Parameters.swift b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
index 6e4c30544b..5197b7f0cc 100644
--- a/Sources/DocCHTML/MarkupRenderer+Parameters.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
@@ -32,10 +32,14 @@ package extension MarkdownRenderer {
         let info = RenderHelpers.sortedLanguageSpecificValues(info)
         
         // Add a heading that references the section before anything the actual parameter list
+        let header = switch goal {
+        case .quality:
+            XMLNode.element(named: "a", children: [.text("Parameters")], attributes: ["href": "#parameters"])
+        case .conciseness:
+            XMLNode.text("Parameters")
+        }
         var items: [XMLElement] = [
-            .element(named: "h2", children: [
-                .element(named: "a", children: [.text("Parameters")], attributes: ["href": "#parameters"])
-            ])
+            .element(named: "h2", children: [header])
         ]
         
         switch info.count {
@@ -59,7 +63,7 @@ package extension MarkdownRenderer {
             })
         }
         
-        return .element(named: "section", children: items, attributes: ["id": "parameters"])
+        return .element(named: "section", children: items, attributes: goal == .quality ? ["id": "parameters"] : [:])
     }
     
     private func _singleLanguageParameters(_ parameterInfo: [ParameterInfo]) -> XMLElement {
diff --git a/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift b/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
index 1bb919da58..096d7b5383 100644
--- a/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
+++ b/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
@@ -115,7 +115,7 @@ package enum ConvertActionConverter {
                     let entity = try context.entity(with: identifier)
                     
                     if let htmlContentConsumer {
-                        var renderer = HTMLRenderer(reference: identifier, context: context)
+                        var renderer = HTMLRenderer(reference: identifier, context: context, goal: .quality)
                         
                         if let symbol = entity.semantic as? Symbol {
                             let renderedPageInfo = renderer.renderSymbol(symbol)
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 750c9b7bcf..c8a07f22c5 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -146,20 +146,22 @@ private struct ContextLinkProvider: DocCHTML.LinkProvider {
 struct HTMLRenderer {
     let reference: ResolvedTopicReference
     let context: DocumentationContext
+    let goal: RenderGoal
     
     private let linkProvider: ContextLinkProvider
     private let filePath: URL
     
     private let renderer: MarkdownRenderer<ContextLinkProvider>
     
-    init(reference: ResolvedTopicReference, context: DocumentationContext) {
+    init(reference: ResolvedTopicReference, context: DocumentationContext, goal: RenderGoal) {
         self.reference = reference
         self.context = context
+        self.goal = goal
         let linkProvider = ContextLinkProvider(reference: reference, context: context)
         self.linkProvider = linkProvider
         let filePath = ContextLinkProvider.filePath(for: reference)
         self.filePath = filePath
-        self.renderer = MarkdownRenderer(path: filePath, linkProvider: linkProvider)
+        self.renderer = MarkdownRenderer(path: filePath, goal: goal, linkProvider: linkProvider)
     }
     
     private func path(to destination: ResolvedTopicReference) -> String {
@@ -210,11 +212,7 @@ struct HTMLRenderer {
         
         // Title
         hero.addChild(
-            .element(
-                named: "h1",
-                children: [.text(node.name.plainText)],
-                attributes: ["class": "title"]
-            )
+            .element(named: "h1", children: [.text(node.name.plainText)])
         )
         
         // Abstract
@@ -235,7 +233,7 @@ struct HTMLRenderer {
         var hasMadeSeparatedCuration = false
         
         func separateCurationIfNeeded() {
-            guard !hasMadeSeparatedCuration else {
+            guard !hasMadeSeparatedCuration, goal == .quality else {
                 return
             }
             
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index 99ddcc7e92..f0cc18190d 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -15,8 +15,8 @@ import DocCHTML
 import Markdown
 
 struct MarkdownRenderer_PageElementsTests {
-    @Test
-    func testRenderBreadcrumbs() {
+    @Test(arguments: RenderGoal.allCases)
+    func testRenderBreadcrumbs(goal: RenderGoal) {
         let elements = [
             LinkedElement(
                 path: URL(string: "/documentation/ModuleName/index.html")!,
@@ -43,45 +43,70 @@ struct MarkdownRenderer_PageElementsTests {
                 abstract: nil
             ),
         ]
-        let breadcrumbs = makeRenderer(elementsToReturn: elements).breadcrumbs(references: elements.map { $0.path }, currentPageNames: .single(.conceptual("ThisPage")))
-        
-        #expect(breadcrumbs.rendered(prettyFormatted: true) == """
-        <nav id="breadcrumbs">
-        <ul>
+        let breadcrumbs = makeRenderer(goal: goal, elementsToReturn: elements).breadcrumbs(references: elements.map { $0.path }, currentPageNames: .single(.conceptual("ThisPage")))
+        switch goal {
+        case .quality:
+            #expect(breadcrumbs.rendered(prettyFormatted: true) == """
+            <nav id="breadcrumbs">
+            <ul>
+                <li>
+                    <a href="../../../index.html">ModuleName</a>
+                </li>
+                <li>
+                    <a href="../../index.html">
+                        <span class="swift-only">Something</span>
+                        <span class="occ-only">TLASomething</span>
+                    </a>
+                </li>
+                <li>ThisPage</li>
+            </ul>
+            </nav>
+            """)
+        case .conciseness:
+            #expect(breadcrumbs.rendered(prettyFormatted: true) == """
+            <ul>
             <li>
                 <a href="../../../index.html">ModuleName</a>
             </li>
             <li>
-                <a href="../../index.html">
-                    <span class="swift-only">Something</span>
-                    <span class="occ-only">TLASomething</span>
-                </a>
+                <a href="../../index.html">Something</a>
             </li>
             <li>ThisPage</li>
-        </ul>
-        </nav>
-        """)
+            </ul>
+            """)
+        }
     }
     
-    @Test
-    func testRenderAvailability() {
-        let availability = makeRenderer().availability([
-            .init(name: "First", introduced: "1.2", deprecated: "3.4", isBeta: false),
-            .init(name: "Second", introduced: "1.2.3", isBeta: false),
-            .init(name: "Third", introduced: "4.5", isBeta: true),
+    @Test(arguments: RenderGoal.allCases)
+    func testRenderAvailability(goal: RenderGoal) {
+        let availability = makeRenderer(goal: goal).availability([
+            .init(name: "First",  introduced: "1.2", deprecated: "3.4", isBeta: false),
+            .init(name: "Second", introduced: "1.2.3",                  isBeta: false),
+            .init(name: "Third",  introduced: "4.5",                    isBeta: true),
         ])
-        #expect(availability.rendered(prettyFormatted: true) == """
-        <ul id="availability">
-        <li aria-label="First 1.2–3.4, Introduced in First 1.2 and deprecated in First 3.4" class="deprecated" role="text" title="Introduced in First 1.2 and deprecated in First 3.4">First 1.2–3.4</li>
-        <li aria-label="Second 1.2.3+, Available on 1.2.3 and later" role="text" title="Available on 1.2.3 and later">Second 1.2.3+</li>
-        <li aria-label="Third 4.5+, Available on 4.5 and later" class="beta" role="text" title="Available on 4.5 and later">Third 4.5+</li>
-        </ul>
-        """)
+        switch goal {
+        case .quality:
+            #expect(availability.rendered(prettyFormatted: true) == """
+            <ul id="availability">
+            <li aria-label="First 1.2–3.4, Introduced in First 1.2 and deprecated in First 3.4" class="deprecated" role="text" title="Introduced in First 1.2 and deprecated in First 3.4">First 1.2–3.4</li>
+            <li aria-label="Second 1.2.3+, Available on 1.2.3 and later" role="text" title="Available on 1.2.3 and later">Second 1.2.3+</li>
+            <li aria-label="Third 4.5+, Available on 4.5 and later" class="beta" role="text" title="Available on 4.5 and later">Third 4.5+</li>
+            </ul>
+            """)
+        case .conciseness:
+            #expect(availability.rendered(prettyFormatted: true) == """
+            <ul id="availability">
+            <li>First 1.2–3.4</li>
+            <li>Second 1.2.3+</li>
+            <li>Third 4.5+</li>
+            </ul>
+            """)
+        }
     }
     
-    @Test
-    func testRenderSingleLanguageParameters() {
-        let parameters = makeRenderer().parameters([
+    @Test(arguments: RenderGoal.allCases)
+    func testRenderSingleLanguageParameters(goal: RenderGoal) {
+        let parameters = makeRenderer(goal: goal).parameters([
             .swift: [
                 .init(name: "First", content: parseMarkup(string: "Some _formatted_ description with `code`")),
                 .init(name: "Second", content: parseMarkup(string: """
@@ -91,11 +116,21 @@ struct MarkdownRenderer_PageElementsTests {
                 """)),
             ]
         ])
+        let expectedHTMLStart = switch goal {
+        case .quality: """
+            <section id="parameters">
+            <h2>
+                <a href="#parameters">Parameters</a>
+            </h2>
+            """
+        case .conciseness: """
+            <section>
+            <h2>Parameters</h2>
+            """
+        }
+        
         #expect(parameters.rendered(prettyFormatted: true) == """
-        <section id="parameters">
-        <h2>
-            <a href="#parameters">Parameters</a>
-        </h2>
+        \(expectedHTMLStart)
         <dl>
             <dt>
                 <code>First</code>
@@ -121,7 +156,7 @@ struct MarkdownRenderer_PageElementsTests {
     
     @Test
     func testRenderLanguageSpecificParameters() {
-        let parameters = makeRenderer().parameters([
+        let parameters = makeRenderer(goal: .quality).parameters([
             .swift: [
                 .init(name: "FirstCommon", content: parseMarkup(string: "Available in both languages")),
                 .init(name: "SwiftOnly", content: parseMarkup(string: "Only available in Swift")),
@@ -170,7 +205,7 @@ struct MarkdownRenderer_PageElementsTests {
     
     @Test
     func testRenderManyLanguageSpecificParameters() {
-        let parameters = makeRenderer().parameters([
+        let parameters = makeRenderer(goal: .quality).parameters([
             .swift: [
                 .init(name: "First", content: parseMarkup(string: "Some description")),
             ],
@@ -214,15 +249,15 @@ struct MarkdownRenderer_PageElementsTests {
         """)
     }
     
-    @Test
-    func testRenderSwiftDeclaration() {
+    @Test(arguments: RenderGoal.allCases)
+    func testRenderSwiftDeclaration(goal: RenderGoal) {
         let symbolPaths = [
             "first-parameter-symbol-id":  URL(string: "/documentation/ModuleName/FirstParameterValue/index.html")!,
             "second-parameter-symbol-id": URL(string: "/documentation/ModuleName/SecondParameterValue/index.html")!,
             "return-value-symbol-id":     URL(string: "/documentation/ModuleName/ReturnValue/index.html")!,
         ]
         
-        let declaration = makeRenderer(pathsToReturn: symbolPaths).declaration([
+        let declaration = makeRenderer(goal: goal, pathsToReturn: symbolPaths).declaration([
             .swift:  [
                 .init(kind: .keyword,           spelling: "func",        preciseIdentifier: nil),
                 .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
@@ -245,26 +280,35 @@ struct MarkdownRenderer_PageElementsTests {
                 .init(kind: .typeIdentifier,    spelling: "ReturnValue", preciseIdentifier: "return-value-symbol-id"),
             ]
         ])
-        #expect(declaration.rendered(prettyFormatted: true) == """
-        <pre id="declaration">
-        <code>
-            <span class="token-keyword">func</span>
-             <span class="token-identifier">doSomething</span>
-            (<span class="token-externalParam">with</span>
-             <span class="token-internalParam">first</span>
-            : <a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
-            , <span class="token-externalParam">and</span>
-             <span class="token-internalParam">second</span>
-            : <a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
-            ) <span class="token-keyword">throws</span>
-            -&gt; <a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
-        </code>
-        </pre>
-        """)
+        switch goal {
+        case .quality:
+            #expect(declaration.rendered(prettyFormatted: true) == """
+            <pre id="declaration">
+            <code>
+                <span class="token-keyword">func</span>
+                 <span class="token-identifier">doSomething</span>
+                (<span class="token-externalParam">with</span>
+                 <span class="token-internalParam">first</span>
+                : <a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
+                , <span class="token-externalParam">and</span>
+                 <span class="token-internalParam">second</span>
+                : <a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
+                ) <span class="token-keyword">throws</span>
+                -&gt; <a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
+            </code>
+            </pre>
+            """)
+        case .conciseness:
+            #expect(declaration.rendered(prettyFormatted: true) == """
+            <pre id="declaration">
+            <code>func doSomething(with first: FirstParameterValue, and second: SecondParameterValue) throws-&gt; ReturnValue</code>
+            </pre>
+            """)
+        }
     }
     
-    @Test
-    func testRenderLanguageSpecificDeclarations() {
+    @Test(arguments: RenderGoal.allCases)
+    func testRenderLanguageSpecificDeclarations(goal: RenderGoal) {
         let symbolPaths = [
             "first-parameter-symbol-id":  URL(string: "/documentation/ModuleName/FirstParameterValue/index.html")!,
             "second-parameter-symbol-id": URL(string: "/documentation/ModuleName/SecondParameterValue/index.html")!,
@@ -272,7 +316,7 @@ struct MarkdownRenderer_PageElementsTests {
             "error-parameter-symbol-id":  URL(string: "/documentation/Foundation/NSError/index.html")!,
         ]
         
-        let declaration = makeRenderer(pathsToReturn: symbolPaths).declaration([
+        let declaration = makeRenderer(goal: goal, pathsToReturn: symbolPaths).declaration([
             .swift:  [
                 .init(kind: .keyword,           spelling: "func",        preciseIdentifier: nil),
                 .init(kind: .text,              spelling: " ",           preciseIdentifier: nil),
@@ -319,38 +363,49 @@ struct MarkdownRenderer_PageElementsTests {
                 .init(kind: .text,              spelling: ";",           preciseIdentifier: nil),
             ]
         ])
-        #expect(declaration.rendered(prettyFormatted: true) == """
-        <pre id="declaration">
-        <code class="swift-only">
-            <span class="token-keyword">func</span>
-             <span class="token-identifier">doSomething</span>
-            (<span class="token-externalParam">with</span>
-             <span class="token-internalParam">first</span>
-            : <a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
-            , <span class="token-externalParam">and</span>
-             <span class="token-internalParam">second</span>
-            : <a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
-            ) <span class="token-keyword">throws</span>
-            -&gt; <a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
-        </code>
-        <code class="occ-only">- (<a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
-            ) <span class="token-identifier">doSomethingWithFirst</span>
-            : (<a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
-            ) <span class="token-internalParam">first</span>
-             <span class="token-identifier">andSecond</span>
-            : (<a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
-            ) <span class="token-internalParam">second</span>
-             <span class="token-identifier">error</span>
-            : (<a class="token-typeIdentifier" href="../../../../Foundation/NSError/index.html">NSError</a>
-             **) <span class="token-internalParam">error</span>
-            ;</code>
-        </pre>
-        """)
+        switch goal {
+        case .quality:
+            #expect(declaration.rendered(prettyFormatted: true) == """
+            <pre id="declaration">
+            <code class="swift-only">
+                <span class="token-keyword">func</span>
+                 <span class="token-identifier">doSomething</span>
+                (<span class="token-externalParam">with</span>
+                 <span class="token-internalParam">first</span>
+                : <a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
+                , <span class="token-externalParam">and</span>
+                 <span class="token-internalParam">second</span>
+                : <a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
+                ) <span class="token-keyword">throws</span>
+                -&gt; <a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
+            </code>
+            <code class="occ-only">- (<a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
+                ) <span class="token-identifier">doSomethingWithFirst</span>
+                : (<a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
+                ) <span class="token-internalParam">first</span>
+                 <span class="token-identifier">andSecond</span>
+                : (<a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
+                ) <span class="token-internalParam">second</span>
+                 <span class="token-identifier">error</span>
+                : (<a class="token-typeIdentifier" href="../../../../Foundation/NSError/index.html">NSError</a>
+                 **) <span class="token-internalParam">error</span>
+                ;</code>
+            </pre>
+            """)
+            
+        case .conciseness:
+            #expect(declaration.rendered(prettyFormatted: true) == """
+            <pre id="declaration">
+            <code>func doSomething(with first: FirstParameterValue, and second: SecondParameterValue) throws-&gt; ReturnValue</code>
+            </pre>
+            """)
+        }
     }
     
     // MARK: -
     
     private func makeRenderer(
+        goal: RenderGoal,
         elementsToReturn: [LinkedElement] = [],
         pathsToReturn: [String: URL] = [:],
         assetsToReturn: [String: LinkedAsset] = [:],
@@ -373,15 +428,12 @@ struct MarkdownRenderer_PageElementsTests {
             elementsByURL[element.path] = element
         }
         
-        return MarkdownRenderer(
-            path: path,
-            linkProvider: MultiValueLinkProvider(
-                elementsToReturn: elementsByURL,
-                pathsToReturn: pathsToReturn,
-                assetsToReturn: assetsToReturn,
-                fallbackLinkTextsToReturn: fallbackLinkTextsToReturn
-            )
-        )
+        return MarkdownRenderer(path: path, goal: goal, linkProvider: MultiValueLinkProvider(
+            elementsToReturn: elementsByURL,
+            pathsToReturn: pathsToReturn,
+            assetsToReturn: assetsToReturn,
+            fallbackLinkTextsToReturn: fallbackLinkTextsToReturn
+        ))
     }
     
     private func parseMarkup(string: String) -> [any Markup] {
@@ -411,3 +463,9 @@ struct MultiValueLinkProvider: LinkProvider {
         fallbackLinkTextsToReturn[linkString] ?? linkString
     }
 }
+
+extension RenderGoal: CaseIterable {
+    package static var allCases: [RenderGoal] {
+        [.quality, .conciseness]
+    }
+}
diff --git a/Tests/DocCHTMLTests/MarkdownRendererTests.swift b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
index f96916bb82..eb2e74e134 100644
--- a/Tests/DocCHTMLTests/MarkdownRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
@@ -542,6 +542,7 @@ struct MarkdownRendererTests {
     ) {
         let renderer = MarkdownRenderer(
             path: URL(string: "/documentation/Something/ThisPage/index.html")!,
+            goal: .quality,
             linkProvider: SingleValueLinkProvider(
                 elementToReturn: elementToReturn,
                 assetToReturn: assetToReturn,

From e3131c1380717a4556b5083ddf12c9b95d55fbd3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 26 Nov 2025 17:07:03 +0100
Subject: [PATCH 35/68] Remove duplicate declaration in HTML output

---
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 34 +------------------
 .../FileWritingHTMLContentConsumerTests.swift |  8 -----
 2 files changed, 1 insertion(+), 41 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index c8a07f22c5..a6fb84c69c 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -387,38 +387,6 @@ struct HTMLRenderer {
             hero.addChild( renderer.declaration(fragmentsByLanguageID) )
         }
         
-        for (trait, variant) in symbol.declarationVariants.allValues.sorted(by: { $0.trait < $1.trait}) {
-            guard let lang = trait.interfaceLanguage else { continue }
-            
-            for (/*platforms*/_, declaration) in variant {
-                // FIXME: Pretty print declarations for Swift and Objective-C
-                
-                hero.addChild(
-                    .element(named: "pre", children: [
-                        .element(named: "code", children: declaration.declarationFragments.map { fragment in
-                            // ???: Do `.text` tokens need to be wrapped in a span?
-                            if fragment.kind == .typeIdentifier,
-                               let symbolID = fragment.preciseIdentifier,
-                               let reference = context.localOrExternalReference(symbolID: symbolID)
-                            {
-                                // Make a link
-                                return .element(named: "span", children: [
-                                    .element(
-                                        named: "a",
-                                        children: [.text(fragment.spelling)],
-                                        attributes: ["href": path(to: reference)]
-                                    )
-                                ], attributes: ["class": "type-identifier-link"])
-                            }
-                            else {
-                                return .element(named: "span", children: [.text(fragment.spelling)], attributes: ["class": "token-\(fragment.kind.rawValue)"])
-                            }
-                        })
-                    ], attributes: ["class": "\(lang)-only"])
-                )
-            }
-        }
-        
         // Deprecation message
         if let deprecationSummary = symbol.deprecatedSummary {
             var children: [XMLNode] = [
@@ -458,7 +426,7 @@ struct HTMLRenderer {
         if let returnsSection = symbol.returnsSection {
             let section = XMLElement(name: "section")
             section.addAttribute(
-                XMLNode.attribute(withName: "class", stringValue: "return-value") as! XMLNode
+                XMLNode.attribute(withName: "id", stringValue: "return-value") as! XMLNode
             )
             
             if let title = ReturnsSection.title {
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index bfde5b779f..d8138dd36a 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -153,7 +153,6 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </html>
         """)
         
-        // FIXME: This output contains some unexpected duplication for the declaration.
         XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/ModuleName/SomeClass/index.html")), encoding: .utf8)), """
         <html>
           <head>
@@ -185,13 +184,6 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                          <span class="token-identifier">SomeClass</span>
                     </code>
                 </pre>
-                <pre class="swift-only">
-                    <code>
-                        <span class="token-keyword">class</span>
-                        <span class="token-text"> </span>
-                        <span class="token-identifier">SomeClass</span>
-                    </code>
-                </pre>
             </section>
         </article>
         </main></noscript>

From 81ae2ccd4a7dcad85a5172dbf3313fc7a8d90272 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 26 Nov 2025 18:29:12 +0100
Subject: [PATCH 36/68] Add test for rendering return sections declarations

---
 .../DocCHTML/MarkupRenderer+Parameters.swift  | 32 ++-----
 Sources/DocCHTML/MarkupRenderer+Returns.swift | 96 +++++++++++++++++++
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 13 +++
 .../MarkdownRenderer+PageElementsTests.swift  | 54 +++++++++++
 4 files changed, 172 insertions(+), 23 deletions(-)
 create mode 100644 Sources/DocCHTML/MarkupRenderer+Returns.swift

diff --git a/Sources/DocCHTML/MarkupRenderer+Parameters.swift b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
index 5197b7f0cc..c7309e6a3f 100644
--- a/Sources/DocCHTML/MarkupRenderer+Parameters.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
@@ -28,42 +28,28 @@ package extension MarkdownRenderer {
         }
     }
     
-    func parameters(_ info: [SourceLanguage: [ParameterInfo]]) -> XMLNode {
+    func parameters(_ info: [SourceLanguage: [ParameterInfo]]) -> XMLElement {
         let info = RenderHelpers.sortedLanguageSpecificValues(info)
-        
-        // Add a heading that references the section before anything the actual parameter list
-        let header = switch goal {
-        case .quality:
-            XMLNode.element(named: "a", children: [.text("Parameters")], attributes: ["href": "#parameters"])
-        case .conciseness:
-            XMLNode.text("Parameters")
-        }
-        var items: [XMLElement] = [
-            .element(named: "h2", children: [header])
-        ]
-        
-        switch info.count {
+        let items: [XMLElement] = switch info.count {
         case 1:
-            items.append(
-                _singleLanguageParameters(info.first!.value) // Verified to exist above
-            )
+            [_singleLanguageParameters(info.first!.value)] // Verified to exist above
+            
         case 2:
-            items.append(
-                _dualLanguageParameters(primary: info.first!, secondary: info.last!) // Both verified to exist above
-            )
+            [_dualLanguageParameters(primary: info.first!, secondary: info.last!)] // Both verified to exist above
+            
         default:
             // In practice DocC only encounters one or two different languages. If there would be a third one,
             // produce correct looking pages that may include duplicated markup by not trying to share parameters across languages.
-            items.append(contentsOf: info.map { language, info in
+            info.map { language, info in
                 .element(
                     named: "dl",
                     children: _singleLanguageParameterItems(info),
                     attributes: ["class": "\(language.id)-only"]
                 )
-            })
+            }
         }
         
-        return .element(named: "section", children: items, attributes: goal == .quality ? ["id": "parameters"] : [:])
+        return selfReferencingSection(named: "Parameters", content: items)
     }
     
     private func _singleLanguageParameters(_ parameterInfo: [ParameterInfo]) -> XMLElement {
diff --git a/Sources/DocCHTML/MarkupRenderer+Returns.swift b/Sources/DocCHTML/MarkupRenderer+Returns.swift
new file mode 100644
index 0000000000..be6b16f101
--- /dev/null
+++ b/Sources/DocCHTML/MarkupRenderer+Returns.swift
@@ -0,0 +1,96 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+package import Foundation
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+package import FoundationXML
+#endif
+
+package import Markdown
+package import DocCCommon
+
+package extension MarkdownRenderer {
+    func returns(_ languageSpecificSections: [SourceLanguage: [any Markup]]) -> XMLElement {
+        let info = RenderHelpers.sortedLanguageSpecificValues(languageSpecificSections)
+        let items: [XMLNode] = if info.count == 1 {
+            info.first!.value.map { visit($0) } // Verified to exist above
+        } else {
+            info.flatMap { language, content in
+                let attributes = ["class": "\(language.id)-only"]
+                // Most return sections only have 1 paragraph of content with 2 and 3 paragraphs being increasingly uncommon.
+                // Avoid wrapping that content in a div and instead add the language specific class attribute to each paragraph.
+                return content.map { markup in
+                    let node = visit(markup)
+                    if let element = node as? XMLElement {
+                        element.addAttributes(attributes)
+                        return element
+                    } else {
+                        // Any text _should_ already be contained in a markdown paragraph, but if the input is unexpected, wrap it here.
+                        return .element(named: "p", children: [node], attributes: attributes)
+                    }
+                }
+            }
+        }
+        
+        return selfReferencingSection(named: "Return Value", content: items)
+    }
+    
+    func selfReferencingSection(named sectionName: String, content: [XMLNode]) -> XMLElement {
+        let headingContent: XMLNode
+        let sectionAttributes: [String: String]
+        
+        switch goal {
+        case .quality:
+            let id = urlReadableFragment(sectionName.lowercased())
+            headingContent = .element(named: "a", children: [.text(sectionName)], attributes: ["href": "#\(id)"])
+            sectionAttributes = ["id": id]
+        case .conciseness:
+            headingContent = .text(sectionName)
+            sectionAttributes = [:]
+        }
+        
+        return .element(
+            named: "section",
+            children: [.element(named: "h2", children: [headingContent])] + content,
+            attributes: sectionAttributes
+        )
+    }
+}
+
+private extension CharacterSet {
+    // For fragments
+    static let fragmentCharactersToRemove = CharacterSet.punctuationCharacters // Remove punctuation from fragments
+        .union(CharacterSet(charactersIn: "`"))       // Also consider back-ticks as punctuation. They are used as quotes around symbols or other code.
+        .subtracting(CharacterSet(charactersIn: "-")) // Don't remove hyphens. They are used as a whitespace replacement.
+    static let whitespaceAndDashes = CharacterSet.whitespaces
+        .union(CharacterSet(charactersIn: "-–—")) // hyphen, en dash, em dash
+}
+
+/// Creates a more readable version of a fragment by replacing characters that are not allowed in the fragment of a URL with hyphens.
+///
+/// If this step is not performed, the disallowed characters are instead percent escape encoded, which is less readable.
+/// For example, a fragment like `"#hello world"` is converted to `"#hello-world"` instead of `"#hello%20world"`.
+private func urlReadableFragment(_ fragment: some StringProtocol) -> String {
+    var fragment = fragment
+        // Trim leading/trailing whitespace
+        .trimmingCharacters(in: .whitespaces)
+    
+        // Replace continuous whitespace and dashes
+        .components(separatedBy: .whitespaceAndDashes)
+        .filter({ !$0.isEmpty })
+        .joined(separator: "-")
+    
+    // Remove invalid characters
+    fragment.unicodeScalars.removeAll(where: CharacterSet.fragmentCharactersToRemove.contains)
+    
+    return fragment
+}
+
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index a6fb84c69c..fe6145e4be 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -423,6 +423,19 @@ struct HTMLRenderer {
         }
         
         // Return value
+        if !symbol.returnsSectionVariants.allValues.isEmpty {
+            articleElement.addChild(
+                renderer.returns(
+                    .init(
+                        symbol.returnsSectionVariants.allValues.map { trait, returnSection in (
+                            key:   trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift,
+                            value: returnSection.content
+                        )},
+                        uniquingKeysWith: { _, new in new }
+                    )
+                )
+            )
+        }
         if let returnsSection = symbol.returnsSection {
             let section = XMLElement(name: "section")
             section.addAttribute(
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index f0cc18190d..ab46b1fff7 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -307,6 +307,60 @@ struct MarkdownRenderer_PageElementsTests {
         }
     }
     
+    @Test(arguments: RenderGoal.allCases)
+    func testRenderSingleLanguageReturnSections(goal: RenderGoal) {
+        let parameters = makeRenderer(goal: goal).returns([
+            .swift: parseMarkup(string: "First paragraph\n\nSecond paragraph")
+        ])
+        let expectedHTMLStart = switch goal {
+        case .quality: """
+            <section id="return-value">
+            <h2>
+                <a href="#return-value">Return Value</a>
+            </h2>
+            """
+        case .conciseness: """
+            <section>
+            <h2>Return Value</h2>
+            """
+        }
+        
+        #expect(parameters.rendered(prettyFormatted: true) == """
+        \(expectedHTMLStart)
+        <p>First paragraph</p>
+        <p>Second paragraph</p>
+        </section>
+        """)
+    }
+    
+    @Test(arguments: RenderGoal.allCases)
+    func testRenderLanguageSpecificReturnSections(goal: RenderGoal) {
+        let parameters = makeRenderer(goal: goal).returns([
+            .swift:      parseMarkup(string: "First paragraph\n\nSecond paragraph"),
+            .objectiveC: parseMarkup(string: "Other language's paragraph"),
+        ])
+        let expectedHTMLStart = switch goal {
+        case .quality: """
+            <section id="return-value">
+            <h2>
+                <a href="#return-value">Return Value</a>
+            </h2>
+            """
+        case .conciseness: """
+            <section>
+            <h2>Return Value</h2>
+            """
+        }
+        
+        #expect(parameters.rendered(prettyFormatted: true) == """
+        \(expectedHTMLStart)
+        <p class="swift-only">First paragraph</p>
+        <p class="swift-only">Second paragraph</p>
+        <p class="occ-only">Other language’s paragraph</p>
+        </section>
+        """)
+    }
+    
     @Test(arguments: RenderGoal.allCases)
     func testRenderLanguageSpecificDeclarations(goal: RenderGoal) {
         let symbolPaths = [

From af95717552eccc7c744466e0330a6e6c8164f97b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 26 Nov 2025 18:37:41 +0100
Subject: [PATCH 37/68] Add an article and a method to the full HTML content
 consumer test

---
 .../Model/Rendering/HTML/HTMLRenderer.swift   |  20 --
 .../FileWritingHTMLContentConsumerTests.swift | 215 +++++++++++++++++-
 2 files changed, 207 insertions(+), 28 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index fe6145e4be..17195eca31 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -436,26 +436,6 @@ struct HTMLRenderer {
                 )
             )
         }
-        if let returnsSection = symbol.returnsSection {
-            let section = XMLElement(name: "section")
-            section.addAttribute(
-                XMLNode.attribute(withName: "id", stringValue: "return-value") as! XMLNode
-            )
-            
-            if let title = ReturnsSection.title {
-                section.addChild(
-                    .selfReferencingHeader(title: title)
-                )
-            }
-            
-            for markup in returnsSection.content {
-                section.addChild(
-                    renderer.visit(markup)
-                )
-            }
-            
-            articleElement.addChild(section)
-        }
         
         // Discussion
         if let discussion = symbol.discussion {
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index d8138dd36a..c74431e842 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -19,17 +19,74 @@ import SwiftDocCTestUtilities
 final class FileWritingHTMLContentConsumerTests: XCTestCase {
     
     func testWritesContentInsideHTMLTemplate() async throws {
-        let catalog = Folder(name: "unit-test.docc", content: [
+        let catalog = Folder(name: "ModuleName.docc", content: [
+            TextFile(name: "SomeArticle.md", utf8Content: """
+            # Some article
+            
+            This is an article.
+            
+            It explains how a developer can perform some task using this module.
+            """),
+            
             JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(moduleName: "ModuleName", symbols: [
-                makeSymbol(id: "some-symbol-id", kind: .class, pathComponents: ["SomeClass"], docComment: """
-                Some in-source description of this class
+                makeSymbol(id: "some-class-id", kind: .class, pathComponents: ["SomeClass"], docComment: """
+                Some in-source description of this class.
                 """, otherMixins: [
-                    SymbolGraph.Symbol.DeclarationFragments.init(declarationFragments: [
+                    SymbolGraph.Symbol.DeclarationFragments(declarationFragments: [
                         .init(kind: .keyword,    spelling: "class",     preciseIdentifier: nil),
                         .init(kind: .text,       spelling: " ",         preciseIdentifier: nil),
                         .init(kind: .identifier, spelling: "SomeClass", preciseIdentifier: nil),
                     ])
+                ]),
+                makeSymbol(id: "some-method-id", kind: .method, pathComponents: ["SomeClass", "someMethod(with:and:)"], docComment: """
+                Some in-source description of this method.
+                
+                Further description of this method and how to use it.
+                
+                - Parameters: 
+                  - first:  Description of the `first` parameter.
+                  - second: Description of the `second` parameter.
+                - Returns:  Description of the return value.
+                """, otherMixins: [
+                    SymbolGraph.Symbol.DeclarationFragments(declarationFragments: [
+                        .init(kind: .keyword,           spelling: "func",       preciseIdentifier: nil),
+                        .init(kind: .text,              spelling: " ",          preciseIdentifier: nil),
+                        .init(kind: .identifier,        spelling: "someMethod", preciseIdentifier: nil),
+                        .init(kind: .text,              spelling: "(",          preciseIdentifier: nil),
+                        .init(kind: .externalParameter, spelling: "with",       preciseIdentifier: nil),
+                        .init(kind: .text,              spelling: " ",          preciseIdentifier: nil),
+                        .init(kind: .internalParameter, spelling: "first",      preciseIdentifier: nil),
+                        .init(kind: .text,              spelling: ": ",         preciseIdentifier: nil),
+                        .init(kind: .typeIdentifier,    spelling: "Int",        preciseIdentifier: "s:Si"),
+                        .init(kind: .text,              spelling: ", ",         preciseIdentifier: nil),
+                        .init(kind: .externalParameter, spelling: "and",        preciseIdentifier: nil),
+                        .init(kind: .text,              spelling: " ",          preciseIdentifier: nil),
+                        .init(kind: .internalParameter, spelling: "second",     preciseIdentifier: nil),
+                        .init(kind: .text,              spelling: ": ",         preciseIdentifier: nil),
+                        .init(kind: .typeIdentifier,    spelling: "String",     preciseIdentifier: "s:SS"),
+                        .init(kind: .text,              spelling: ") -> ",      preciseIdentifier: nil),
+                        .init(kind: .typeIdentifier,    spelling: "Bool",       preciseIdentifier: "s:Sb"),
+                    ]),
+                    SymbolGraph.Symbol.FunctionSignature(
+                        parameters: [
+                            .init(name: "first", externalName: "with", declarationFragments: [
+                                .init(kind: .identifier,     spelling: "first",  preciseIdentifier: nil),
+                                .init(kind: .text,           spelling: ": ",     preciseIdentifier: nil),
+                                .init(kind: .typeIdentifier, spelling: "Int",    preciseIdentifier: "s:Si"),
+                            ], children: []),
+                            .init(name: "second", externalName: "and", declarationFragments: [
+                                .init(kind: .identifier,     spelling: "first",  preciseIdentifier: nil),
+                                .init(kind: .text,           spelling: ": ",     preciseIdentifier: nil),
+                                .init(kind: .typeIdentifier, spelling: "String", preciseIdentifier: "s:Ss"),
+                            ], children: [])
+                        ],
+                        returns: [
+                            .init(kind: .typeIdentifier,     spelling: "Bool",    preciseIdentifier: "s:Sb"),
+                        ]
+                    )
                 ])
+            ], relationships: [
+                .init(source: "some-method-id", target: "some-class-id", kind: .memberOf, targetFallback: nil)
             ])),
             
             TextFile(name: "ModuleName.md", utf8Content: """
@@ -90,12 +147,16 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         )
         
         // Because the TestOutputConsumer below, doesn't create any files, we only expect the HTML files in the output directory
-        XCTAssertEqual(fileSystem.dump(subHierarchyFrom: "/output"), """
+        XCTAssertEqual(fileSystem.dump(subHierarchyFrom: "/output-dir"), """
         output-dir/
         ╰─ documentation/
            ╰─ ModuleName/
-              ├─ SomeClass/
+              ├─ SomeArticle/
               │  ╰─ index.html
+              ├─ SomeClass/
+              │  ├─ index.html
+              │  ╰─ someMethod(with:and:)/
+              │     ╰─ index.html
               ╰─ index.html
         """)
         
@@ -143,7 +204,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                                 Class</span>
                         </code>
                     </a>
-                    <p>Some in-source description of this class</p>
+                    <p>Some in-source description of this class.</p>
                 </div>
             </section>
         </article>
@@ -177,7 +238,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 </header>
                 <h1>Some<wbr/>
                     Class</h1>
-                <p id="abstract">Some in-source description of this class</p>
+                <p id="abstract">Some in-source description of this class.</p>
                 <pre id="declaration">
                     <code>
                         <span class="token-keyword">class</span>
@@ -185,6 +246,144 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     </code>
                 </pre>
             </section>
+            <section>
+                <h2 id="Topics">
+                    <a href="#Topics">Topics</a>
+                </h2>
+                <h3 id="Instance-Methods">
+                    <a href="#Instance-Methods">Instance Methods</a>
+                </h3>
+                <div class="link-block">
+                    <a href="someMethod(with:and:)/index.html">
+                        <code class="swift-only">
+                            <span class="identifier">some<wbr/>
+                                Method(<wbr/>
+                                with:<wbr/>
+                                and:)</span>
+                        </code>
+                    </a>
+                    <p>Some in-source description of this method.</p>
+                </div>
+            </section>
+        </article>
+        </main></noscript>
+            <div id="app"></div>
+          </body>
+        </html>
+        """)
+        
+        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/ModuleName/SomeClass/someMethod(with:and:)/index.html")), encoding: .utf8)), """
+        <html>
+          <head>
+            <meta charset="utf-8" />
+            <link rel="icon" href="/favicon.ico" />
+            <title>someMethod(with:and:)</title>
+            <script>var baseUrl = "/"</script>
+          </head>
+          <body>
+            <noscript><main>
+        <article>
+            <section class="separated">
+                <header>
+                    <nav id="breadcrumbs">
+                        <ul>
+                            <li>
+                                <span class="swift-only">someMethod(with:and:)</span>
+                            </li>
+                        </ul>
+                    </nav>
+                    <span class="eyebrow">Instance Method</span>
+                </header>
+                <h1>some<wbr/>
+                    Method(<wbr/>
+                    with:<wbr/>
+                    and:)</h1>
+                <p id="abstract">Some in-source description of this method.</p>
+                <pre id="declaration">
+                    <code>
+                        <span class="token-keyword">func</span>
+                         <span class="token-identifier">someMethod</span>
+                        (<span class="token-externalParam">with</span>
+                         <span class="token-internalParam">first</span>
+                        : <span class="token-typeIdentifier">Int</span>
+                        , <span class="token-externalParam">and</span>
+                         <span class="token-internalParam">second</span>
+                        : <span class="token-typeIdentifier">String</span>
+                        ) -&gt; <span class="token-typeIdentifier">Bool</span>
+                    </code>
+                </pre>
+            </section>
+            <section id="parameters">
+                <h2>
+                    <a href="#parameters">Parameters</a>
+                </h2>
+                <dl>
+                    <dt>
+                        <code>first</code>
+                    </dt>
+                    <dd>
+                        <p>Description of the <code>first</code>
+                             parameter.</p>
+                    </dd>
+                    <dt>
+                        <code>second</code>
+                    </dt>
+                    <dd>
+                        <p>Description of the <code>second</code>
+                             parameter.</p>
+                    </dd>
+                </dl>
+            </section>
+            <section id="return-value">
+                <h2>
+                    <a href="#return-value">Return Value</a>
+                </h2>
+                <p>Description of the return value.</p>
+            </section>
+            <section>
+                <h2 id="Discussion">
+                    <a href="#Discussion">Discussion</a>
+                </h2>
+                <p>Further description of this method and how to use it.</p>
+            </section>
+        </article>
+        </main></noscript>
+            <div id="app"></div>
+          </body>
+        </html>
+        """)
+        
+        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/ModuleName/SomeArticle/index.html")), encoding: .utf8)), """
+        <html>
+          <head>
+            <meta charset="utf-8" />
+            <link rel="icon" href="/favicon.ico" />
+            <title>Some article</title>
+            <script>var baseUrl = "/"</script>
+          </head>
+          <body>
+            <noscript><main>
+        <article>
+            <div id="hero-article">
+                <section>
+                    <header>
+                        <nav id="breadcrumbs">
+                            <ul>
+                                <li>Some article</li>
+                            </ul>
+                        </nav>
+                        <span class="eyebrow">Article</span>
+                    </header>
+                    <h1>Some article</h1>
+                    <p id="abstract">This is an article.</p>
+                </section>
+            </div>
+            <section>
+                <h2 id="Overview">
+                    <a href="#Overview">Overview</a>
+                </h2>
+                <p>It explains how a developer can perform some task using this module.</p>
+            </section>
         </article>
         </main></noscript>
             <div id="app"></div>

From f7303da368445e3c790c689af9b1b85db169c28c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 26 Nov 2025 18:48:40 +0100
Subject: [PATCH 38/68] Omit language class from single-language breadcrumbs

---
 Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift    | 12 ++++++++----
 .../FileWritingHTMLContentConsumerTests.swift        | 12 +++---------
 2 files changed, 11 insertions(+), 13 deletions(-)

diff --git a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
index b350065df4..4141be0441 100644
--- a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
@@ -28,10 +28,14 @@ package extension MarkdownRenderer {
                 let names = RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID)
                 return switch goal {
                 case .quality:
-                    names.map { language, name in
-                        .element(named: "span", children: [
-                            .text(name) // Breadcrumbs display symbol names in a default style (no "code voice")
-                        ], attributes: ["class": "\(language.id)-only"])
+                    if names.count == 1 {
+                        [.text(names.first!.value)]
+                    } else {
+                        names.map { language, name in
+                                .element(named: "span", children: [
+                                    .text(name) // Breadcrumbs display symbol names in a default style (no "code voice")
+                                ], attributes: ["class": "\(language.id)-only"])
+                        }
                     }
                 case .conciseness:
                     // If the goal is conciseness, only display the primary language's name
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index c74431e842..d0da8f56b2 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -177,9 +177,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     <header>
                         <nav id="breadcrumbs">
                             <ul>
-                                <li>
-                                    <span class="swift-only">ModuleName</span>
-                                </li>
+                                <li>ModuleName</li>
                             </ul>
                         </nav>
                         <span class="eyebrow">Framework</span>
@@ -229,9 +227,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 <header>
                     <nav id="breadcrumbs">
                         <ul>
-                            <li>
-                                <span class="swift-only">SomeClass</span>
-                            </li>
+                            <li>SomeClass</li>
                         </ul>
                     </nav>
                     <span class="eyebrow">Class</span>
@@ -287,9 +283,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 <header>
                     <nav id="breadcrumbs">
                         <ul>
-                            <li>
-                                <span class="swift-only">someMethod(with:and:)</span>
-                            </li>
+                            <li>someMethod(with:and:)</li>
                         </ul>
                     </nav>
                     <span class="eyebrow">Instance Method</span>

From 8d280718948ccbdcb66c31580cf0deb87ad23cb6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 26 Nov 2025 18:56:10 +0100
Subject: [PATCH 39/68] Fix missing symbol breadcrumbs to container pages

---
 .../Model/Rendering/HTML/HTMLRenderer.swift          |  4 ++--
 .../FileWritingHTMLContentConsumerTests.swift        | 12 ++++++++++++
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 17195eca31..98dbcd4390 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -194,7 +194,7 @@ struct HTMLRenderer {
         hero.addChild(
             .element(named: "header", children: [
                 renderer.breadcrumbs(
-                    references: (context.shortestFinitePath(to: reference) ?? [context.soleRootModuleReference!]).map { ContextLinkProvider.filePath(for: $0) },
+                    references: (context.shortestFinitePath(to: reference) ?? [context.soleRootModuleReference!]).map { $0.url },
                     currentPageNames: .single(.conceptual(node.name.plainText))
                 ),
                 
@@ -307,7 +307,7 @@ struct HTMLRenderer {
         hero.addChild(
             .element(named: "header", children: [
                 renderer.breadcrumbs(
-                    references: (context.linkResolver.localResolver.breadcrumbs(of: reference, in: reference.sourceLanguage) ?? []).map { ContextLinkProvider.filePath(for: $0) },
+                    references: (context.linkResolver.localResolver.breadcrumbs(of: reference, in: reference.sourceLanguage) ?? []).map { $0.url },
                     currentPageNames: names
                 ),
                 
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index d0da8f56b2..ae9208ae12 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -227,6 +227,9 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 <header>
                     <nav id="breadcrumbs">
                         <ul>
+                            <li>
+                                <a href="../../index.html">ModuleName</a>
+                            </li>
                             <li>SomeClass</li>
                         </ul>
                     </nav>
@@ -283,6 +286,12 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 <header>
                     <nav id="breadcrumbs">
                         <ul>
+                            <li>
+                                <a href="../../../index.html">ModuleName</a>
+                            </li>
+                            <li>
+                                <a href="../../index.html">SomeClass</a>
+                            </li>
                             <li>someMethod(with:and:)</li>
                         </ul>
                     </nav>
@@ -363,6 +372,9 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     <header>
                         <nav id="breadcrumbs">
                             <ul>
+                                <li>
+                                    <a href="../../index.html">ModuleName</a>
+                                </li>
                                 <li>Some article</li>
                             </ul>
                         </nav>

From c6db56d7c3f4536665773e7b1c7e2d0eb3097591 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 15:03:03 +0100
Subject: [PATCH 40/68] Add test for rendering Topics sections

---
 Sources/DocCHTML/MarkupRenderer+Returns.swift |   2 +-
 Sources/DocCHTML/MarkupRenderer+Topics.swift  | 162 ++++++++++++++++++
 .../Model/Rendering/HTML/HTMLRenderer.swift   |  63 ++++---
 .../SymbolGraphCreation.swift                 |  21 ++-
 .../MarkdownRenderer+PageElementsTests.swift  | 132 ++++++++++++++
 .../FileWritingHTMLContentConsumerTests.swift |  70 ++++----
 6 files changed, 378 insertions(+), 72 deletions(-)
 create mode 100644 Sources/DocCHTML/MarkupRenderer+Topics.swift

diff --git a/Sources/DocCHTML/MarkupRenderer+Returns.swift b/Sources/DocCHTML/MarkupRenderer+Returns.swift
index be6b16f101..68937231e6 100644
--- a/Sources/DocCHTML/MarkupRenderer+Returns.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Returns.swift
@@ -78,7 +78,7 @@ private extension CharacterSet {
 ///
 /// If this step is not performed, the disallowed characters are instead percent escape encoded, which is less readable.
 /// For example, a fragment like `"#hello world"` is converted to `"#hello-world"` instead of `"#hello%20world"`.
-private func urlReadableFragment(_ fragment: some StringProtocol) -> String {
+func urlReadableFragment(_ fragment: some StringProtocol) -> String {
     var fragment = fragment
         // Trim leading/trailing whitespace
         .trimmingCharacters(in: .whitespaces)
diff --git a/Sources/DocCHTML/MarkupRenderer+Topics.swift b/Sources/DocCHTML/MarkupRenderer+Topics.swift
new file mode 100644
index 0000000000..504878e8c7
--- /dev/null
+++ b/Sources/DocCHTML/MarkupRenderer+Topics.swift
@@ -0,0 +1,162 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+package import Foundation
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+package import FoundationXML
+#endif
+
+package import Markdown
+package import DocCCommon
+
+package extension MarkdownRenderer {
+    struct TaskGroupInfo {
+        package var title: String?
+        package var content: [any Markup]
+        package var references: [URL]
+        
+        package init(title: String?, content: [any Markup], references: [URL]) {
+            self.title = title
+            self.content = content
+            self.references = references
+        }
+    }
+    
+    func topicsSection(_ taskGroups: [SourceLanguage: [TaskGroupInfo]]) -> XMLElement {
+        let taskGroups = RenderHelpers.sortedLanguageSpecificValues(taskGroups)
+        
+        let items: [XMLElement] = if taskGroups.count == 1 {
+            taskGroups.first!.value.flatMap { taskGroup in
+                _singleTaskGroupElements(for: taskGroup)
+            }
+        } else {
+            // TODO: As a future improvement we could diff the links and only mark add "class" attributes to the unique ones
+            taskGroups.flatMap { language, taskGroups in
+                let attribute = XMLNode.attribute(withName: "class", stringValue: "\(language.id)-only") as! XMLNode
+                
+                let elements = taskGroups.flatMap { _singleTaskGroupElements(for: $0) }
+                for element in elements {
+                    element.addAttribute(attribute)
+                }
+                return elements
+            }
+        }
+        
+        return selfReferencingSection(named: "Topics", content: items)
+    }
+    
+    private func _singleTaskGroupElements(for taskGroup: TaskGroupInfo) -> [XMLElement] {
+        let listItems = taskGroup.references.compactMap { reference in
+            linkProvider.element(for: reference).map { _taskGroupItem(for: $0) }
+        }
+        // Don't return a title and abstract/discussion if this group has no links
+        guard !listItems.isEmpty else { return [] }
+        
+        var items: [XMLElement] = []
+        // Title
+        if let title = taskGroup.title {
+            switch goal {
+            case .quality:
+                items.append(.selfReferencingHeader(level: 3, title: title))
+            case .conciseness:
+                items.append(.element(named: "h3", children: [.text(title)]))
+            }
+        }
+        // Abstract/Discussion
+        for markup in taskGroup.content {
+            let rendered = visit(markup)
+            if let element = rendered as? XMLElement {
+                items.append(element)
+            } else {
+                // Wrap any inline content in an element. This is not expected to happen in practice
+                items.append(.element(named: "p", children: [rendered]))
+            }
+        }
+        // Links
+        items.append(.element(named: "ul", children: listItems))
+        
+        return items
+    }
+    
+    private func _taskGroupItem(for element: LinkedElement) -> XMLElement {
+        var items: [XMLNode]
+        switch element.subheadings {
+        case .single(.conceptual(let title)):
+            items = [.text(title)]
+            
+        case .single(.symbol(let fragments)):
+            items = switch goal {
+            case .conciseness:
+                [ .element(named: "code", children: [.text(fragments.map(\.text).joined())]) ]
+            case .quality:
+                [ _symbolSubheading(fragments, languageFilter: nil) ]
+            }
+            break
+            
+        case .languageSpecificSymbol(let fragmentsByLanguage):
+            let fragmentsByLanguage = RenderHelpers.sortedLanguageSpecificValues(fragmentsByLanguage)
+            items = if fragmentsByLanguage.count == 1 {
+                [ _symbolSubheading(fragmentsByLanguage.first!.value, languageFilter: nil) ]
+            } else if goal == .conciseness, let fragments = fragmentsByLanguage.first?.value {
+                [ _symbolSubheading(fragments, languageFilter: nil) ]
+            } else {
+                fragmentsByLanguage.map { language, fragments in
+                    _symbolSubheading(fragments, languageFilter: language)
+                }
+            }
+        }
+        
+        // Add the formatted abstract if the
+        if let abstract = element.abstract {
+            items.append(visit(abstract))
+        }
+        
+        return .element(named: "li", children: [
+            .element(named: "a", children: items, attributes: ["href": path(to: element.path)])
+        ])
+    }
+    
+    private func _symbolSubheading(_ fragments: [LinkedElement.SymbolNameFragment], languageFilter: SourceLanguage?) -> XMLElement {
+        switch goal {
+        case .quality:
+            .element(
+                named: "code",
+                children: fragments.map {
+                    .element(named: "span", children: RenderHelpers.wordBreak(symbolName: $0.text), attributes: ["class": $0.kind.rawValue])
+                },
+                attributes: languageFilter.map { ["class": "\($0.id)-only"] }
+            )
+        case .conciseness:
+            .element(
+                named: "code",
+                children: [.text(fragments.map(\.text).joined())],
+                attributes: languageFilter.map { ["class": "\($0.id)-only"] }
+            )
+        }
+    }
+}
+
+extension XMLNode {
+    static func selfReferencingHeader(level: Int, title: String) -> XMLElement {
+        let id = urlReadableFragment(title.lowercased())
+        return .element(
+            named: "h\(level)",
+            children: [
+                .element(
+                    named: "a",
+                    children: [.text(title)],
+                    attributes: ["href": "#\(id)"]
+                )
+            ],
+            attributes: ["id": id]
+        )
+    }
+}
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 98dbcd4390..4ff66e6eee 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -79,6 +79,7 @@ private struct ContextLinkProvider: DocCHTML.LinkProvider {
                     current = .init(text: fragment.spelling, kind: kind)
                 }
             }
+            result.append(current)
             return result
         }
         
@@ -251,7 +252,17 @@ struct HTMLRenderer {
         // Topics
         if let topics = article.topics {
             separateCurationIfNeeded()
-            articleElement.addChild(makeGroupedSection(topics))
+            
+            // TODO: Support language specific topic sections
+            articleElement.addChild(
+                renderer.topicsSection([
+                    .swift: topics.taskGroups.map { group in
+                        .init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
+                            $0.destination.flatMap { URL(string: $0) }
+                        })
+                    }
+                ])
+            )
         }
         // Articles don't have automatic topic sections
         
@@ -464,39 +475,27 @@ struct HTMLRenderer {
         if let topics = symbol.topics {
             separateCurationIfNeeded()
             
-            articleElement.addChild(makeGroupedSection(topics))
+            // TODO: Support language specific topic sections
+            articleElement.addChild(
+                renderer.topicsSection([
+                    .swift: topics.taskGroups.map { group in
+                        .init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
+                            $0.destination.flatMap { URL(string: $0) }
+                        })
+                    }
+                ])
+            )
         }
-        if let automaticTopics = try? AutomaticCuration.topics(for: node, withTraits: [.swift, .objectiveC], context: context) {
-            // Automatice SeeAlso
-            let section = XMLElement(name: "section")
-            
-            var didAddAnyLink = false
-            
-            if let title = TopicsSection.title {
-                section.addChild(
-                    .selfReferencingHeader(title: title)
-                )
-            }
-            
-            for automaticTopic in automaticTopics {
-                if let heading = automaticTopic.title {
-                    section.addChild(
-                        .selfReferencingHeader(level: 3, title: heading)
-                    )
-                }
-                
-                for link in automaticTopic.references {
-                    if let element = self.makeTopicSectionItem(for: link) {
-                        didAddAnyLink = true
-                        section.addChild(element)
+        if let automaticTopics = try? AutomaticCuration.topics(for: node, withTraits: [.swift, .objectiveC], context: context),
+           automaticTopics.contains(where: { !$0.references.isEmpty })
+        {
+            articleElement.addChild(
+                renderer.topicsSection([
+                    .swift: automaticTopics.map { group in
+                        .init(title: group.title, content: [], references: group.references.compactMap { $0.url })
                     }
-                }
-            }
-            
-            if didAddAnyLink {
-                separateCurationIfNeeded()
-                articleElement.addChild(section)
-            }
+                ])
+            )
         }
         
         // See Also
diff --git a/Sources/SwiftDocCTestUtilities/SymbolGraphCreation.swift b/Sources/SwiftDocCTestUtilities/SymbolGraphCreation.swift
index 6a15e4596b..419b27ffc6 100644
--- a/Sources/SwiftDocCTestUtilities/SymbolGraphCreation.swift
+++ b/Sources/SwiftDocCTestUtilities/SymbolGraphCreation.swift
@@ -107,7 +107,7 @@ extension XCTestCase {
         
         return SymbolGraph.Symbol(
             identifier: SymbolGraph.Symbol.Identifier(precise: id, interfaceLanguage: language.id),
-            names: makeSymbolNames(name: pathComponents.last!),
+            names: makeSymbolNames(name: pathComponents.last!, kindID: kindID),
             pathComponents: pathComponents,
             docComment: docComment.map {
                 makeLineList(
@@ -133,13 +133,20 @@ extension XCTestCase {
         return SymbolGraph.Symbol.Availability.AvailabilityItem(domain: .init(rawValue: domainName), introducedVersion: introduced, deprecatedVersion: deprecated, obsoletedVersion: obsoleted, message: nil, renamed: nil, isUnconditionallyDeprecated: false, isUnconditionallyUnavailable: unconditionallyUnavailable, willEventuallyBeDeprecated: false)
     }
     
-    package func makeSymbolNames(name: String) -> SymbolGraph.Symbol.Names {
-        SymbolGraph.Symbol.Names(
-            title: name,
-            navigator: [.init(kind: .identifier, spelling: name, preciseIdentifier: nil)],
-            subHeading: [.init(kind: .identifier, spelling: name, preciseIdentifier: nil)],
-            prose: nil
+    package func makeSymbolNames(name: String, kindID: SymbolGraph.Symbol.KindIdentifier? = nil) -> SymbolGraph.Symbol.Names {
+        var fragments: [SymbolGraph.Symbol.DeclarationFragments.Fragment] = []
+        if let kindID {
+            fragments.append(contentsOf: [
+                // This is not entirely correct but it's a fair approximation for test that that may not even be checked against.
+                .init(kind: .keyword, spelling: kindID.identifier, preciseIdentifier: nil),
+                .init(kind: .text,    spelling: " ",               preciseIdentifier: nil),
+            ])
+        }
+        fragments.append(
+            .init(kind: .identifier, spelling: name, preciseIdentifier: nil)
         )
+        
+        return SymbolGraph.Symbol.Names(title: name,navigator: fragments, subHeading: fragments, prose: nil)
     }
     
     package func makeSymbolKind(_ kindID: SymbolGraph.Symbol.KindIdentifier) -> SymbolGraph.Symbol.Kind {
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index ab46b1fff7..f4ba87aa20 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -456,6 +456,138 @@ struct MarkdownRenderer_PageElementsTests {
         }
     }
     
+    @Test(arguments: RenderGoal.allCases)
+    func testRenderSingleLanguageTopicSectionsWithMultiLanguageLinks(goal: RenderGoal) {
+        let elements = [
+            LinkedElement(
+                path: URL(string: "/documentation/ModuleName/SomeClass/index.html")!,
+                names: .languageSpecificSymbol([
+                    .swift:      "SomeClass",
+                    .objectiveC: "TLASomeClass",
+                ]),
+                subheadings: .languageSpecificSymbol([
+                    .swift: [
+                        .init(text: "class ",    kind: .decorator),
+                        .init(text: "SomeClass", kind: .identifier),
+                    ],
+                    .objectiveC: [
+                        .init(text: "class ",       kind: .decorator),
+                        .init(text: "TLASomeClass", kind: .identifier),
+                    ],
+                ]),
+                abstract: nil
+            ),
+            LinkedElement(
+                path: URL(string: "/documentation/ModuleName/SomeClass/someMethod(with:and:)/index.html")!,
+                names: .languageSpecificSymbol([
+                    .swift:      "someMethod(with:and:)",
+                    .objectiveC: "someMethodWithFirst:andSecond:",
+                ]),
+                subheadings: .languageSpecificSymbol([
+                    .swift: [
+                        .init(text: "func ",      kind: .decorator),
+                        .init(text: "someMethod", kind: .identifier),
+                        .init(text: "(",          kind: .decorator),
+                        .init(text: "with",       kind: .identifier),
+                        .init(text: ": Int, ",    kind: .decorator),
+                        .init(text: "and",        kind: .identifier),
+                        .init(text: ": String)",  kind: .decorator),
+                    ],
+                    .objectiveC: [
+                        .init(text: "- ", kind: .decorator),
+                        .init(text: "someMethodWithFirst:andSecond:", kind: .identifier),
+                    ],
+                ]),
+                abstract: nil
+            ),
+        ]
+        
+        let topicSection = makeRenderer(goal: goal, elementsToReturn: elements).topicsSection([
+            .swift: [
+                .init(title: "Group title", content: parseMarkup(string: "Some description of this group"), references: [
+                    URL(string: "/documentation/ModuleName/SomeClass/index.html")!,
+                    URL(string: "/documentation/ModuleName/SomeClass/someMethod(with:and:)/index.html")!,
+                ])
+            ]
+        ])
+        
+        switch goal {
+        case .quality:
+            #expect(topicSection.rendered(prettyFormatted: true) == """
+            <section id="topics">
+            <h2>
+                <a href="#topics">Topics</a>
+            </h2>
+            <h3 id="group-title">
+                <a href="#group-title">Group title</a>
+            </h3>
+            <p>Some description of this group</p>
+            <ul>
+                <li>
+                    <a href="../../../SomeClass/index.html">
+                        <code class="swift-only">
+                            <span class="decorator">class </span>
+                            <span class="identifier">Some<wbr/>
+                                Class</span>
+                        </code>
+                        <code class="occ-only">
+                            <span class="decorator">class </span>
+                            <span class="identifier">TLASome<wbr/>
+                                Class</span>
+                        </code>
+                    </a>
+                </li>
+                <li>
+                    <a href="../../../SomeClass/someMethod(with:and:)/index.html">
+                        <code class="swift-only">
+                            <span class="decorator">func </span>
+                            <span class="identifier">some<wbr/>
+                                Method</span>
+                            <span class="decorator">(</span>
+                            <span class="identifier">with</span>
+                            <span class="decorator">:<wbr/>
+                                 Int, </span>
+                            <span class="identifier">and</span>
+                            <span class="decorator">:<wbr/>
+                                 String)</span>
+                        </code>
+                        <code class="occ-only">
+                            <span class="decorator">- </span>
+                            <span class="identifier">some<wbr/>
+                                Method<wbr/>
+                                With<wbr/>
+                                First:<wbr/>
+                                and<wbr/>
+                                Second:</span>
+                        </code>
+                    </a>
+                </li>
+            </ul>
+            </section>
+            """)
+        case .conciseness:
+            #expect(topicSection.rendered(prettyFormatted: true) == """
+            <section>
+            <h2>Topics</h2>
+            <h3>Group title</h3>
+            <p>Some description of this group</p>
+            <ul>
+                <li>
+                    <a href="../../../SomeClass/index.html">
+                        <code>class SomeClass</code>
+                    </a>
+                </li>
+                <li>
+                    <a href="../../../SomeClass/someMethod(with:and:)/index.html">
+                        <code>func someMethod(with: Int, and: String)</code>
+                    </a>
+                </li>
+            </ul>
+            </section>
+            """)
+        }
+    }
+    
     // MARK: -
     
     private func makeRenderer(
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index ae9208ae12..1cdabb50c2 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -125,10 +125,10 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             Folder(name: "output-dir", content: [])
         ])
         
-        let (bundle, dataProvider) = try DocumentationContext.InputsProvider(fileManager: fileSystem)
+        let (inputs, dataProvider) = try DocumentationContext.InputsProvider(fileManager: fileSystem)
             .inputsAndDataProvider(startingPoint: URL(fileURLWithPath: "/path/to/\(catalog.name)"), options: .init())
         
-        let context = try await DocumentationContext(bundle: bundle, dataProvider: dataProvider, configuration: .init())
+        let context = try await DocumentationContext(bundle: inputs, dataProvider: dataProvider, configuration: .init())
         
         let htmlConsumer = try FileWritingHTMLContentConsumer(
             targetFolder: URL(fileURLWithPath: "/output-dir"),
@@ -188,22 +188,25 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     <pre id="declaration"/>
                 </section>
             </div>
-            <section>
-                <h2 id="Topics">
-                    <a href="#Topics">Topics</a>
+            <section id="topics">
+                <h2>
+                    <a href="#topics">Topics</a>
                 </h2>
-                <h3 id="Classes">
-                    <a href="#Classes">Classes</a>
+                <h3 id="classes">
+                    <a href="#classes">Classes</a>
                 </h3>
-                <div class="link-block">
-                    <a href="SomeClass/index.html">
-                        <code class="swift-only">
-                            <span class="identifier">Some<wbr/>
-                                Class</span>
-                        </code>
-                    </a>
-                    <p>Some in-source description of this class.</p>
-                </div>
+                <ul>
+                    <li>
+                        <a href="../SomeClass/index.html">
+                            <code>
+                                <span class="decorator">class </span>
+                                <span class="identifier">Some<wbr/>
+                                    Class</span>
+                            </code>
+                            <p>Some in-source description of this class.</p>
+                        </a>
+                    </li>
+                </ul>
             </section>
         </article>
         </main></noscript>
@@ -245,24 +248,27 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     </code>
                 </pre>
             </section>
-            <section>
-                <h2 id="Topics">
-                    <a href="#Topics">Topics</a>
+            <section id="topics">
+                <h2>
+                    <a href="#topics">Topics</a>
                 </h2>
-                <h3 id="Instance-Methods">
-                    <a href="#Instance-Methods">Instance Methods</a>
+                <h3 id="instance-methods">
+                    <a href="#instance-methods">Instance Methods</a>
                 </h3>
-                <div class="link-block">
-                    <a href="someMethod(with:and:)/index.html">
-                        <code class="swift-only">
-                            <span class="identifier">some<wbr/>
-                                Method(<wbr/>
-                                with:<wbr/>
-                                and:)</span>
-                        </code>
-                    </a>
-                    <p>Some in-source description of this method.</p>
-                </div>
+                <ul>
+                    <li>
+                        <a href="../someMethod(with:and:)/index.html">
+                            <code>
+                                <span class="decorator">method </span>
+                                <span class="identifier">some<wbr/>
+                                    Method(<wbr/>
+                                    with:<wbr/>
+                                    and:)</span>
+                            </code>
+                            <p>Some in-source description of this method.</p>
+                        </a>
+                    </li>
+                </ul>
             </section>
         </article>
         </main></noscript>

From 5d771d9a5e7a7b3679a7ee039965fad2dd348c05 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 15:29:33 +0100
Subject: [PATCH 41/68] Update HTML content test to include authored Topics and
 SeeAlso sections

---
 Sources/DocCHTML/MarkupRenderer+Topics.swift  |   4 +-
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 145 +++---------------
 .../MarkdownRenderer+PageElementsTests.swift  |  18 ++-
 .../FileWritingHTMLContentConsumerTests.swift |  65 +++++++-
 4 files changed, 95 insertions(+), 137 deletions(-)

diff --git a/Sources/DocCHTML/MarkupRenderer+Topics.swift b/Sources/DocCHTML/MarkupRenderer+Topics.swift
index 504878e8c7..64fd7bc273 100644
--- a/Sources/DocCHTML/MarkupRenderer+Topics.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Topics.swift
@@ -30,7 +30,7 @@ package extension MarkdownRenderer {
         }
     }
     
-    func topicsSection(_ taskGroups: [SourceLanguage: [TaskGroupInfo]]) -> XMLElement {
+    func groupedSection(named sectionName: String, groups taskGroups: [SourceLanguage: [TaskGroupInfo]]) -> XMLElement {
         let taskGroups = RenderHelpers.sortedLanguageSpecificValues(taskGroups)
         
         let items: [XMLElement] = if taskGroups.count == 1 {
@@ -50,7 +50,7 @@ package extension MarkdownRenderer {
             }
         }
         
-        return selfReferencingSection(named: "Topics", content: items)
+        return selfReferencingSection(named: sectionName, content: items)
     }
     
     private func _singleTaskGroupElements(for taskGroup: TaskGroupInfo) -> [XMLElement] {
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 4ff66e6eee..b0a9f4189d 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -255,7 +255,7 @@ struct HTMLRenderer {
             
             // TODO: Support language specific topic sections
             articleElement.addChild(
-                renderer.topicsSection([
+                renderer.groupedSection(named: "Topics", groups: [
                     .swift: topics.taskGroups.map { group in
                         .init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
                             $0.destination.flatMap { URL(string: $0) }
@@ -269,7 +269,16 @@ struct HTMLRenderer {
         // See Also
         if let seeAlso = article.seeAlso {
             separateCurationIfNeeded()
-            articleElement.addChild(makeGroupedSection(seeAlso))
+            
+            articleElement.addChild(
+                renderer.groupedSection(named: "See Also", groups: [
+                    .swift: seeAlso.taskGroups.map { group in
+                        .init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
+                            $0.destination.flatMap { URL(string: $0) }
+                        })
+                    }
+                ])
+            )
         }
         // TODO: Add a way of determining the _automatic_ SeeAlso sections that doesn't query the JSON RenderContext for information.
         
@@ -477,7 +486,7 @@ struct HTMLRenderer {
             
             // TODO: Support language specific topic sections
             articleElement.addChild(
-                renderer.topicsSection([
+                renderer.groupedSection(named: "Topics", groups: [
                     .swift: topics.taskGroups.map { group in
                         .init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
                             $0.destination.flatMap { URL(string: $0) }
@@ -490,7 +499,7 @@ struct HTMLRenderer {
            automaticTopics.contains(where: { !$0.references.isEmpty })
         {
             articleElement.addChild(
-                renderer.topicsSection([
+                renderer.groupedSection(named: "Topics", groups: [
                     .swift: automaticTopics.map { group in
                         .init(title: group.title, content: [], references: group.references.compactMap { $0.url })
                     }
@@ -501,7 +510,16 @@ struct HTMLRenderer {
         // See Also
         if let seeAlso = symbol.seeAlso {
             separateCurationIfNeeded()
-            articleElement.addChild(makeGroupedSection(seeAlso))
+            
+            articleElement.addChild(
+                renderer.groupedSection(named: "See Also", groups: [
+                    .swift: seeAlso.taskGroups.map { group in
+                        .init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
+                            $0.destination.flatMap { URL(string: $0) }
+                        })
+                    }
+                ])
+            )
         }
         // TODO: Add a way of determining the _automatic_ SeeAlso sections that doesn't query the JSON RenderContext for information.
         
@@ -541,123 +559,6 @@ struct HTMLRenderer {
         return section
     }
     
-    private func makeGroupedSection<Grouped: GroupedSection>(_ groupedSection: Grouped) -> XMLNode {
-        let section = XMLElement(name: "section")
-        
-        if let title = Grouped.title {
-            section.addChild(
-                .selfReferencingHeader(title: title)
-            )
-        }
-        
-        for taskGroup in groupedSection.taskGroups {
-            if let heading = taskGroup.heading {
-                section.addChild(
-                    .selfReferencingHeader(level: 3, title: heading.title)
-                )
-            }
-            
-            for link in taskGroup.links {
-                guard let destination = link.destination,
-                      let reference = context.referenceIndex[destination]
-                else {
-                    // Unresolved links wouldn't be found here
-                    continue
-                }
-                
-                if let element = self.makeTopicSectionItem(for: reference) {
-                    section.addChild(element)
-                }
-            }
-        }
-        
-        return section
-    }
-    
-    private func makeTopicSectionItem(for reference: ResolvedTopicReference) -> XMLNode? {
-        if let local = context.documentationCache[reference] {
-            let container = XMLNode.element(named: "div")//, attributes: ["class": className])
-            var className = "link-block"
-             
-            // Title
-            var titles: [XMLNode]? = nil
-            if let symbol = local.semantic as? Symbol {
-                if symbol.isDeprecated {
-                    className += " deprecated"
-                }
-                
-                if case .conceptual(let title) = local.name {
-                    // FIXME: What element and class should this be?
-                    titles = [.element(named: "span", children: [.text(title)])]
-                    
-                }
-                else  {
-                    titles = symbol.subHeadingVariants
-                        .allValues.sorted(by: { $0.trait < $1.trait})
-                        .compactMap { trait, variant in
-                            guard let lang = trait.interfaceLanguage else { return nil }
-                            
-                            return .element(
-                                named: "code",
-                                children: variant.map { fragment in
-                                    let className = switch fragment.kind {
-                                        case .identifier, .externalParameter:
-                                            "identifier"
-                                        default:
-                                            "decorator"
-                                    }
-                                    
-                                    return .element(named: "span", children: RenderHelpers.wordBreak(symbolName: fragment.spelling), attributes: ["class": className])
-                                },
-                                attributes: ["class": "\(lang)-only"]
-                            )
-                        }
-                }
-                
-            } else if let article = local.semantic as? Article {
-                if let heading = article.title {
-                    // FIXME: What element and class should this be?
-                    titles = [.element(named: "span", children: [.text(heading.title)])]
-                }
-            }
-            container.setAttributesWith(["class": className])
-            if let titles {
-                container.addChild(
-                    .element(named: "a", children: titles, attributes: ["href": path(to: reference)])
-                )
-            }
-            
-            // Abstract
-            if let abstract = (local.semantic as? any Abstracted)?.abstract {
-                container.addChild(renderer.visit(abstract))
-            }
-            
-            return container
-        } else if let external = context.externalCache[reference] {
-            let container = XMLNode.element(named: "div", attributes: ["class": "link-block"])
-            
-            let title: XMLNode
-            if external.kind.isSymbol, let fragments = external.subheadingDeclarationFragments {
-                title = .element(named: "code", children: fragments.map { fragment in
-                    let className = fragment.kind == .identifier ? "identifier" : "decorator"
-                    return .element(named: "span", children: [.text(fragment.text)], attributes: ["class": className])
-                })
-            } else {
-                // FIXME: What element and class should this be?
-                title = .element(named: "span", children: [.text(external.title)])
-            }
-            
-            container.addChild(
-                .element(named: "a", children: [title], attributes: ["href": path(to: reference)])
-            )
-            
-            // TODO: Support external abstracts as well
-            
-            return container
-        }
-        return nil
-    }
-    
     // FIXME: There's currently nothing calling this. Instead, the 2 `render...` methods return a `RenderedPageInfo` value.
     private func makePage(main: XMLNode, title: String, plainDescription: String?) -> XMLNode {
         let head = XMLElement(name: "head")
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index f4ba87aa20..5f20439e71 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -456,8 +456,8 @@ struct MarkdownRenderer_PageElementsTests {
         }
     }
     
-    @Test(arguments: RenderGoal.allCases)
-    func testRenderSingleLanguageTopicSectionsWithMultiLanguageLinks(goal: RenderGoal) {
+    @Test(arguments: RenderGoal.allCases, ["Topics", "See Also"])
+    func testRenderSingleLanguageGroupedSectionsWithMultiLanguageLinks(goal: RenderGoal, expectedGroupTitle: String) {
         let elements = [
             LinkedElement(
                 path: URL(string: "/documentation/ModuleName/SomeClass/index.html")!,
@@ -502,7 +502,9 @@ struct MarkdownRenderer_PageElementsTests {
             ),
         ]
         
-        let topicSection = makeRenderer(goal: goal, elementsToReturn: elements).topicsSection([
+        let renderer = makeRenderer(goal: goal, elementsToReturn: elements)
+        let expectedSectionID = expectedGroupTitle.lowercased().replacingOccurrences(of: " ", with: "-")
+        let groupedSection = renderer.groupedSection(named: expectedGroupTitle, groups: [
             .swift: [
                 .init(title: "Group title", content: parseMarkup(string: "Some description of this group"), references: [
                     URL(string: "/documentation/ModuleName/SomeClass/index.html")!,
@@ -513,10 +515,10 @@ struct MarkdownRenderer_PageElementsTests {
         
         switch goal {
         case .quality:
-            #expect(topicSection.rendered(prettyFormatted: true) == """
-            <section id="topics">
+            #expect(groupedSection.rendered(prettyFormatted: true) == """
+            <section id="\(expectedSectionID)">
             <h2>
-                <a href="#topics">Topics</a>
+                <a href="#\(expectedSectionID)">\(expectedGroupTitle)</a>
             </h2>
             <h3 id="group-title">
                 <a href="#group-title">Group title</a>
@@ -566,9 +568,9 @@ struct MarkdownRenderer_PageElementsTests {
             </section>
             """)
         case .conciseness:
-            #expect(topicSection.rendered(prettyFormatted: true) == """
+            #expect(groupedSection.rendered(prettyFormatted: true) == """
             <section>
-            <h2>Topics</h2>
+            <h2>\(expectedGroupTitle)</h2>
             <h3>Group title</h3>
             <p>Some description of this group</p>
             <ul>
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 1cdabb50c2..78ff22525d 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -26,6 +26,10 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             This is an article.
             
             It explains how a developer can perform some task using this module.
+            
+            ## See Also
+            
+            - ``SomeClass``
             """),
             
             JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(moduleName: "ModuleName", symbols: [
@@ -47,6 +51,10 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                   - first:  Description of the `first` parameter.
                   - second: Description of the `second` parameter.
                 - Returns:  Description of the return value.
+                
+                ## See Also
+                
+                - <doc:SomeArticle>
                 """, otherMixins: [
                     SymbolGraph.Symbol.DeclarationFragments(declarationFragments: [
                         .init(kind: .keyword,           spelling: "func",       preciseIdentifier: nil),
@@ -93,6 +101,15 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             # ``ModuleName``
             
             Some description of this module
+            
+            ## Topics
+            
+            ## Something custom
+            
+            A custom _formatted_ description of this topic section
+            
+            - <doc:SomeArticle>
+            - ``SomeClass``
             """)
         ])
         
@@ -192,10 +209,14 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 <h2>
                     <a href="#topics">Topics</a>
                 </h2>
-                <h3 id="classes">
-                    <a href="#classes">Classes</a>
-                </h3>
+                <h2>Something custom</h2>
+                <p>A custom <i>formatted</i>
+                     description of this topic section</p>
                 <ul>
+                    <li>
+                        <a href="../SomeArticle/index.html">Some article<p>This is an article.</p>
+                        </a>
+                    </li>
                     <li>
                         <a href="../SomeClass/index.html">
                             <code>
@@ -349,12 +370,26 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 </h2>
                 <p>Description of the return value.</p>
             </section>
-            <section>
+            <section class="separated">
                 <h2 id="Discussion">
                     <a href="#Discussion">Discussion</a>
                 </h2>
                 <p>Further description of this method and how to use it.</p>
             </section>
+            <section id="see-also">
+                <h2>
+                    <a href="#see-also">See Also</a>
+                </h2>
+                <h3 id="related-documentation">
+                    <a href="#related-documentation">Related Documentation</a>
+                </h3>
+                <ul>
+                    <li>
+                        <a href="../../../SomeArticle/index.html">Some article<p>This is an article.</p>
+                        </a>
+                    </li>
+                </ul>
+            </section>
         </article>
         </main></noscript>
             <div id="app"></div>
@@ -390,12 +425,32 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     <p id="abstract">This is an article.</p>
                 </section>
             </div>
-            <section>
+            <section class="separated">
                 <h2 id="Overview">
                     <a href="#Overview">Overview</a>
                 </h2>
                 <p>It explains how a developer can perform some task using this module.</p>
             </section>
+            <section id="see-also">
+                <h2>
+                    <a href="#see-also">See Also</a>
+                </h2>
+                <h3 id="related-documentation">
+                    <a href="#related-documentation">Related Documentation</a>
+                </h3>
+                <ul>
+                    <li>
+                        <a href="../../SomeClass/index.html">
+                            <code>
+                                <span class="decorator">class </span>
+                                <span class="identifier">Some<wbr/>
+                                    Class</span>
+                            </code>
+                            <p>Some in-source description of this class.</p>
+                        </a>
+                    </li>
+                </ul>
+            </section>
         </article>
         </main></noscript>
             <div id="app"></div>

From 9b401a32447ee66b97fb29f9653060d0f3ad97b5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 15:58:06 +0100
Subject: [PATCH 42/68] Use thematic breaks instead of element classes to
 separate sections

---
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 83 +++++++------------
 .../FileWritingHTMLContentConsumerTests.swift | 12 ++-
 2 files changed, 39 insertions(+), 56 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index b0a9f4189d..3c49bb5273 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -231,22 +231,12 @@ struct HTMLRenderer {
             articleElement.addChild(makeDiscussion(discussion, isSymbol: false))
         }
         
-        var hasMadeSeparatedCuration = false
-        
         func separateCurationIfNeeded() {
-            guard !hasMadeSeparatedCuration, goal == .quality else {
-                return
-            }
-            
-            guard let section: XMLElement = (articleElement.children ?? []).reversed().mapFirst(where: {
-                guard let element = $0 as? XMLElement, element.name == "section" else { return nil }
-                return element
-            }) else {
+            guard goal == .quality, ((articleElement.children ?? []).last as? XMLElement)?.name == "section" else {
                 return
             }
             
-            hasMadeSeparatedCuration = true
-            section.setAttributesWith(["class": "separated"])
+            articleElement.addChild(.element(named: "hr")) // Separate the sections with a thematic break
         }
         
         // Topics
@@ -306,7 +296,6 @@ struct HTMLRenderer {
                 .element(named: "div", children: [hero], attributes: ["id": "hero-module"])
             )
         } else {
-            hero.setAttributesWith(["class": "separated"])
             articleElement.addChild(hero)
         }
         
@@ -457,54 +446,44 @@ struct HTMLRenderer {
             )
         }
         
-        // Discussion
-        if let discussion = symbol.discussion {
-            articleElement.addChild(makeDiscussion(discussion, isSymbol: true))
-        }
-        
-        var hasMadeSeparatedCuration = false
-        
         func separateCurationIfNeeded() {
-            guard !hasMadeSeparatedCuration else {
-                return
-            }
-            
-            guard let section: XMLElement = (articleElement.children ?? []).reversed().mapFirst(where: {
-                guard let element = $0 as? XMLElement, element.name == "section" else { return nil }
-                return element
-            }) else {
+            guard goal == .quality, ((articleElement.children ?? []).last as? XMLElement)?.name == "section" else {
                 return
             }
             
-            hasMadeSeparatedCuration = true
-            section.setAttributesWith(["class": "separated"])
+            articleElement.addChild(.element(named: "hr")) // Separate the sections with a thematic break
         }
         
-        // Topics
-        if let topics = symbol.topics {
+        // Discussion
+        if let discussion = symbol.discussion {
             separateCurationIfNeeded()
             
-            // TODO: Support language specific topic sections
-            articleElement.addChild(
-                renderer.groupedSection(named: "Topics", groups: [
-                    .swift: topics.taskGroups.map { group in
-                        .init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
-                            $0.destination.flatMap { URL(string: $0) }
-                        })
-                    }
-                ])
-            )
+            articleElement.addChild(makeDiscussion(discussion, isSymbol: true))
         }
-        if let automaticTopics = try? AutomaticCuration.topics(for: node, withTraits: [.swift, .objectiveC], context: context),
-           automaticTopics.contains(where: { !$0.references.isEmpty })
-        {
-            articleElement.addChild(
-                renderer.groupedSection(named: "Topics", groups: [
-                    .swift: automaticTopics.map { group in
-                        .init(title: group.title, content: [], references: group.references.compactMap { $0.url })
-                    }
-                ])
-            )
+        
+        // Topics
+        do {
+            // TODO: Support language specific topic sections
+            var taskGroupInfo: [MarkdownRenderer<ContextLinkProvider>.TaskGroupInfo] = []
+            
+            if let authored = symbol.topics?.taskGroups {
+                taskGroupInfo.append(contentsOf: authored.map { group in
+                    .init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
+                        $0.destination.flatMap { URL(string: $0) }
+                    })
+                })
+            }
+            if let automatic = try? AutomaticCuration.topics(for: node, withTraits: [.swift, .objectiveC], context: context) {
+                taskGroupInfo.append(contentsOf: automatic.map { group in
+                    .init(title: group.title, content: [], references: group.references.compactMap { $0.url })
+                })
+            }
+            
+            if !taskGroupInfo.isEmpty {
+                separateCurationIfNeeded()
+                
+                articleElement.addChild(renderer.groupedSection(named: "Topics", groups: [.swift: taskGroupInfo]))
+            }
         }
         
         // See Also
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 78ff22525d..ce3146b49d 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -247,7 +247,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
           <body>
             <noscript><main>
         <article>
-            <section class="separated">
+            <section>
                 <header>
                     <nav id="breadcrumbs">
                         <ul>
@@ -269,6 +269,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     </code>
                 </pre>
             </section>
+            <hr/>
             <section id="topics">
                 <h2>
                     <a href="#topics">Topics</a>
@@ -309,7 +310,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
           <body>
             <noscript><main>
         <article>
-            <section class="separated">
+            <section>
                 <header>
                     <nav id="breadcrumbs">
                         <ul>
@@ -370,12 +371,14 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 </h2>
                 <p>Description of the return value.</p>
             </section>
-            <section class="separated">
+            <hr/>
+            <section>
                 <h2 id="Discussion">
                     <a href="#Discussion">Discussion</a>
                 </h2>
                 <p>Further description of this method and how to use it.</p>
             </section>
+            <hr/>
             <section id="see-also">
                 <h2>
                     <a href="#see-also">See Also</a>
@@ -425,12 +428,13 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     <p id="abstract">This is an article.</p>
                 </section>
             </div>
-            <section class="separated">
+            <section>
                 <h2 id="Overview">
                     <a href="#Overview">Overview</a>
                 </h2>
                 <p>It explains how a developer can perform some task using this module.</p>
             </section>
+            <hr/>
             <section id="see-also">
                 <h2>
                     <a href="#see-also">See Also</a>

From aa48c6059dd72bc58a0be664e4648b2c429f2d63 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 16:26:16 +0100
Subject: [PATCH 43/68] Add declaration parameter to makeSymbol(...) helper

---
 .../SymbolGraphCreation.swift                 | 36 ++++---
 .../FileWritingHTMLContentConsumerTests.swift | 95 ++++++++++---------
 2 files changed, 73 insertions(+), 58 deletions(-)

diff --git a/Sources/SwiftDocCTestUtilities/SymbolGraphCreation.swift b/Sources/SwiftDocCTestUtilities/SymbolGraphCreation.swift
index 419b27ffc6..8bd48ead94 100644
--- a/Sources/SwiftDocCTestUtilities/SymbolGraphCreation.swift
+++ b/Sources/SwiftDocCTestUtilities/SymbolGraphCreation.swift
@@ -90,6 +90,7 @@ extension XCTestCase {
         location: (position: SymbolGraph.LineList.SourceRange.Position, url: URL)? = (defaultSymbolPosition, defaultSymbolURL),
         signature: SymbolGraph.Symbol.FunctionSignature? = nil,
         availability: [SymbolGraph.Symbol.Availability.AvailabilityItem]? = nil,
+        declaration: [SymbolGraph.Symbol.DeclarationFragments.Fragment]? = nil,
         otherMixins: [any Mixin] = []
     ) -> SymbolGraph.Symbol {
         precondition(!pathComponents.isEmpty, "Need at least one path component to name the symbol")
@@ -104,10 +105,24 @@ extension XCTestCase {
         if let availability {
             mixins.append(SymbolGraph.Symbol.Availability(availability: availability))
         }
+        if let declaration {
+            mixins.append(SymbolGraph.Symbol.DeclarationFragments(declarationFragments: declaration))
+        }
+        
+        let names = if let declaration {
+            SymbolGraph.Symbol.Names(
+                title: pathComponents.last!, // Verified above to exist
+                navigator: declaration,
+                subHeading: declaration,
+                prose: nil
+            )
+        } else {
+            makeSymbolNames(name: pathComponents.last!) // Verified above to exist
+        }
         
         return SymbolGraph.Symbol(
             identifier: SymbolGraph.Symbol.Identifier(precise: id, interfaceLanguage: language.id),
-            names: makeSymbolNames(name: pathComponents.last!, kindID: kindID),
+            names: names,
             pathComponents: pathComponents,
             docComment: docComment.map {
                 makeLineList(
@@ -133,20 +148,13 @@ extension XCTestCase {
         return SymbolGraph.Symbol.Availability.AvailabilityItem(domain: .init(rawValue: domainName), introducedVersion: introduced, deprecatedVersion: deprecated, obsoletedVersion: obsoleted, message: nil, renamed: nil, isUnconditionallyDeprecated: false, isUnconditionallyUnavailable: unconditionallyUnavailable, willEventuallyBeDeprecated: false)
     }
     
-    package func makeSymbolNames(name: String, kindID: SymbolGraph.Symbol.KindIdentifier? = nil) -> SymbolGraph.Symbol.Names {
-        var fragments: [SymbolGraph.Symbol.DeclarationFragments.Fragment] = []
-        if let kindID {
-            fragments.append(contentsOf: [
-                // This is not entirely correct but it's a fair approximation for test that that may not even be checked against.
-                .init(kind: .keyword, spelling: kindID.identifier, preciseIdentifier: nil),
-                .init(kind: .text,    spelling: " ",               preciseIdentifier: nil),
-            ])
-        }
-        fragments.append(
-            .init(kind: .identifier, spelling: name, preciseIdentifier: nil)
+    package func makeSymbolNames(name: String) -> SymbolGraph.Symbol.Names {
+        SymbolGraph.Symbol.Names(
+            title: name,
+            navigator: [.init(kind: .identifier, spelling: name, preciseIdentifier: nil)],
+            subHeading: [.init(kind: .identifier, spelling: name, preciseIdentifier: nil)],
+            prose: nil
         )
-        
-        return SymbolGraph.Symbol.Names(title: name,navigator: fragments, subHeading: fragments, prose: nil)
     }
     
     package func makeSymbolKind(_ kindID: SymbolGraph.Symbol.KindIdentifier) -> SymbolGraph.Symbol.Kind {
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index ce3146b49d..536bccca2e 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -35,28 +35,45 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(moduleName: "ModuleName", symbols: [
                 makeSymbol(id: "some-class-id", kind: .class, pathComponents: ["SomeClass"], docComment: """
                 Some in-source description of this class.
-                """, otherMixins: [
-                    SymbolGraph.Symbol.DeclarationFragments(declarationFragments: [
-                        .init(kind: .keyword,    spelling: "class",     preciseIdentifier: nil),
-                        .init(kind: .text,       spelling: " ",         preciseIdentifier: nil),
-                        .init(kind: .identifier, spelling: "SomeClass", preciseIdentifier: nil),
-                    ])
+                """, declaration: [
+                    .init(kind: .keyword,    spelling: "class",     preciseIdentifier: nil),
+                    .init(kind: .text,       spelling: " ",         preciseIdentifier: nil),
+                    .init(kind: .identifier, spelling: "SomeClass", preciseIdentifier: nil),
                 ]),
-                makeSymbol(id: "some-method-id", kind: .method, pathComponents: ["SomeClass", "someMethod(with:and:)"], docComment: """
-                Some in-source description of this method.
-                
-                Further description of this method and how to use it.
-                
-                - Parameters: 
-                  - first:  Description of the `first` parameter.
-                  - second: Description of the `second` parameter.
-                - Returns:  Description of the return value.
-                
-                ## See Also
-                
-                - <doc:SomeArticle>
-                """, otherMixins: [
-                    SymbolGraph.Symbol.DeclarationFragments(declarationFragments: [
+                makeSymbol(
+                    id: "some-method-id", kind: .method, pathComponents: ["SomeClass", "someMethod(with:and:)"],
+                    docComment: """
+                    Some in-source description of this method.
+                    
+                    Further description of this method and how to use it.
+                    
+                    - Parameters: 
+                      - first:  Description of the `first` parameter.
+                      - second: Description of the `second` parameter.
+                    - Returns:  Description of the return value.
+                    
+                    ## See Also
+                    
+                    - <doc:SomeArticle>
+                    """,
+                    signature: .init(
+                        parameters: [
+                            .init(name: "first", externalName: "with", declarationFragments: [
+                                .init(kind: .identifier,     spelling: "first",  preciseIdentifier: nil),
+                                .init(kind: .text,           spelling: ": ",     preciseIdentifier: nil),
+                                .init(kind: .typeIdentifier, spelling: "Int",    preciseIdentifier: "s:Si"),
+                            ], children: []),
+                            .init(name: "second", externalName: "and", declarationFragments: [
+                                .init(kind: .identifier,     spelling: "first",  preciseIdentifier: nil),
+                                .init(kind: .text,           spelling: ": ",     preciseIdentifier: nil),
+                                .init(kind: .typeIdentifier, spelling: "String", preciseIdentifier: "s:Ss"),
+                            ], children: [])
+                        ],
+                        returns: [
+                            .init(kind: .typeIdentifier,     spelling: "Bool",    preciseIdentifier: "s:Sb"),
+                        ]
+                    ),
+                    declaration: [
                         .init(kind: .keyword,           spelling: "func",       preciseIdentifier: nil),
                         .init(kind: .text,              spelling: " ",          preciseIdentifier: nil),
                         .init(kind: .identifier,        spelling: "someMethod", preciseIdentifier: nil),
@@ -74,25 +91,8 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                         .init(kind: .typeIdentifier,    spelling: "String",     preciseIdentifier: "s:SS"),
                         .init(kind: .text,              spelling: ") -> ",      preciseIdentifier: nil),
                         .init(kind: .typeIdentifier,    spelling: "Bool",       preciseIdentifier: "s:Sb"),
-                    ]),
-                    SymbolGraph.Symbol.FunctionSignature(
-                        parameters: [
-                            .init(name: "first", externalName: "with", declarationFragments: [
-                                .init(kind: .identifier,     spelling: "first",  preciseIdentifier: nil),
-                                .init(kind: .text,           spelling: ": ",     preciseIdentifier: nil),
-                                .init(kind: .typeIdentifier, spelling: "Int",    preciseIdentifier: "s:Si"),
-                            ], children: []),
-                            .init(name: "second", externalName: "and", declarationFragments: [
-                                .init(kind: .identifier,     spelling: "first",  preciseIdentifier: nil),
-                                .init(kind: .text,           spelling: ": ",     preciseIdentifier: nil),
-                                .init(kind: .typeIdentifier, spelling: "String", preciseIdentifier: "s:Ss"),
-                            ], children: [])
-                        ],
-                        returns: [
-                            .init(kind: .typeIdentifier,     spelling: "Bool",    preciseIdentifier: "s:Sb"),
-                        ]
-                    )
-                ])
+                    ]
+                )
             ], relationships: [
                 .init(source: "some-method-id", target: "some-class-id", kind: .memberOf, targetFallback: nil)
             ])),
@@ -281,11 +281,18 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     <li>
                         <a href="../someMethod(with:and:)/index.html">
                             <code>
-                                <span class="decorator">method </span>
+                                <span class="decorator">func </span>
                                 <span class="identifier">some<wbr/>
-                                    Method(<wbr/>
-                                    with:<wbr/>
-                                    and:)</span>
+                                    Method</span>
+                                <span class="decorator">(</span>
+                                <span class="identifier">with</span>
+                                <span class="decorator"> first:<wbr/>
+                                     Int, </span>
+                                <span class="identifier">and</span>
+                                <span class="decorator"> second:<wbr/>
+                                     String)<wbr/>
+                                     -&gt;<wbr/>
+                                     Bool</span>
                             </code>
                             <p>Some in-source description of this method.</p>
                         </a>

From 5890088e44be83da2f3a9bf6233d5b9ed7ce8821 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 16:31:57 +0100
Subject: [PATCH 44/68] Simplify HTML element for the "eyebrow"

---
 .../Model/Rendering/HTML/HTMLRenderer.swift          | 12 ++++--------
 .../Convert/FileWritingHTMLContentConsumer.swift     | 10 +++++-----
 .../FileWritingHTMLContentConsumerTests.swift        |  8 ++++----
 3 files changed, 13 insertions(+), 17 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 3c49bb5273..3fc93076f5 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -200,17 +200,13 @@ struct HTMLRenderer {
                 ),
                 
                 .element(
-                    named: "span",
+                    named: "p",
                     children: [.text(article.topics == nil ? "Article": "API Collection")],
-                    attributes: ["class": "eyebrow"]
+                    attributes: ["id": "eyebrow"]
                 ),
             ])
         )
         
-        
-        // FIXME: Add a background for articles
-        // FIXME: Then add a background for the Framework page
-        
         // Title
         hero.addChild(
             .element(named: "h1", children: [.text(node.name.plainText)])
@@ -321,9 +317,9 @@ struct HTMLRenderer {
                 ),
                 
                 .element(
-                    named: "span",
+                    named: "p",
                     children: [.text(symbol.roleHeading)],
-                    attributes: ["class": "eyebrow"]
+                    attributes: ["id": "eyebrow"]
                 ),
             ])
         )
diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
index 701fc277cc..5f01affd68 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
@@ -1,11 +1,11 @@
 /*
-This source file is part of the Swift.org open source project
+ This source file is part of the Swift.org open source project
 
-Copyright (c) 2025 Apple Inc. and the Swift project authors
-Licensed under Apache License v2.0 with Runtime Library Exception
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
 
-See https://swift.org/LICENSE.txt for license information
-See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
 import Foundation
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 536bccca2e..f49c0d9232 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -197,7 +197,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                                 <li>ModuleName</li>
                             </ul>
                         </nav>
-                        <span class="eyebrow">Framework</span>
+                        <p id="eyebrow">Framework</p>
                     </header>
                     <h1>Module<wbr/>
                         Name</h1>
@@ -257,7 +257,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                             <li>SomeClass</li>
                         </ul>
                     </nav>
-                    <span class="eyebrow">Class</span>
+                    <p id="eyebrow">Class</p>
                 </header>
                 <h1>Some<wbr/>
                     Class</h1>
@@ -330,7 +330,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                             <li>someMethod(with:and:)</li>
                         </ul>
                     </nav>
-                    <span class="eyebrow">Instance Method</span>
+                    <p id="eyebrow">Instance Method</p>
                 </header>
                 <h1>some<wbr/>
                     Method(<wbr/>
@@ -429,7 +429,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                                 <li>Some article</li>
                             </ul>
                         </nav>
-                        <span class="eyebrow">Article</span>
+                        <p id="eyebrow">Article</p>
                     </header>
                     <h1>Some article</h1>
                     <p id="abstract">This is an article.</p>

From c25e8fa7031856e76c6d50bb94e057a53f68ef38 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 16:38:28 +0100
Subject: [PATCH 45/68] Simplify creation of Discussion/Overview section

---
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 27 +++++--------------
 .../FileWritingHTMLContentConsumerTests.swift | 12 ++++-----
 2 files changed, 13 insertions(+), 26 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 3fc93076f5..7785df02d0 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -508,30 +508,17 @@ struct HTMLRenderer {
     }
     
     private func makeDiscussion(_ discussion: DiscussionSection, isSymbol: Bool) -> XMLNode {
-        let section = XMLElement(name: "section")
-        
-        // Don't add a heading if it's already authored
-        if (discussion.content.first as? Heading)?.level != 2 {
-            section.addChild(
-                .selfReferencingHeader(title: isSymbol ? "Discussion" : "Overview")
-            )
-        }
-        
         var remaining = discussion.content[...]
-        if let heading = discussion.content.first as? Heading, heading.level == 2 {
-            _ = remaining.removeFirst()
-            section.addChild(
-                .selfReferencingHeader(title: heading.title)
-            )
-        }
         
-        for markup in remaining {
-            section.addChild(
-                renderer.visit(markup)
-            )
+        let title: String
+        if let heading = remaining.first as? Heading, heading.level == 2 {
+            _ = remaining.removeFirst() // Make the authored heading reference the section, not itself
+            title = heading.title
+        } else {
+            title = isSymbol ? "Discussion" : "Overview"
         }
         
-        return section
+        return renderer.selfReferencingSection(named: title, content: remaining.map { renderer.visit($0) })
     }
     
     // FIXME: There's currently nothing calling this. Instead, the 2 `render...` methods return a `RenderedPageInfo` value.
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index f49c0d9232..343b053f6e 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -379,9 +379,9 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 <p>Description of the return value.</p>
             </section>
             <hr/>
-            <section>
-                <h2 id="Discussion">
-                    <a href="#Discussion">Discussion</a>
+            <section id="discussion">
+                <h2>
+                    <a href="#discussion">Discussion</a>
                 </h2>
                 <p>Further description of this method and how to use it.</p>
             </section>
@@ -435,9 +435,9 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     <p id="abstract">This is an article.</p>
                 </section>
             </div>
-            <section>
-                <h2 id="Overview">
-                    <a href="#Overview">Overview</a>
+            <section id="overview">
+                <h2>
+                    <a href="#overview">Overview</a>
                 </h2>
                 <p>It explains how a developer can perform some task using this module.</p>
             </section>

From 3bff6ad2f9d9f0b1cb1d8cabd9e6c4a210125ec6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 16:57:51 +0100
Subject: [PATCH 46/68] Make headings link to themselves by default

---
 Sources/DocCHTML/MarkdownRenderer.swift       | 21 +++++++++-
 Sources/DocCHTML/MarkupRenderer+Topics.swift  | 24 +-----------
 .../DocCHTMLTests/MarkdownRendererTests.swift | 38 +++++++++++++------
 .../FileWritingHTMLContentConsumerTests.swift | 20 ++++++++--
 4 files changed, 64 insertions(+), 39 deletions(-)

diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index 1593ce87b9..2fa619f16c 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -60,7 +60,26 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
     }
     
     package func visit(_ heading: Heading) -> XMLNode {
-        .element(named: "h\(heading.level)", children: visit(heading.children))
+        selfReferencingHeading(level: heading.level, content: visit(heading.children), plainTextTitle: heading.plainText)
+    }
+    
+    func selfReferencingHeading(level: Int, content: [XMLNode], plainTextTitle: @autoclosure () -> String) -> XMLElement {
+        switch goal {
+        case .conciseness:
+            return .element(named: "h\(level)", children: content)
+            
+        case .quality:
+            let id = urlReadableFragment(plainTextTitle().lowercased())
+            return .element(
+                named: "h\(level)",
+                children: [
+                    // Wrap the heading content in an anchor ...
+                    .element(named: "a", children: content, attributes: ["href": "#\(id)"])
+                ],
+                // ... that refers to the heading itself
+                attributes: ["id": id]
+            )
+        }
     }
     
     func visit(_ emphasis: Emphasis) -> XMLNode {
diff --git a/Sources/DocCHTML/MarkupRenderer+Topics.swift b/Sources/DocCHTML/MarkupRenderer+Topics.swift
index 64fd7bc273..a2f560e096 100644
--- a/Sources/DocCHTML/MarkupRenderer+Topics.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Topics.swift
@@ -63,12 +63,7 @@ package extension MarkdownRenderer {
         var items: [XMLElement] = []
         // Title
         if let title = taskGroup.title {
-            switch goal {
-            case .quality:
-                items.append(.selfReferencingHeader(level: 3, title: title))
-            case .conciseness:
-                items.append(.element(named: "h3", children: [.text(title)]))
-            }
+            items.append(selfReferencingHeading(level: 3, content: [.text(title)], plainTextTitle: title))
         }
         // Abstract/Discussion
         for markup in taskGroup.content {
@@ -143,20 +138,3 @@ package extension MarkdownRenderer {
         }
     }
 }
-
-extension XMLNode {
-    static func selfReferencingHeader(level: Int, title: String) -> XMLElement {
-        let id = urlReadableFragment(title.lowercased())
-        return .element(
-            named: "h\(level)",
-            children: [
-                .element(
-                    named: "a",
-                    children: [.text(title)],
-                    attributes: ["href": "#\(id)"]
-                )
-            ],
-            attributes: ["id": id]
-        )
-    }
-}
diff --git a/Tests/DocCHTMLTests/MarkdownRendererTests.swift b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
index eb2e74e134..e0cd5538f7 100644
--- a/Tests/DocCHTMLTests/MarkdownRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
@@ -45,9 +45,15 @@ struct MarkdownRendererTests {
             """,
             prettyFormatted: true,
             matches: """
-            <h1>One</h1>
-            <h2>Two</h2>
-            <h3>Three</h3>
+            <h1 id="one">
+            <a href="#one">One</a>
+            </h1>
+            <h2 id="two">
+            <a href="#two">Two</a>
+            </h2>
+            <h3 id="three">
+            <a href="#three">Three</a>
+            </h3>
             """
         )
         
@@ -61,8 +67,12 @@ struct MarkdownRendererTests {
             """,
             prettyFormatted: true,
             matches: """
-            <h1>One</h1>
-            <h2>Two</h2>
+            <h1 id="one">
+            <a href="#one">One</a>
+            </h1>
+            <h2 id="two">
+            <a href="#two">Two</a>
+            </h2>
             """
         )
         
@@ -76,14 +86,20 @@ struct MarkdownRendererTests {
             """,
             prettyFormatted: true,
             matches: """
-            <h1>
-            <i>One</i>
+            <h1 id="one">
+            <a href="#one">
+                <i>One</i>
+            </a>
             </h1>
-            <h2>
-            <b>Two</b>
+            <h2 id="two">
+            <a href="#two">
+                <b>Two</b>
+            </a>
             </h2>
-            <h3>
-            <code>Three</code>
+            <h3 id="three">
+            <a href="#three">
+                <code>Three</code>
+            </a>
             </h3>
             """
         )
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 343b053f6e..2dee0a8d68 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -25,8 +25,14 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             
             This is an article.
             
+            ## Custom discussion
+            
             It explains how a developer can perform some task using this module.
             
+            ### Details
+            
+            This subsection describes something more detailed.
+            
             ## See Also
             
             - ``SomeClass``
@@ -104,7 +110,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             
             ## Topics
             
-            ## Something custom
+            ### Something custom
             
             A custom _formatted_ description of this topic section
             
@@ -209,7 +215,9 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 <h2>
                     <a href="#topics">Topics</a>
                 </h2>
-                <h2>Something custom</h2>
+                <h3 id="something-custom">
+                    <a href="#something-custom">Something custom</a>
+                </h3>
                 <p>A custom <i>formatted</i>
                      description of this topic section</p>
                 <ul>
@@ -435,11 +443,15 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     <p id="abstract">This is an article.</p>
                 </section>
             </div>
-            <section id="overview">
+            <section id="custom-discussion">
                 <h2>
-                    <a href="#overview">Overview</a>
+                    <a href="#custom-discussion">Custom discussion</a>
                 </h2>
                 <p>It explains how a developer can perform some task using this module.</p>
+                <h3 id="details">
+                    <a href="#details">Details</a>
+                </h3>
+                <p>This subsection describes something more detailed.</p>
             </section>
             <hr/>
             <section id="see-also">

From e5a822eb65fa0ec61581804185c628496811cbb4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 18:28:47 +0100
Subject: [PATCH 47/68] Include description meta element in the HTML

---
 .../FileWritingHTMLContentConsumer.swift      | 40 ++++++++++++-------
 .../FileWritingHTMLContentConsumerTests.swift |  8 ++--
 2 files changed, 29 insertions(+), 19 deletions(-)

diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
index 5f01affd68..a08f5f050d 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
@@ -10,6 +10,7 @@
 
 import Foundation
 import SwiftDocC
+import DocCHTML
 
 struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
     var targetFolder: URL
@@ -18,37 +19,46 @@ struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
     var prettyPrintOutput: Bool
     
     private struct HTMLTemplate {
-        var beforeTitle: String
-        var fromTitleToNoScript: String
-        var afterNoScript: String
+        var original: String
+        var contentReplacementRange:     Range<String.Index>
+        var titleReplacementRange:       Range<String.Index>
+        var descriptionReplacementRange: Range<String.Index>
         
         init(data: Data) throws {
             let content = String(decoding: data, as: UTF8.self)
             
-            // FIXME: If the template doesn't already contain a <noscript> tag, add one to the start of the <body>
-            let noScriptStart = content.utf8.firstRange(of: "<noscript>".utf8)!.upperBound
+            // ???: Should we parse the content with XMLParser instead? If so, what do we do if it's not valid XHTML?
+            let noScriptStart = content.utf8.firstRange(of:  "<noscript>".utf8)!.upperBound
             let noScriptEnd   = content.utf8.firstRange(of: "</noscript>".utf8)!.lowerBound
             
-            let prefix = content[..<noScriptStart]
-            
-            // FIXME: If the template doesn't already contain a <title> tag, add one to the end of the <head>
-            let titleStart = content.utf8.firstRange(of: "<title>".utf8)!.upperBound
+            let titleStart = content.utf8.firstRange(of:  "<title>".utf8)!.upperBound
             let titleEnd   = content.utf8.firstRange(of: "</title>".utf8)!.lowerBound
             
-            // ???: Should we parse the content with XMLParser instead? If so, what do we do if it's not valid XHTML?
+            let beforeHeadEnd = content.utf8.firstRange(of: "</head>".utf8)!.lowerBound
             
-            beforeTitle         = String( prefix[..<titleStart] )
-            fromTitleToNoScript = String( prefix[titleEnd...] )
-            afterNoScript       = String( content[noScriptEnd...] )
+            original = content
+            // FIXME: If the template doesn't already contain a <noscript> tag, add one to the start of the <body>
+            // FIXME: If the template doesn't already contain a <title> tag, add one to the end of the <head>
+            contentReplacementRange     = noScriptStart ..< noScriptEnd
+            titleReplacementRange       = titleStart    ..< titleEnd
+            descriptionReplacementRange = beforeHeadEnd ..< beforeHeadEnd
         }
         
         func makeContent(
             content: XMLNode,
             title: String,
-            plainDescription _: String?, // FIXME: Insert the description in the <head>
+            plainDescription: String?,
             prettyPrint: Bool
         ) -> String {
-            beforeTitle + title + fromTitleToNoScript + content.rendered(prettyPrinted: prettyPrint) + afterNoScript
+            var copy = original
+            copy.replaceSubrange(contentReplacementRange, with: content.rendered(prettyPrinted: prettyPrint))
+            if let plainDescription {
+                let metaDescription = XMLNode.element(named: "meta", attributes: ["name": "description", "content": plainDescription])
+                copy.replaceSubrange(descriptionReplacementRange, with: metaDescription.rendered(prettyPrinted: prettyPrint))
+            }
+            copy.replaceSubrange(titleReplacementRange,   with: title)
+            
+            return copy
         }
     }
     private var htmlTemplate: HTMLTemplate
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 2dee0a8d68..ce1d6383ba 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -191,7 +191,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <link rel="icon" href="/favicon.ico" />
             <title>ModuleName</title>
             <script>var baseUrl = "/"</script>
-          </head>
+          <meta content="Some description of this module" name="description"/></head>
           <body>
             <noscript><main>
         <article>
@@ -251,7 +251,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <link rel="icon" href="/favicon.ico" />
             <title>SomeClass</title>
             <script>var baseUrl = "/"</script>
-          </head>
+          <meta content="Some in-source description of this class." name="description"/></head>
           <body>
             <noscript><main>
         <article>
@@ -321,7 +321,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <link rel="icon" href="/favicon.ico" />
             <title>someMethod(with:and:)</title>
             <script>var baseUrl = "/"</script>
-          </head>
+          <meta content="Some in-source description of this method." name="description"/></head>
           <body>
             <noscript><main>
         <article>
@@ -422,7 +422,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <link rel="icon" href="/favicon.ico" />
             <title>Some article</title>
             <script>var baseUrl = "/"</script>
-          </head>
+          <meta content="This is an article." name="description"/></head>
           <body>
             <noscript><main>
         <article>

From f5e0bc57000dad34ec71cbb45ce4227f272caee8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 18:40:59 +0100
Subject: [PATCH 48/68] Simplify breadcrumbs and eyebrow HTML

---
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 42 ++++------
 .../FileWritingHTMLContentConsumerTests.swift | 80 +++++++++----------
 2 files changed, 50 insertions(+), 72 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 7785df02d0..a6fd24347b 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -192,20 +192,15 @@ struct HTMLRenderer {
         )
         
         // Breadcrumbs and Eyebrow
-        hero.addChild(
-            .element(named: "header", children: [
-                renderer.breadcrumbs(
-                    references: (context.shortestFinitePath(to: reference) ?? [context.soleRootModuleReference!]).map { $0.url },
-                    currentPageNames: .single(.conceptual(node.name.plainText))
-                ),
-                
-                .element(
-                    named: "p",
-                    children: [.text(article.topics == nil ? "Article": "API Collection")],
-                    attributes: ["id": "eyebrow"]
-                ),
-            ])
-        )
+        hero.addChild(renderer.breadcrumbs(
+            references: (context.shortestFinitePath(to: reference) ?? [context.soleRootModuleReference!]).map { $0.url },
+            currentPageNames: .single(.conceptual(node.name.plainText))
+        ))
+        hero.addChild(.element(
+            named: "p",
+            children: [.text(article.topics == nil ? "Article": "API Collection")],
+            attributes: ["id": "eyebrow"]
+        ))
         
         // Title
         hero.addChild(
@@ -309,20 +304,11 @@ struct HTMLRenderer {
         }
         
         // Breadcrumbs and Eyebrow
-        hero.addChild(
-            .element(named: "header", children: [
-                renderer.breadcrumbs(
-                    references: (context.linkResolver.localResolver.breadcrumbs(of: reference, in: reference.sourceLanguage) ?? []).map { $0.url },
-                    currentPageNames: names
-                ),
-                
-                .element(
-                    named: "p",
-                    children: [.text(symbol.roleHeading)],
-                    attributes: ["id": "eyebrow"]
-                ),
-            ])
-        )
+        hero.addChild(renderer.breadcrumbs(
+            references: (context.linkResolver.localResolver.breadcrumbs(of: reference, in: reference.sourceLanguage) ?? []).map { $0.url },
+            currentPageNames: names
+        ))
+        hero.addChild(.element(named: "p", children: [.text(symbol.roleHeading)], attributes: ["id": "eyebrow"]))
         
         // Title
         let titleVariants = symbol.titleVariants.allValues.sorted(by: { $0.trait < $1.trait})
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index ce1d6383ba..2022f48472 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -197,14 +197,12 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         <article>
             <div id="hero-module">
                 <section>
-                    <header>
-                        <nav id="breadcrumbs">
-                            <ul>
-                                <li>ModuleName</li>
-                            </ul>
-                        </nav>
-                        <p id="eyebrow">Framework</p>
-                    </header>
+                    <nav id="breadcrumbs">
+                        <ul>
+                            <li>ModuleName</li>
+                        </ul>
+                    </nav>
+                    <p id="eyebrow">Framework</p>
                     <h1>Module<wbr/>
                         Name</h1>
                     <p id="abstract">Some description of this module</p>
@@ -256,17 +254,15 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <noscript><main>
         <article>
             <section>
-                <header>
-                    <nav id="breadcrumbs">
-                        <ul>
-                            <li>
-                                <a href="../../index.html">ModuleName</a>
-                            </li>
-                            <li>SomeClass</li>
-                        </ul>
-                    </nav>
-                    <p id="eyebrow">Class</p>
-                </header>
+                <nav id="breadcrumbs">
+                    <ul>
+                        <li>
+                            <a href="../../index.html">ModuleName</a>
+                        </li>
+                        <li>SomeClass</li>
+                    </ul>
+                </nav>
+                <p id="eyebrow">Class</p>
                 <h1>Some<wbr/>
                     Class</h1>
                 <p id="abstract">Some in-source description of this class.</p>
@@ -326,20 +322,18 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <noscript><main>
         <article>
             <section>
-                <header>
-                    <nav id="breadcrumbs">
-                        <ul>
-                            <li>
-                                <a href="../../../index.html">ModuleName</a>
-                            </li>
-                            <li>
-                                <a href="../../index.html">SomeClass</a>
-                            </li>
-                            <li>someMethod(with:and:)</li>
-                        </ul>
-                    </nav>
-                    <p id="eyebrow">Instance Method</p>
-                </header>
+                <nav id="breadcrumbs">
+                    <ul>
+                        <li>
+                            <a href="../../../index.html">ModuleName</a>
+                        </li>
+                        <li>
+                            <a href="../../index.html">SomeClass</a>
+                        </li>
+                        <li>someMethod(with:and:)</li>
+                    </ul>
+                </nav>
+                <p id="eyebrow">Instance Method</p>
                 <h1>some<wbr/>
                     Method(<wbr/>
                     with:<wbr/>
@@ -428,17 +422,15 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         <article>
             <div id="hero-article">
                 <section>
-                    <header>
-                        <nav id="breadcrumbs">
-                            <ul>
-                                <li>
-                                    <a href="../../index.html">ModuleName</a>
-                                </li>
-                                <li>Some article</li>
-                            </ul>
-                        </nav>
-                        <p id="eyebrow">Article</p>
-                    </header>
+                    <nav id="breadcrumbs">
+                        <ul>
+                            <li>
+                                <a href="../../index.html">ModuleName</a>
+                            </li>
+                            <li>Some article</li>
+                        </ul>
+                    </nav>
+                    <p id="eyebrow">Article</p>
                     <h1>Some article</h1>
                     <p id="abstract">This is an article.</p>
                 </section>

From 61381a613ee9beea8820d7130326bda5db42ef5c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 18:44:51 +0100
Subject: [PATCH 49/68] Don't include an empty declaration for module pages

---
 Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift     | 4 +++-
 .../FileWritingHTMLContentConsumerTests.swift                 | 1 -
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index a6fd24347b..3ecb785045 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -375,7 +375,9 @@ struct HTMLRenderer {
                 fragmentsByLanguageID[SourceLanguage(id: languageID)] = variant.values.first?.declarationFragments
             }
             
-            hero.addChild( renderer.declaration(fragmentsByLanguageID) )
+            if fragmentsByLanguageID.values.contains(where: { !$0.isEmpty }) {
+                hero.addChild( renderer.declaration(fragmentsByLanguageID) )
+            }
         }
         
         // Deprecation message
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 2022f48472..18822d6d55 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -206,7 +206,6 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     <h1>Module<wbr/>
                         Name</h1>
                     <p id="abstract">Some description of this module</p>
-                    <pre id="declaration"/>
                 </section>
             </div>
             <section id="topics">

From 1ef26284391317137a2cb2dd2fa7f84cf468b71c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 18:56:32 +0100
Subject: [PATCH 50/68] Use a paragraph for the article title in a topic
 section item

---
 Sources/DocCHTML/MarkupRenderer+Topics.swift  |  2 +-
 .../MarkdownRenderer+PageElementsTests.swift  | 29 ++++++++++++++++++-
 .../FileWritingHTMLContentConsumerTests.swift | 24 ++++++++++-----
 3 files changed, 45 insertions(+), 10 deletions(-)

diff --git a/Sources/DocCHTML/MarkupRenderer+Topics.swift b/Sources/DocCHTML/MarkupRenderer+Topics.swift
index a2f560e096..70e008e55b 100644
--- a/Sources/DocCHTML/MarkupRenderer+Topics.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Topics.swift
@@ -85,7 +85,7 @@ package extension MarkdownRenderer {
         var items: [XMLNode]
         switch element.subheadings {
         case .single(.conceptual(let title)):
-            items = [.text(title)]
+            items = [.element(named: "p", children: [.text(title)])]
             
         case .single(.symbol(let fragments)):
             items = switch goal {
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index 5f20439e71..c3c6db904c 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -475,7 +475,13 @@ struct MarkdownRenderer_PageElementsTests {
                         .init(text: "TLASomeClass", kind: .identifier),
                     ],
                 ]),
-                abstract: nil
+                abstract: parseMarkup(string: "Some _formatted_ description of this class").first as? Paragraph
+            ),
+            LinkedElement(
+                path: URL(string: "/documentation/ModuleName/SomeArticle/index.html")!,
+                names: .single(.conceptual("Some Article")),
+                subheadings: .single(.conceptual("Some Article")),
+                abstract: parseMarkup(string: "Some **formatted** description of this _article_.").first as? Paragraph
             ),
             LinkedElement(
                 path: URL(string: "/documentation/ModuleName/SomeClass/someMethod(with:and:)/index.html")!,
@@ -508,6 +514,7 @@ struct MarkdownRenderer_PageElementsTests {
             .swift: [
                 .init(title: "Group title", content: parseMarkup(string: "Some description of this group"), references: [
                     URL(string: "/documentation/ModuleName/SomeClass/index.html")!,
+                    URL(string: "/documentation/ModuleName/SomeArticle/index.html")!,
                     URL(string: "/documentation/ModuleName/SomeClass/someMethod(with:and:)/index.html")!,
                 ])
             ]
@@ -537,6 +544,16 @@ struct MarkdownRenderer_PageElementsTests {
                             <span class="identifier">TLASome<wbr/>
                                 Class</span>
                         </code>
+                        <p>Some <i>formatted</i>
+                             description of this class</p>
+                    </a>
+                </li>
+                <li>
+                    <a href="../../../SomeArticle/index.html">
+                        <p>Some Article</p>
+                        <p>Some <b>formatted</b>
+                             description of this <i>article</i>
+                            .</p>
                     </a>
                 </li>
                 <li>
@@ -577,6 +594,16 @@ struct MarkdownRenderer_PageElementsTests {
                 <li>
                     <a href="../../../SomeClass/index.html">
                         <code>class SomeClass</code>
+                        <p>Some <i>formatted</i>
+                             description of this class</p>
+                    </a>
+                </li>
+                <li>
+                    <a href="../../../SomeArticle/index.html">
+                        <p>Some Article</p>
+                        <p>Some <b>formatted</b>
+                             description of this <i>article</i>
+                            .</p>
                     </a>
                 </li>
                 <li>
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 18822d6d55..f30ec5a447 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -23,7 +23,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             TextFile(name: "SomeArticle.md", utf8Content: """
             # Some article
             
-            This is an article.
+            This is an _formatted_ article.
             
             ## Custom discussion
             
@@ -106,7 +106,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             TextFile(name: "ModuleName.md", utf8Content: """
             # ``ModuleName``
             
-            Some description of this module
+            Some **formatted** description of this module
             
             ## Topics
             
@@ -191,7 +191,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <link rel="icon" href="/favicon.ico" />
             <title>ModuleName</title>
             <script>var baseUrl = "/"</script>
-          <meta content="Some description of this module" name="description"/></head>
+          <meta content="Some formatted description of this module" name="description"/></head>
           <body>
             <noscript><main>
         <article>
@@ -205,7 +205,8 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     <p id="eyebrow">Framework</p>
                     <h1>Module<wbr/>
                         Name</h1>
-                    <p id="abstract">Some description of this module</p>
+                    <p id="abstract">Some <b>formatted</b>
+                         description of this module</p>
                 </section>
             </div>
             <section id="topics">
@@ -219,7 +220,10 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                      description of this topic section</p>
                 <ul>
                     <li>
-                        <a href="../SomeArticle/index.html">Some article<p>This is an article.</p>
+                        <a href="../SomeArticle/index.html">
+                            <p>Some article</p>
+                            <p>This is an <i>formatted</i>
+                                 article.</p>
                         </a>
                     </li>
                     <li>
@@ -396,7 +400,10 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 </h3>
                 <ul>
                     <li>
-                        <a href="../../../SomeArticle/index.html">Some article<p>This is an article.</p>
+                        <a href="../../../SomeArticle/index.html">
+                            <p>Some article</p>
+                            <p>This is an <i>formatted</i>
+                                 article.</p>
                         </a>
                     </li>
                 </ul>
@@ -415,7 +422,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <link rel="icon" href="/favicon.ico" />
             <title>Some article</title>
             <script>var baseUrl = "/"</script>
-          <meta content="This is an article." name="description"/></head>
+          <meta content="This is an formatted article." name="description"/></head>
           <body>
             <noscript><main>
         <article>
@@ -431,7 +438,8 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     </nav>
                     <p id="eyebrow">Article</p>
                     <h1>Some article</h1>
-                    <p id="abstract">This is an article.</p>
+                    <p id="abstract">This is an <i>formatted</i>
+                         article.</p>
                 </section>
             </div>
             <section id="custom-discussion">

From 4ac4a2788bf623a3b38b7304748f5374e3c1683e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 19:07:37 +0100
Subject: [PATCH 51/68] Use a minimal/concise version of the HTML content

---
 Sources/DocCHTML/MarkdownRenderer.swift       |  17 +-
 .../DocCHTML/MarkupRenderer+Declaration.swift |   2 +-
 Sources/DocCHTML/MarkupRenderer+Topics.swift  |   2 +-
 .../ConvertActionConverter.swift              |   2 +-
 .../Model/Rendering/HTML/HTMLRenderer.swift   |  32 +-
 .../MarkdownRenderer+PageElementsTests.swift  |   4 +-
 .../FileWritingHTMLContentConsumerTests.swift | 391 +++++++-----------
 7 files changed, 188 insertions(+), 262 deletions(-)

diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index 2fa619f16c..1da33b203c 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -153,6 +153,13 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
         return .text(html.rawHTML)
     }
     
+    package func wordBreak(symbolName: String) -> [XMLNode] {
+        switch goal {
+        case .quality:     RenderHelpers.wordBreak(symbolName: symbolName)
+        case .conciseness: [.text(symbolName)]
+        }
+    }
+    
     func visit(_ link: Link) -> XMLNode {
         guard let destination = link.destination.flatMap({ URL(string: $0) }) else {
             return .text("")
@@ -162,7 +169,7 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
             var customTitle = [XMLNode]()
             for child in link.inlineChildren {
                 if let code = child as? InlineCode {
-                    customTitle.append(.element(named: "code", children: RenderHelpers.wordBreak(symbolName: code.code)))
+                    customTitle.append(.element(named: "code", children: wordBreak(symbolName: code.code)))
                 } else {
                     customTitle.append(visit(child))
                 }
@@ -186,12 +193,12 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
                 case .single(let name):
                     switch name {
                         case .conceptual(let name): [ .text(name) ]
-                        case .symbol(let name):     [ .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name)) ]
+                        case .symbol(let name):     [ .element(named: "code", children: wordBreak(symbolName: name)) ]
                     }
                     
                 case .languageSpecificSymbol(let namesByLanguageID):
                     RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { language, name in
-                        .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(language.id)-only"])
+                        .element(named: "code", children: wordBreak(symbolName: name), attributes: ["class": "\(language.id)-only"])
                     }
             }
             
@@ -225,12 +232,12 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
             case .single(let name):
                 switch name {
                     case .conceptual(let name): [ .text(name) ]
-                    case .symbol(let name):     [ .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name)) ]
+                    case .symbol(let name):     [ .element(named: "code", children: wordBreak(symbolName: name)) ]
                 }
                 
             case .languageSpecificSymbol(let namesByLanguageID):
                 RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID).map { language, name in
-                    .element(named: "code", children: RenderHelpers.wordBreak(symbolName: name), attributes: ["class": "\(language.id)-only"])
+                    .element(named: "code", children: wordBreak(symbolName: name), attributes: ["class": "\(language.id)-only"])
                 }
         }
         
diff --git a/Sources/DocCHTML/MarkupRenderer+Declaration.swift b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
index 22116d9869..4762244e62 100644
--- a/Sources/DocCHTML/MarkupRenderer+Declaration.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
@@ -29,7 +29,7 @@ package extension MarkdownRenderer {
             let plainTextDeclaration: [XMLNode] = fragmentsByLanguage.first.map { _, fragments in
                 [.element(named: "code", children: [.text(fragments.map(\.spelling).joined())])]
             } ?? []
-            return .element(named: "pre", children: plainTextDeclaration, attributes: ["id": "declaration"])
+            return .element(named: "pre", children: plainTextDeclaration)
         }
         
         // Note: declarations scroll, so they don't need to word wrap within tokens
diff --git a/Sources/DocCHTML/MarkupRenderer+Topics.swift b/Sources/DocCHTML/MarkupRenderer+Topics.swift
index 70e008e55b..0273a0db8b 100644
--- a/Sources/DocCHTML/MarkupRenderer+Topics.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Topics.swift
@@ -125,7 +125,7 @@ package extension MarkdownRenderer {
             .element(
                 named: "code",
                 children: fragments.map {
-                    .element(named: "span", children: RenderHelpers.wordBreak(symbolName: $0.text), attributes: ["class": $0.kind.rawValue])
+                    .element(named: "span", children: wordBreak(symbolName: $0.text), attributes: ["class": $0.kind.rawValue])
                 },
                 attributes: languageFilter.map { ["class": "\($0.id)-only"] }
             )
diff --git a/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift b/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
index 096d7b5383..d82fcce906 100644
--- a/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
+++ b/Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift
@@ -115,7 +115,7 @@ package enum ConvertActionConverter {
                     let entity = try context.entity(with: identifier)
                     
                     if let htmlContentConsumer {
-                        var renderer = HTMLRenderer(reference: identifier, context: context, goal: .quality)
+                        var renderer = HTMLRenderer(reference: identifier, context: context, goal: .conciseness)
                         
                         if let symbol = entity.semantic as? Symbol {
                             let renderedPageInfo = renderer.renderSymbol(symbol)
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 3ecb785045..d58ba8bdfa 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -187,9 +187,14 @@ struct HTMLRenderer {
         main.addChild(articleElement)
         
         let hero = XMLElement(name: "section")
-        articleElement.addChild(
-            .element(named: "div", children: [hero], attributes: ["id": article.topics != nil ? "hero-api" : "hero-article"])
-        )
+        switch goal {
+        case .quality:
+            articleElement.addChild(
+                .element(named: "div", children: [hero], attributes: ["id": article.topics != nil ? "hero-api" : "hero-article"])
+            )
+        case .conciseness:
+            articleElement.addChild(hero)
+        }
         
         // Breadcrumbs and Eyebrow
         hero.addChild(renderer.breadcrumbs(
@@ -264,7 +269,7 @@ struct HTMLRenderer {
         // TODO: Add a way of determining the _automatic_ SeeAlso sections that doesn't query the JSON RenderContext for information.
         
         return RenderedPageInfo(
-            content: main,
+            content: goal == .quality ? main : articleElement,
             metadata: .init(
                 title: article.title?.plainText ?? node.name.plainText,
                 plainDescription: article.abstract?.plainText
@@ -282,7 +287,7 @@ struct HTMLRenderer {
         main.addChild(articleElement)
         
         let hero = XMLElement(name: "section")
-        if symbol.kind.identifier == .module {
+        if symbol.kind.identifier == .module, goal == .quality {
             articleElement.addChild(
                 .element(named: "div", children: [hero], attributes: ["id": "hero-module"])
             )
@@ -308,7 +313,11 @@ struct HTMLRenderer {
             references: (context.linkResolver.localResolver.breadcrumbs(of: reference, in: reference.sourceLanguage) ?? []).map { $0.url },
             currentPageNames: names
         ))
-        hero.addChild(.element(named: "p", children: [.text(symbol.roleHeading)], attributes: ["id": "eyebrow"]))
+        hero.addChild(.element(
+            named: "p",
+            children: [.text(symbol.roleHeading)],
+            attributes: goal == .quality ? ["id": "eyebrow"] : [:]
+        ))
         
         // Title
         let titleVariants = symbol.titleVariants.allValues.sorted(by: { $0.trait < $1.trait})
@@ -333,7 +342,7 @@ struct HTMLRenderer {
             hero.addChild(
                 .element(
                     named: "h1",
-                    children: RenderHelpers.wordBreak(symbolName: variant),
+                    children: renderer.wordBreak(symbolName: variant),
                     attributes: attributes
                 )
             )
@@ -342,10 +351,9 @@ struct HTMLRenderer {
         // Abstract
         if let abstract = symbol.abstract {
             let paragraph = renderer.visit(abstract) as! XMLElement
-            
-            paragraph.addAttribute(
-                XMLNode.attribute(withName: "id", stringValue: "abstract") as! XMLNode
-            )
+            if goal == .quality {
+                paragraph.addAttribute(XMLNode.attribute(withName: "id", stringValue: "abstract") as! XMLNode)
+            }
             hero.addChild(paragraph)
         }
         
@@ -487,7 +495,7 @@ struct HTMLRenderer {
         // TODO: Add a way of determining the _automatic_ SeeAlso sections that doesn't query the JSON RenderContext for information.
         
         return RenderedPageInfo(
-            content: main,
+            content: goal == .quality ? main : articleElement,
             metadata: .init(
                 title: symbol.title,
                 plainDescription: symbol.abstract?.plainText
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index c3c6db904c..7e37f322d5 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -300,7 +300,7 @@ struct MarkdownRenderer_PageElementsTests {
             """)
         case .conciseness:
             #expect(declaration.rendered(prettyFormatted: true) == """
-            <pre id="declaration">
+            <pre>
             <code>func doSomething(with first: FirstParameterValue, and second: SecondParameterValue) throws-&gt; ReturnValue</code>
             </pre>
             """)
@@ -449,7 +449,7 @@ struct MarkdownRenderer_PageElementsTests {
             
         case .conciseness:
             #expect(declaration.rendered(prettyFormatted: true) == """
-            <pre id="declaration">
+            <pre>
             <code>func doSomething(with first: FirstParameterValue, and second: SecondParameterValue) throws-&gt; ReturnValue</code>
             </pre>
             """)
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index f30ec5a447..fc1933d1bb 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -193,53 +193,38 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <script>var baseUrl = "/"</script>
           <meta content="Some formatted description of this module" name="description"/></head>
           <body>
-            <noscript><main>
-        <article>
-            <div id="hero-module">
-                <section>
-                    <nav id="breadcrumbs">
-                        <ul>
-                            <li>ModuleName</li>
-                        </ul>
-                    </nav>
-                    <p id="eyebrow">Framework</p>
-                    <h1>Module<wbr/>
-                        Name</h1>
-                    <p id="abstract">Some <b>formatted</b>
-                         description of this module</p>
-                </section>
-            </div>
-            <section id="topics">
-                <h2>
-                    <a href="#topics">Topics</a>
-                </h2>
-                <h3 id="something-custom">
-                    <a href="#something-custom">Something custom</a>
-                </h3>
-                <p>A custom <i>formatted</i>
-                     description of this topic section</p>
-                <ul>
-                    <li>
-                        <a href="../SomeArticle/index.html">
-                            <p>Some article</p>
-                            <p>This is an <i>formatted</i>
-                                 article.</p>
-                        </a>
-                    </li>
-                    <li>
-                        <a href="../SomeClass/index.html">
-                            <code>
-                                <span class="decorator">class </span>
-                                <span class="identifier">Some<wbr/>
-                                    Class</span>
-                            </code>
-                            <p>Some in-source description of this class.</p>
-                        </a>
-                    </li>
-                </ul>
-            </section>
-        </article>
-        </main></noscript>
+            <noscript><article>
+        <section>
+            <ul>
+                <li>ModuleName</li>
+            </ul>
+            <p>Framework</p>
+            <h1>ModuleName</h1>
+            <p>Some <b>formatted</b>
+                 description of this module</p>
+        </section>
+        <section>
+            <h2>Topics</h2>
+            <h3>Something custom</h3>
+            <p>A custom <i>formatted</i>
+                 description of this topic section</p>
+            <ul>
+                <li>
+                    <a href="../SomeArticle/index.html">
+                        <p>Some article</p>
+                        <p>This is an <i>formatted</i>
+                             article.</p>
+                    </a>
+                </li>
+                <li>
+                    <a href="../SomeClass/index.html">
+                        <code>class SomeClass</code>
+                        <p>Some in-source description of this class.</p>
+                    </a>
+                </li>
+            </ul>
+        </section>
+        </article></noscript>
             <div id="app"></div>
           </body>
         </html>
@@ -254,60 +239,34 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <script>var baseUrl = "/"</script>
           <meta content="Some in-source description of this class." name="description"/></head>
           <body>
-            <noscript><main>
-        <article>
-            <section>
-                <nav id="breadcrumbs">
-                    <ul>
-                        <li>
-                            <a href="../../index.html">ModuleName</a>
-                        </li>
-                        <li>SomeClass</li>
-                    </ul>
-                </nav>
-                <p id="eyebrow">Class</p>
-                <h1>Some<wbr/>
-                    Class</h1>
-                <p id="abstract">Some in-source description of this class.</p>
-                <pre id="declaration">
-                    <code>
-                        <span class="token-keyword">class</span>
-                         <span class="token-identifier">SomeClass</span>
-                    </code>
-                </pre>
-            </section>
-            <hr/>
-            <section id="topics">
-                <h2>
-                    <a href="#topics">Topics</a>
-                </h2>
-                <h3 id="instance-methods">
-                    <a href="#instance-methods">Instance Methods</a>
-                </h3>
-                <ul>
-                    <li>
-                        <a href="../someMethod(with:and:)/index.html">
-                            <code>
-                                <span class="decorator">func </span>
-                                <span class="identifier">some<wbr/>
-                                    Method</span>
-                                <span class="decorator">(</span>
-                                <span class="identifier">with</span>
-                                <span class="decorator"> first:<wbr/>
-                                     Int, </span>
-                                <span class="identifier">and</span>
-                                <span class="decorator"> second:<wbr/>
-                                     String)<wbr/>
-                                     -&gt;<wbr/>
-                                     Bool</span>
-                            </code>
-                            <p>Some in-source description of this method.</p>
-                        </a>
-                    </li>
-                </ul>
-            </section>
-        </article>
-        </main></noscript>
+            <noscript><article>
+        <section>
+            <ul>
+                <li>
+                    <a href="../../index.html">ModuleName</a>
+                </li>
+                <li>SomeClass</li>
+            </ul>
+            <p>Class</p>
+            <h1>SomeClass</h1>
+            <p>Some in-source description of this class.</p>
+            <pre>
+                <code>class SomeClass</code>
+            </pre>
+        </section>
+        <section>
+            <h2>Topics</h2>
+            <h3>Instance Methods</h3>
+            <ul>
+                <li>
+                    <a href="../someMethod(with:and:)/index.html">
+                        <code>func someMethod(with first: Int, and second: String) -&gt; Bool</code>
+                        <p>Some in-source description of this method.</p>
+                    </a>
+                </li>
+            </ul>
+        </section>
+        </article></noscript>
             <div id="app"></div>
           </body>
         </html>
@@ -322,94 +281,65 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <script>var baseUrl = "/"</script>
           <meta content="Some in-source description of this method." name="description"/></head>
           <body>
-            <noscript><main>
-        <article>
-            <section>
-                <nav id="breadcrumbs">
-                    <ul>
-                        <li>
-                            <a href="../../../index.html">ModuleName</a>
-                        </li>
-                        <li>
-                            <a href="../../index.html">SomeClass</a>
-                        </li>
-                        <li>someMethod(with:and:)</li>
-                    </ul>
-                </nav>
-                <p id="eyebrow">Instance Method</p>
-                <h1>some<wbr/>
-                    Method(<wbr/>
-                    with:<wbr/>
-                    and:)</h1>
-                <p id="abstract">Some in-source description of this method.</p>
-                <pre id="declaration">
-                    <code>
-                        <span class="token-keyword">func</span>
-                         <span class="token-identifier">someMethod</span>
-                        (<span class="token-externalParam">with</span>
-                         <span class="token-internalParam">first</span>
-                        : <span class="token-typeIdentifier">Int</span>
-                        , <span class="token-externalParam">and</span>
-                         <span class="token-internalParam">second</span>
-                        : <span class="token-typeIdentifier">String</span>
-                        ) -&gt; <span class="token-typeIdentifier">Bool</span>
-                    </code>
-                </pre>
-            </section>
-            <section id="parameters">
-                <h2>
-                    <a href="#parameters">Parameters</a>
-                </h2>
-                <dl>
-                    <dt>
-                        <code>first</code>
-                    </dt>
-                    <dd>
-                        <p>Description of the <code>first</code>
-                             parameter.</p>
-                    </dd>
-                    <dt>
-                        <code>second</code>
-                    </dt>
-                    <dd>
-                        <p>Description of the <code>second</code>
-                             parameter.</p>
-                    </dd>
-                </dl>
-            </section>
-            <section id="return-value">
-                <h2>
-                    <a href="#return-value">Return Value</a>
-                </h2>
-                <p>Description of the return value.</p>
-            </section>
-            <hr/>
-            <section id="discussion">
-                <h2>
-                    <a href="#discussion">Discussion</a>
-                </h2>
-                <p>Further description of this method and how to use it.</p>
-            </section>
-            <hr/>
-            <section id="see-also">
-                <h2>
-                    <a href="#see-also">See Also</a>
-                </h2>
-                <h3 id="related-documentation">
-                    <a href="#related-documentation">Related Documentation</a>
-                </h3>
-                <ul>
-                    <li>
-                        <a href="../../../SomeArticle/index.html">
-                            <p>Some article</p>
-                            <p>This is an <i>formatted</i>
-                                 article.</p>
-                        </a>
-                    </li>
-                </ul>
-            </section>
-        </article>
-        </main></noscript>
+            <noscript><article>
+        <section>
+            <ul>
+                <li>
+                    <a href="../../../index.html">ModuleName</a>
+                </li>
+                <li>
+                    <a href="../../index.html">SomeClass</a>
+                </li>
+                <li>someMethod(with:and:)</li>
+            </ul>
+            <p>Instance Method</p>
+            <h1>someMethod(with:and:)</h1>
+            <p>Some in-source description of this method.</p>
+            <pre>
+                <code>func someMethod(with first: Int, and second: String) -&gt; Bool</code>
+            </pre>
+        </section>
+        <section>
+            <h2>Parameters</h2>
+            <dl>
+                <dt>
+                    <code>first</code>
+                </dt>
+                <dd>
+                    <p>Description of the <code>first</code>
+                         parameter.</p>
+                </dd>
+                <dt>
+                    <code>second</code>
+                </dt>
+                <dd>
+                    <p>Description of the <code>second</code>
+                         parameter.</p>
+                </dd>
+            </dl>
+        </section>
+        <section>
+            <h2>Return Value</h2>
+            <p>Description of the return value.</p>
+        </section>
+        <section>
+            <h2>Discussion</h2>
+            <p>Further description of this method and how to use it.</p>
+        </section>
+        <section>
+            <h2>See Also</h2>
+            <h3>Related Documentation</h3>
+            <ul>
+                <li>
+                    <a href="../../../SomeArticle/index.html">
+                        <p>Some article</p>
+                        <p>This is an <i>formatted</i>
+                             article.</p>
+                    </a>
+                </li>
+            </ul>
+        </section>
+        </article></noscript>
             <div id="app"></div>
           </body>
         </html>
@@ -424,57 +354,38 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <script>var baseUrl = "/"</script>
           <meta content="This is an formatted article." name="description"/></head>
           <body>
-            <noscript><main>
-        <article>
-            <div id="hero-article">
-                <section>
-                    <nav id="breadcrumbs">
-                        <ul>
-                            <li>
-                                <a href="../../index.html">ModuleName</a>
-                            </li>
-                            <li>Some article</li>
-                        </ul>
-                    </nav>
-                    <p id="eyebrow">Article</p>
-                    <h1>Some article</h1>
-                    <p id="abstract">This is an <i>formatted</i>
-                         article.</p>
-                </section>
-            </div>
-            <section id="custom-discussion">
-                <h2>
-                    <a href="#custom-discussion">Custom discussion</a>
-                </h2>
-                <p>It explains how a developer can perform some task using this module.</p>
-                <h3 id="details">
-                    <a href="#details">Details</a>
-                </h3>
-                <p>This subsection describes something more detailed.</p>
-            </section>
-            <hr/>
-            <section id="see-also">
-                <h2>
-                    <a href="#see-also">See Also</a>
-                </h2>
-                <h3 id="related-documentation">
-                    <a href="#related-documentation">Related Documentation</a>
-                </h3>
-                <ul>
-                    <li>
-                        <a href="../../SomeClass/index.html">
-                            <code>
-                                <span class="decorator">class </span>
-                                <span class="identifier">Some<wbr/>
-                                    Class</span>
-                            </code>
-                            <p>Some in-source description of this class.</p>
-                        </a>
-                    </li>
-                </ul>
-            </section>
-        </article>
-        </main></noscript>
+            <noscript><article>
+        <section>
+            <ul>
+                <li>
+                    <a href="../../index.html">ModuleName</a>
+                </li>
+                <li>Some article</li>
+            </ul>
+            <p id="eyebrow">Article</p>
+            <h1>Some article</h1>
+            <p id="abstract">This is an <i>formatted</i>
+                 article.</p>
+        </section>
+        <section>
+            <h2>Custom discussion</h2>
+            <p>It explains how a developer can perform some task using this module.</p>
+            <h3>Details</h3>
+            <p>This subsection describes something more detailed.</p>
+        </section>
+        <section>
+            <h2>See Also</h2>
+            <h3>Related Documentation</h3>
+            <ul>
+                <li>
+                    <a href="../../SomeClass/index.html">
+                        <code>class SomeClass</code>
+                        <p>Some in-source description of this class.</p>
+                    </a>
+                </li>
+            </ul>
+        </section>
+        </article></noscript>
             <div id="app"></div>
           </body>
         </html>

From 893917e3bdff8c680073cebb5239ee14db8d26bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 27 Nov 2025 19:08:44 +0100
Subject: [PATCH 52/68] Rename 'RenderGoal.quality' to 'RenderGoal.richness'

---
 Sources/DocCHTML/MarkdownRenderer.swift       |  8 +++----
 .../MarkupRenderer+Availability.swift         |  2 +-
 .../DocCHTML/MarkupRenderer+Breadcrumbs.swift |  4 ++--
 .../DocCHTML/MarkupRenderer+Declaration.swift |  2 +-
 Sources/DocCHTML/MarkupRenderer+Returns.swift |  2 +-
 Sources/DocCHTML/MarkupRenderer+Topics.swift  |  4 ++--
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 16 +++++++-------
 .../MarkdownRenderer+PageElementsTests.swift  | 22 +++++++++----------
 .../DocCHTMLTests/MarkdownRendererTests.swift |  2 +-
 9 files changed, 31 insertions(+), 31 deletions(-)

diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index 1da33b203c..08d57a1170 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -13,10 +13,10 @@ package import Markdown
 
 /// The primary goal for the rendered HTML output.
 package enum RenderGoal {
-    /// The rendered output should prioritize quality, optimizing for human consumption.
+    /// The rendered output should prioritize richness, optimizing for human consumption.
     ///
     /// The rendered output might include explicit work-breaks, syntax highlighted code, etc.
-    case quality
+    case richness
     /// The minimalistic rendered output should prioritize conciseness, optimizing for consumption by machines such as SEO indexers or LLMs.
     case conciseness
 }
@@ -68,7 +68,7 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
         case .conciseness:
             return .element(named: "h\(level)", children: content)
             
-        case .quality:
+        case .richness:
             let id = urlReadableFragment(plainTextTitle().lowercased())
             return .element(
                 named: "h\(level)",
@@ -155,7 +155,7 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
     
     package func wordBreak(symbolName: String) -> [XMLNode] {
         switch goal {
-        case .quality:     RenderHelpers.wordBreak(symbolName: symbolName)
+        case .richness:     RenderHelpers.wordBreak(symbolName: symbolName)
         case .conciseness: [.text(symbolName)]
         }
     }
diff --git a/Sources/DocCHTML/MarkupRenderer+Availability.swift b/Sources/DocCHTML/MarkupRenderer+Availability.swift
index 90d6b85c2f..e70439cdcb 100644
--- a/Sources/DocCHTML/MarkupRenderer+Availability.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Availability.swift
@@ -57,7 +57,7 @@ package extension MarkdownRenderer {
                 attributes["class"] = "deprecated"
             }
             
-            return .element(named: "li", children: [.text(text)], attributes: goal == .quality ? attributes : [:])
+            return .element(named: "li", children: [.text(text)], attributes: goal == .richness ? attributes : [:])
         }
         
         return .element(
diff --git a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
index 4141be0441..9c14df034b 100644
--- a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
@@ -27,7 +27,7 @@ package extension MarkdownRenderer {
             case .languageSpecificSymbol(let namesByLanguageID):
                 let names = RenderHelpers.sortedLanguageSpecificValues(namesByLanguageID)
                 return switch goal {
-                case .quality:
+                case .richness:
                     if names.count == 1 {
                         [.text(names.first!.value)]
                     } else {
@@ -63,7 +63,7 @@ package extension MarkdownRenderer {
         return switch goal {
         case .conciseness:
             list
-        case .quality:
+        case .richness:
             .element(named: "nav", children: [list], attributes: ["id": "breadcrumbs"])
         }
     }
diff --git a/Sources/DocCHTML/MarkupRenderer+Declaration.swift b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
index 4762244e62..d42d645e36 100644
--- a/Sources/DocCHTML/MarkupRenderer+Declaration.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
@@ -24,7 +24,7 @@ package extension MarkdownRenderer {
     func declaration(_ fragmentsByLanguage: [SourceLanguage: [DeclarationFragment]]) -> XMLElement {
         let fragmentsByLanguage = RenderHelpers.sortedLanguageSpecificValues(fragmentsByLanguage)
         
-        guard goal == .quality else {
+        guard goal == .richness else {
             // If the goal is conciseness, display only the primary language's plain text declaration in a <code> block
             let plainTextDeclaration: [XMLNode] = fragmentsByLanguage.first.map { _, fragments in
                 [.element(named: "code", children: [.text(fragments.map(\.spelling).joined())])]
diff --git a/Sources/DocCHTML/MarkupRenderer+Returns.swift b/Sources/DocCHTML/MarkupRenderer+Returns.swift
index 68937231e6..131c94666b 100644
--- a/Sources/DocCHTML/MarkupRenderer+Returns.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Returns.swift
@@ -48,7 +48,7 @@ package extension MarkdownRenderer {
         let sectionAttributes: [String: String]
         
         switch goal {
-        case .quality:
+        case .richness:
             let id = urlReadableFragment(sectionName.lowercased())
             headingContent = .element(named: "a", children: [.text(sectionName)], attributes: ["href": "#\(id)"])
             sectionAttributes = ["id": id]
diff --git a/Sources/DocCHTML/MarkupRenderer+Topics.swift b/Sources/DocCHTML/MarkupRenderer+Topics.swift
index 0273a0db8b..6c274298a3 100644
--- a/Sources/DocCHTML/MarkupRenderer+Topics.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Topics.swift
@@ -91,7 +91,7 @@ package extension MarkdownRenderer {
             items = switch goal {
             case .conciseness:
                 [ .element(named: "code", children: [.text(fragments.map(\.text).joined())]) ]
-            case .quality:
+            case .richness:
                 [ _symbolSubheading(fragments, languageFilter: nil) ]
             }
             break
@@ -121,7 +121,7 @@ package extension MarkdownRenderer {
     
     private func _symbolSubheading(_ fragments: [LinkedElement.SymbolNameFragment], languageFilter: SourceLanguage?) -> XMLElement {
         switch goal {
-        case .quality:
+        case .richness:
             .element(
                 named: "code",
                 children: fragments.map {
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index d58ba8bdfa..92dc0adb91 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -188,7 +188,7 @@ struct HTMLRenderer {
         
         let hero = XMLElement(name: "section")
         switch goal {
-        case .quality:
+        case .richness:
             articleElement.addChild(
                 .element(named: "div", children: [hero], attributes: ["id": article.topics != nil ? "hero-api" : "hero-article"])
             )
@@ -228,7 +228,7 @@ struct HTMLRenderer {
         }
         
         func separateCurationIfNeeded() {
-            guard goal == .quality, ((articleElement.children ?? []).last as? XMLElement)?.name == "section" else {
+            guard goal == .richness, ((articleElement.children ?? []).last as? XMLElement)?.name == "section" else {
                 return
             }
             
@@ -269,7 +269,7 @@ struct HTMLRenderer {
         // TODO: Add a way of determining the _automatic_ SeeAlso sections that doesn't query the JSON RenderContext for information.
         
         return RenderedPageInfo(
-            content: goal == .quality ? main : articleElement,
+            content: goal == .richness ? main : articleElement,
             metadata: .init(
                 title: article.title?.plainText ?? node.name.plainText,
                 plainDescription: article.abstract?.plainText
@@ -287,7 +287,7 @@ struct HTMLRenderer {
         main.addChild(articleElement)
         
         let hero = XMLElement(name: "section")
-        if symbol.kind.identifier == .module, goal == .quality {
+        if symbol.kind.identifier == .module, goal == .richness {
             articleElement.addChild(
                 .element(named: "div", children: [hero], attributes: ["id": "hero-module"])
             )
@@ -316,7 +316,7 @@ struct HTMLRenderer {
         hero.addChild(.element(
             named: "p",
             children: [.text(symbol.roleHeading)],
-            attributes: goal == .quality ? ["id": "eyebrow"] : [:]
+            attributes: goal == .richness ? ["id": "eyebrow"] : [:]
         ))
         
         // Title
@@ -351,7 +351,7 @@ struct HTMLRenderer {
         // Abstract
         if let abstract = symbol.abstract {
             let paragraph = renderer.visit(abstract) as! XMLElement
-            if goal == .quality {
+            if goal == .richness {
                 paragraph.addAttribute(XMLNode.attribute(withName: "id", stringValue: "abstract") as! XMLNode)
             }
             hero.addChild(paragraph)
@@ -439,7 +439,7 @@ struct HTMLRenderer {
         }
         
         func separateCurationIfNeeded() {
-            guard goal == .quality, ((articleElement.children ?? []).last as? XMLElement)?.name == "section" else {
+            guard goal == .richness, ((articleElement.children ?? []).last as? XMLElement)?.name == "section" else {
                 return
             }
             
@@ -495,7 +495,7 @@ struct HTMLRenderer {
         // TODO: Add a way of determining the _automatic_ SeeAlso sections that doesn't query the JSON RenderContext for information.
         
         return RenderedPageInfo(
-            content: goal == .quality ? main : articleElement,
+            content: goal == .richness ? main : articleElement,
             metadata: .init(
                 title: symbol.title,
                 plainDescription: symbol.abstract?.plainText
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index 7e37f322d5..263e1b8470 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -45,7 +45,7 @@ struct MarkdownRenderer_PageElementsTests {
         ]
         let breadcrumbs = makeRenderer(goal: goal, elementsToReturn: elements).breadcrumbs(references: elements.map { $0.path }, currentPageNames: .single(.conceptual("ThisPage")))
         switch goal {
-        case .quality:
+        case .richness:
             #expect(breadcrumbs.rendered(prettyFormatted: true) == """
             <nav id="breadcrumbs">
             <ul>
@@ -85,7 +85,7 @@ struct MarkdownRenderer_PageElementsTests {
             .init(name: "Third",  introduced: "4.5",                    isBeta: true),
         ])
         switch goal {
-        case .quality:
+        case .richness:
             #expect(availability.rendered(prettyFormatted: true) == """
             <ul id="availability">
             <li aria-label="First 1.2–3.4, Introduced in First 1.2 and deprecated in First 3.4" class="deprecated" role="text" title="Introduced in First 1.2 and deprecated in First 3.4">First 1.2–3.4</li>
@@ -117,7 +117,7 @@ struct MarkdownRenderer_PageElementsTests {
             ]
         ])
         let expectedHTMLStart = switch goal {
-        case .quality: """
+        case .richness: """
             <section id="parameters">
             <h2>
                 <a href="#parameters">Parameters</a>
@@ -156,7 +156,7 @@ struct MarkdownRenderer_PageElementsTests {
     
     @Test
     func testRenderLanguageSpecificParameters() {
-        let parameters = makeRenderer(goal: .quality).parameters([
+        let parameters = makeRenderer(goal: .richness).parameters([
             .swift: [
                 .init(name: "FirstCommon", content: parseMarkup(string: "Available in both languages")),
                 .init(name: "SwiftOnly", content: parseMarkup(string: "Only available in Swift")),
@@ -205,7 +205,7 @@ struct MarkdownRenderer_PageElementsTests {
     
     @Test
     func testRenderManyLanguageSpecificParameters() {
-        let parameters = makeRenderer(goal: .quality).parameters([
+        let parameters = makeRenderer(goal: .richness).parameters([
             .swift: [
                 .init(name: "First", content: parseMarkup(string: "Some description")),
             ],
@@ -281,7 +281,7 @@ struct MarkdownRenderer_PageElementsTests {
             ]
         ])
         switch goal {
-        case .quality:
+        case .richness:
             #expect(declaration.rendered(prettyFormatted: true) == """
             <pre id="declaration">
             <code>
@@ -313,7 +313,7 @@ struct MarkdownRenderer_PageElementsTests {
             .swift: parseMarkup(string: "First paragraph\n\nSecond paragraph")
         ])
         let expectedHTMLStart = switch goal {
-        case .quality: """
+        case .richness: """
             <section id="return-value">
             <h2>
                 <a href="#return-value">Return Value</a>
@@ -340,7 +340,7 @@ struct MarkdownRenderer_PageElementsTests {
             .objectiveC: parseMarkup(string: "Other language's paragraph"),
         ])
         let expectedHTMLStart = switch goal {
-        case .quality: """
+        case .richness: """
             <section id="return-value">
             <h2>
                 <a href="#return-value">Return Value</a>
@@ -418,7 +418,7 @@ struct MarkdownRenderer_PageElementsTests {
             ]
         ])
         switch goal {
-        case .quality:
+        case .richness:
             #expect(declaration.rendered(prettyFormatted: true) == """
             <pre id="declaration">
             <code class="swift-only">
@@ -521,7 +521,7 @@ struct MarkdownRenderer_PageElementsTests {
         ])
         
         switch goal {
-        case .quality:
+        case .richness:
             #expect(groupedSection.rendered(prettyFormatted: true) == """
             <section id="\(expectedSectionID)">
             <h2>
@@ -681,6 +681,6 @@ struct MultiValueLinkProvider: LinkProvider {
 
 extension RenderGoal: CaseIterable {
     package static var allCases: [RenderGoal] {
-        [.quality, .conciseness]
+        [.richness, .conciseness]
     }
 }
diff --git a/Tests/DocCHTMLTests/MarkdownRendererTests.swift b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
index e0cd5538f7..f9d9551522 100644
--- a/Tests/DocCHTMLTests/MarkdownRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
@@ -558,7 +558,7 @@ struct MarkdownRendererTests {
     ) {
         let renderer = MarkdownRenderer(
             path: URL(string: "/documentation/Something/ThisPage/index.html")!,
-            goal: .quality,
+            goal: .richness,
             linkProvider: SingleValueLinkProvider(
                 elementToReturn: elementToReturn,
                 assetToReturn: assetToReturn,

From f4bbc8e1018a9fe046747193a1a27e82bfb8f21a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 28 Nov 2025 10:56:13 +0100
Subject: [PATCH 53/68] Remove unused code and unused parameters

---
 Sources/DocCHTML/MarkdownRenderer.swift       |  21 +--
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 140 +-----------------
 .../FileWritingHTMLContentConsumer.swift      |   3 -
 3 files changed, 11 insertions(+), 153 deletions(-)

diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index 08d57a1170..6d94fd6102 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -102,15 +102,15 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
         .text(text.string)
     }
     
-    func visit(_ lineBreak: LineBreak) -> XMLNode {
+    func visit(_: LineBreak) -> XMLNode {
         .element(named: "br")
     }
     
-    func visit(_ softBreak: SoftBreak) -> XMLNode {
+    func visit(_: SoftBreak) -> XMLNode {
         .text(" ") // A soft line break doesn't actually break the content
     }
     
-    func visit(_ thematicBreak: ThematicBreak) -> XMLNode {
+    func visit(_: ThematicBreak) -> XMLNode {
         .element(named: "hr")
     }
     
@@ -482,8 +482,8 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
     
     // MARK: Directives
     
-    func visit(_ blockDirective: BlockDirective) -> XMLNode {
-        .text("") // Do nothing for now
+    func visit(_: BlockDirective) -> XMLNode {
+        .text("") // TODO: Render the block directives that can appear in the content.
     }
     
     // FIXME: It would be nice if DocC processed these before rendering
@@ -594,14 +594,3 @@ private extension Image {
         return firstText.string
     }
 }
-
-private extension URL {
-    /// Returns a copy of the URL without the scheme, host, and port components.
-    func withoutHostAndPortAndScheme() -> URL {
-        var components = URLComponents(url: self, resolvingAgainstBaseURL: false)!
-        components.scheme = nil
-        components.host = nil
-        components.port = nil
-        return components.url!
-    }
-}
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 92dc0adb91..5b34264f10 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -149,25 +149,17 @@ struct HTMLRenderer {
     let context: DocumentationContext
     let goal: RenderGoal
     
-    private let linkProvider: ContextLinkProvider
-    private let filePath: URL
-    
     private let renderer: MarkdownRenderer<ContextLinkProvider>
     
     init(reference: ResolvedTopicReference, context: DocumentationContext, goal: RenderGoal) {
         self.reference = reference
         self.context = context
         self.goal = goal
-        let linkProvider = ContextLinkProvider(reference: reference, context: context)
-        self.linkProvider = linkProvider
-        let filePath = ContextLinkProvider.filePath(for: reference)
-        self.filePath = filePath
-        self.renderer = MarkdownRenderer(path: filePath, goal: goal, linkProvider: linkProvider)
-    }
-    
-    private func path(to destination: ResolvedTopicReference) -> String {
-        (destination.url.relative(to: reference.url)?.path
-            ?? destination.path) + "/index.html"
+        self.renderer = MarkdownRenderer(
+            path: ContextLinkProvider.filePath(for: reference),
+            goal: goal,
+            linkProvider: ContextLinkProvider(reference: reference, context: context)
+        )
     }
     
     struct RenderedPageInfo {
@@ -517,127 +509,7 @@ struct HTMLRenderer {
         return renderer.selfReferencingSection(named: title, content: remaining.map { renderer.visit($0) })
     }
     
-    // FIXME: There's currently nothing calling this. Instead, the 2 `render...` methods return a `RenderedPageInfo` value.
-    private func makePage(main: XMLNode, title: String, plainDescription: String?) -> XMLNode {
-        let head = XMLElement(name: "head")
-        head.setChildren([
-            // <meta charset="utf-8">
-            .element(named: "meta", attributes: ["charset": "utf-8"]),
-            
-            // <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
-            .metaElement(name: "viewport", content: "width=device-width,initial-scale=1,viewport-fit=cover"),
-            
-            // <link rel="icon" href="/favicon.ico">
-            .element(named: "link", attributes: [
-                "rel": "icon",
-                "href": "/favicon.ico", // ???: Should this be relative to the page?
-            ]),
-            
-            // <link rel="mask-icon" href="/apple-logo.svg" color="#333333">
-            .element(named: "link", attributes: [
-                "rel": "mask-icon",
-                "href": "/apple-logo.svg", // ???: Should this be relative to the page?
-                "color": "#333333",
-            ]),
-            
-            .element(named: "title", children: [
-                .text(title)
-            ]),
-            
-            // <link rel="stylesheet" href="styles.css" />
-            .element(named: "link", attributes: [
-                "rel": "stylesheet",
-                "href": String(repeating: "../", count: reference.url.pathComponents.count - 1) + "styles.css"
-            ]),
-            
-            .element(named: "script", attributes: [
-                "type": "text/javascript",
-                "src": String(repeating: "../", count: reference.url.pathComponents.count - 1) + "reference.js"
-            ]),
-            
-            // FIXME: Include OpenGraph metadata
-        ])
-        if let abstract = plainDescription {
-            head.addChild(
-                .metaElement(name: "description", content: abstract)
-            )
-        }
-        
-        // FIXME: Add the page header here
-        let header = XMLNode.element(
-            named: "header",
-            children: [
-                .element(named: "button", attributes: ["id": "sidebar-toggle", "onclick": "toggleSidebar()"]),
-                
-                .element(
-                    named: "span",
-                    children: [.text("Documentation")],
-                    attributes: ["id": "header-title"]
-                ),
-                
-                .element(named: "div", children: [
-                    .element(named: "label", children: [.text("Language: ")], attributes: ["for": "language-toggle"]),
-                    
-                    .element(
-                        named: "select",
-                        children: [
-                            .element(named: "option", children: [.text("Swift")], attributes: ["value": "swift"]),
-                            .element(named: "option", children: [.text("Objective-C")], attributes: ["value": "occ"]),
-                        ],
-                        attributes: ["id": "language-toggle", "onchange": "languageChanged()"]
-                    ),
-                ])
-            ]
-        )
-        
-        // Wrap up the page
-        let document = XMLDocument(rootElement: .element(
-            named: "html",
-            children: [
-                head,
-                .element(named: "body", children: [
-                    header,
-                    main // Passes as an argument
-                ])
-            ],
-            attributes: ["lang": "en-US"]
-        ))
-        document.documentContentKind = .xhtml
-        
-        let docTypeDefinition = XMLDTD()
-        docTypeDefinition.publicID = "-//W3C//DTD XHTML 1.0 Strict//EN"
-        docTypeDefinition.systemID = "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
-        docTypeDefinition.name = "html"
-        document.dtd = docTypeDefinition
-        
-        return document
-    }
-    
-}
-
-extension XMLNode {
-    static func metaElement(name: String, content: String) -> XMLElement {
-        .element(named: "meta", attributes: ["name": name, "content": content])
-    }
-    
-    static func metaElement(property: String, content: String) -> XMLElement {
-        .element(named: "meta", attributes: ["property": property, "content": content])
-    }
-    
-    static func selfReferencingHeader(level: Int = 2, title: String) -> XMLElement {
-        let id = urlReadableFragment(title)
-        return .element(
-            named: "h\(level)",
-            children: [
-                .element(
-                    named: "a",
-                    children: [.text(title)],
-                    attributes: ["href": "#\(id)"]
-                )
-            ],
-            attributes: ["id": id]
-        )
-    }
+    // TODO: As a future direction, build another layer on top of this that creates a full HTML page from scratch.
 }
 
 // Note; this isn't a Comparable conformance because I wanted it to be private to this file.
diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
index a08f5f050d..4d394775ea 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
@@ -14,7 +14,6 @@ import DocCHTML
 
 struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
     var targetFolder: URL
-    var bundleRootFolder: URL?
     var fileManager: any FileManagerProtocol
     var prettyPrintOutput: Bool
     
@@ -65,13 +64,11 @@ struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
     
     init(
         targetFolder: URL,
-        bundleRootFolder: URL? = nil,
         fileManager: some FileManagerProtocol,
         htmlTemplate: URL,
         prettyPrintOutput: Bool = shouldPrettyPrintOutputJSON
     ) throws {
         self.targetFolder = targetFolder
-        self.bundleRootFolder = bundleRootFolder
         self.fileManager = fileManager
         self.htmlTemplate = try HTMLTemplate(data: fileManager.contents(of: htmlTemplate))
         self.prettyPrintOutput = prettyPrintOutput

From 815e88ca5018359e132a6fb0a2d89b6289c861a5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 28 Nov 2025 11:12:31 +0100
Subject: [PATCH 54/68] Don't count the "index.html" component when determining
 a relative path

---
 Sources/DocCHTML/MarkdownRenderer.swift       |  7 ++--
 .../MarkdownRenderer+PageElementsTests.swift  | 40 +++++++++----------
 .../DocCHTMLTests/MarkdownRendererTests.swift | 22 +++++-----
 .../FileWritingHTMLContentConsumerTests.swift | 18 ++++-----
 4 files changed, 44 insertions(+), 43 deletions(-)

diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index 6d94fd6102..a972e68e8b 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -252,15 +252,16 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
         let from = path
         let to   = other
         
-        guard from != to else { return to.withoutHostAndPortAndScheme().absoluteString }
+        guard from != to else { return "." }
 
         // To be able to compare the components of the two URLs they both need to be absolute and standardized.
         let fromComponents = from.absoluteURL.standardizedFileURL.pathComponents
-        let toComponents   = to.absoluteURL.standardizedFileURL.pathComponents
+        let toComponents   =   to.absoluteURL.standardizedFileURL.pathComponents
 
         let commonPrefixLength = Array(zip(fromComponents, toComponents).prefix { lhs, rhs in lhs == rhs }).count
 
-        let relativeComponents = repeatElement("..", count: fromComponents.count - commonPrefixLength) + toComponents.dropFirst(commonPrefixLength)
+        let relativeComponents = repeatElement("..", count: fromComponents.count - commonPrefixLength - 1 /* the "index.html" component doesn't count in a web server */)
+            + toComponents.dropFirst(commonPrefixLength)
        
         return relativeComponents.joined(separator: "/")
     }
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index 263e1b8470..81cf8d23f0 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -50,10 +50,10 @@ struct MarkdownRenderer_PageElementsTests {
             <nav id="breadcrumbs">
             <ul>
                 <li>
-                    <a href="../../../index.html">ModuleName</a>
+                    <a href="../../index.html">ModuleName</a>
                 </li>
                 <li>
-                    <a href="../../index.html">
+                    <a href="../index.html">
                         <span class="swift-only">Something</span>
                         <span class="occ-only">TLASomething</span>
                     </a>
@@ -66,10 +66,10 @@ struct MarkdownRenderer_PageElementsTests {
             #expect(breadcrumbs.rendered(prettyFormatted: true) == """
             <ul>
             <li>
-                <a href="../../../index.html">ModuleName</a>
+                <a href="../../index.html">ModuleName</a>
             </li>
             <li>
-                <a href="../../index.html">Something</a>
+                <a href="../index.html">Something</a>
             </li>
             <li>ThisPage</li>
             </ul>
@@ -289,12 +289,12 @@ struct MarkdownRenderer_PageElementsTests {
                  <span class="token-identifier">doSomething</span>
                 (<span class="token-externalParam">with</span>
                  <span class="token-internalParam">first</span>
-                : <a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
+                : <a class="token-typeIdentifier" href="../../FirstParameterValue/index.html">FirstParameterValue</a>
                 , <span class="token-externalParam">and</span>
                  <span class="token-internalParam">second</span>
-                : <a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
+                : <a class="token-typeIdentifier" href="../../SecondParameterValue/index.html">SecondParameterValue</a>
                 ) <span class="token-keyword">throws</span>
-                -&gt; <a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
+                -&gt; <a class="token-typeIdentifier" href="../../ReturnValue/index.html">ReturnValue</a>
             </code>
             </pre>
             """)
@@ -426,22 +426,22 @@ struct MarkdownRenderer_PageElementsTests {
                  <span class="token-identifier">doSomething</span>
                 (<span class="token-externalParam">with</span>
                  <span class="token-internalParam">first</span>
-                : <a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
+                : <a class="token-typeIdentifier" href="../../FirstParameterValue/index.html">FirstParameterValue</a>
                 , <span class="token-externalParam">and</span>
                  <span class="token-internalParam">second</span>
-                : <a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
+                : <a class="token-typeIdentifier" href="../../SecondParameterValue/index.html">SecondParameterValue</a>
                 ) <span class="token-keyword">throws</span>
-                -&gt; <a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
+                -&gt; <a class="token-typeIdentifier" href="../../ReturnValue/index.html">ReturnValue</a>
             </code>
-            <code class="occ-only">- (<a class="token-typeIdentifier" href="../../../ReturnValue/index.html">ReturnValue</a>
+            <code class="occ-only">- (<a class="token-typeIdentifier" href="../../ReturnValue/index.html">ReturnValue</a>
                 ) <span class="token-identifier">doSomethingWithFirst</span>
-                : (<a class="token-typeIdentifier" href="../../../FirstParameterValue/index.html">FirstParameterValue</a>
+                : (<a class="token-typeIdentifier" href="../../FirstParameterValue/index.html">FirstParameterValue</a>
                 ) <span class="token-internalParam">first</span>
                  <span class="token-identifier">andSecond</span>
-                : (<a class="token-typeIdentifier" href="../../../SecondParameterValue/index.html">SecondParameterValue</a>
+                : (<a class="token-typeIdentifier" href="../../SecondParameterValue/index.html">SecondParameterValue</a>
                 ) <span class="token-internalParam">second</span>
                  <span class="token-identifier">error</span>
-                : (<a class="token-typeIdentifier" href="../../../../Foundation/NSError/index.html">NSError</a>
+                : (<a class="token-typeIdentifier" href="../../../Foundation/NSError/index.html">NSError</a>
                  **) <span class="token-internalParam">error</span>
                 ;</code>
             </pre>
@@ -533,7 +533,7 @@ struct MarkdownRenderer_PageElementsTests {
             <p>Some description of this group</p>
             <ul>
                 <li>
-                    <a href="../../../SomeClass/index.html">
+                    <a href="../../SomeClass/index.html">
                         <code class="swift-only">
                             <span class="decorator">class </span>
                             <span class="identifier">Some<wbr/>
@@ -549,7 +549,7 @@ struct MarkdownRenderer_PageElementsTests {
                     </a>
                 </li>
                 <li>
-                    <a href="../../../SomeArticle/index.html">
+                    <a href="../../SomeArticle/index.html">
                         <p>Some Article</p>
                         <p>Some <b>formatted</b>
                              description of this <i>article</i>
@@ -557,7 +557,7 @@ struct MarkdownRenderer_PageElementsTests {
                     </a>
                 </li>
                 <li>
-                    <a href="../../../SomeClass/someMethod(with:and:)/index.html">
+                    <a href="../../SomeClass/someMethod(with:and:)/index.html">
                         <code class="swift-only">
                             <span class="decorator">func </span>
                             <span class="identifier">some<wbr/>
@@ -592,14 +592,14 @@ struct MarkdownRenderer_PageElementsTests {
             <p>Some description of this group</p>
             <ul>
                 <li>
-                    <a href="../../../SomeClass/index.html">
+                    <a href="../../SomeClass/index.html">
                         <code>class SomeClass</code>
                         <p>Some <i>formatted</i>
                              description of this class</p>
                     </a>
                 </li>
                 <li>
-                    <a href="../../../SomeArticle/index.html">
+                    <a href="../../SomeArticle/index.html">
                         <p>Some Article</p>
                         <p>Some <b>formatted</b>
                              description of this <i>article</i>
@@ -607,7 +607,7 @@ struct MarkdownRenderer_PageElementsTests {
                     </a>
                 </li>
                 <li>
-                    <a href="../../../SomeClass/someMethod(with:and:)/index.html">
+                    <a href="../../SomeClass/someMethod(with:and:)/index.html">
                         <code>func someMethod(with: Int, and: String)</code>
                     </a>
                 </li>
diff --git a/Tests/DocCHTMLTests/MarkdownRendererTests.swift b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
index f9d9551522..3c5a9c3f5c 100644
--- a/Tests/DocCHTMLTests/MarkdownRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
@@ -369,7 +369,7 @@ struct MarkdownRendererTests {
             prettyFormatted: true,
             matches: """
             <p>
-            <a href="../../SomeArticle/index.html">Some Article Title</a>
+            <a href="../SomeArticle/index.html">Some Article Title</a>
             </p>
             """
         )
@@ -390,7 +390,7 @@ struct MarkdownRendererTests {
             prettyFormatted: true,
             matches: """
             <p>
-            <a href="../../SomeClass/someMethod(_:_:)/index.html">
+            <a href="../SomeClass/someMethod(_:_:)/index.html">
                 <code>some<wbr/>
                     Method(<wbr/>
                     _:<wbr/>
@@ -407,7 +407,7 @@ struct MarkdownRendererTests {
             prettyFormatted: true,
             matches: """
             <p>
-            <a href="../../SomeClass/someMethod(_:_:)/index.html">
+            <a href="../SomeClass/someMethod(_:_:)/index.html">
                 <code class="swift-only">do<wbr/>
                     Something(<wbr/>
                     with:<wbr/>
@@ -428,7 +428,7 @@ struct MarkdownRendererTests {
             rendering: "[Custom _formatted_ title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
             elementToReturn: makeExampleMethodWithDifferentLanguageRepresentations(),
             matches: """
-            <p><a href="../../SomeClass/someMethod(_:_:)/index.html">Custom <i>formatted</i> title</a></p>
+            <p><a href="../SomeClass/someMethod(_:_:)/index.html">Custom <i>formatted</i> title</a></p>
             """
         )
         
@@ -437,7 +437,7 @@ struct MarkdownRendererTests {
             rendering: "[Some `CustomSymbolName` title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
             elementToReturn: makeExampleMethodWithDifferentLanguageRepresentations(),
             matches: """
-            <p><a href="../../SomeClass/someMethod(_:_:)/index.html">Some <code>Custom<wbr/>Symbol<wbr/>Name</code> title</a></p>
+            <p><a href="../SomeClass/someMethod(_:_:)/index.html">Some <code>Custom<wbr/>Symbol<wbr/>Name</code> title</a></p>
             """
         )
         
@@ -477,7 +477,7 @@ struct MarkdownRendererTests {
             matches: """
             <p>
             <picture>
-                <img alt="Some alt text" decoding="async" loading="lazy" src="../../../../../images/com.test.example/some-image.png"/>
+                <img alt="Some alt text" decoding="async" loading="lazy" src="../../../../images/com.test.example/some-image.png"/>
             </picture>
             </p>
             """
@@ -496,7 +496,7 @@ struct MarkdownRendererTests {
             matches: """
             <p>
             <picture>
-                <img alt="Some alt text" decoding="async" loading="lazy" srcset="../../../../../images/com.test.example/some-image@2x.png 2x, ../../../../../images/com.test.example/some-image.png 1x"/>
+                <img alt="Some alt text" decoding="async" loading="lazy" srcset="../../../../images/com.test.example/some-image@2x.png 2x, ../../../../images/com.test.example/some-image.png 1x"/>
             </picture>
             </p>
             """
@@ -513,8 +513,8 @@ struct MarkdownRendererTests {
             matches: """
             <p>
             <picture>
-                <source media="(prefers-color-scheme: light)" src="../../../../../images/com.test.example/some-image.png"/>
-                <source media="(prefers-color-scheme: dark)" src="../../../../../images/com.test.example/some-image~dark.png"/>
+                <source media="(prefers-color-scheme: light)" src="../../../../images/com.test.example/some-image.png"/>
+                <source media="(prefers-color-scheme: dark)" src="../../../../images/com.test.example/some-image~dark.png"/>
                 <img alt="Some alt text" decoding="async" loading="lazy"/>
             </picture>
             </p>
@@ -538,8 +538,8 @@ struct MarkdownRendererTests {
             matches: """
             <p>
             <picture>
-                <source media="(prefers-color-scheme: light)" srcset="../../../../../images/com.test.example/some-image@2x.png 2x, ../../../../../images/com.test.example/some-image.png 1x"/>
-                <source media="(prefers-color-scheme: dark)" srcset="../../../../../images/com.test.example/some-image~dark@2x.png 2x, ../../../../../images/com.test.example/some-image~dark.png 1x"/>
+                <source media="(prefers-color-scheme: light)" srcset="../../../../images/com.test.example/some-image@2x.png 2x, ../../../../images/com.test.example/some-image.png 1x"/>
+                <source media="(prefers-color-scheme: dark)" srcset="../../../../images/com.test.example/some-image~dark@2x.png 2x, ../../../../images/com.test.example/some-image~dark.png 1x"/>
                 <img alt="Some alt text" decoding="async" loading="lazy"/>
             </picture>
             </p>
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index fc1933d1bb..527d4b8af5 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -210,14 +210,14 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                  description of this topic section</p>
             <ul>
                 <li>
-                    <a href="../SomeArticle/index.html">
+                    <a href="SomeArticle/index.html">
                         <p>Some article</p>
                         <p>This is an <i>formatted</i>
                              article.</p>
                     </a>
                 </li>
                 <li>
-                    <a href="../SomeClass/index.html">
+                    <a href="SomeClass/index.html">
                         <code>class SomeClass</code>
                         <p>Some in-source description of this class.</p>
                     </a>
@@ -243,7 +243,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         <section>
             <ul>
                 <li>
-                    <a href="../../index.html">ModuleName</a>
+                    <a href="../index.html">ModuleName</a>
                 </li>
                 <li>SomeClass</li>
             </ul>
@@ -259,7 +259,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <h3>Instance Methods</h3>
             <ul>
                 <li>
-                    <a href="../someMethod(with:and:)/index.html">
+                    <a href="someMethod(with:and:)/index.html">
                         <code>func someMethod(with first: Int, and second: String) -&gt; Bool</code>
                         <p>Some in-source description of this method.</p>
                     </a>
@@ -285,10 +285,10 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         <section>
             <ul>
                 <li>
-                    <a href="../../../index.html">ModuleName</a>
+                    <a href="../../index.html">ModuleName</a>
                 </li>
                 <li>
-                    <a href="../../index.html">SomeClass</a>
+                    <a href="../index.html">SomeClass</a>
                 </li>
                 <li>someMethod(with:and:)</li>
             </ul>
@@ -331,7 +331,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <h3>Related Documentation</h3>
             <ul>
                 <li>
-                    <a href="../../../SomeArticle/index.html">
+                    <a href="../../SomeArticle/index.html">
                         <p>Some article</p>
                         <p>This is an <i>formatted</i>
                              article.</p>
@@ -358,7 +358,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         <section>
             <ul>
                 <li>
-                    <a href="../../index.html">ModuleName</a>
+                    <a href="../index.html">ModuleName</a>
                 </li>
                 <li>Some article</li>
             </ul>
@@ -378,7 +378,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <h3>Related Documentation</h3>
             <ul>
                 <li>
-                    <a href="../../SomeClass/index.html">
+                    <a href="../SomeClass/index.html">
                         <code>class SomeClass</code>
                         <p>Some in-source description of this class.</p>
                     </a>

From 43018c892f07cfdc60d1ead7487e749af8d2968f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 28 Nov 2025 11:17:19 +0100
Subject: [PATCH 55/68] Add FIXME about future changes once other PRs are
 merged

---
 Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 5b34264f10..64f2ecd547 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -39,6 +39,7 @@ private struct ContextLinkProvider: DocCHTML.LinkProvider {
                // This symbol has multiple unique names
                 let titles = [SourceLanguage: String](
                     titles.map { trait, title in
+                        // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
                         ((trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift), title)
                     },
                     uniquingKeysWith: { _, new in new }
@@ -92,6 +93,7 @@ private struct ContextLinkProvider: DocCHTML.LinkProvider {
                 // This symbol has multiple unique names
                 subheadings = .languageSpecificSymbol(.init(
                     allSubheadings.map { trait, subheading in (
+                        // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
                         key:   (trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift),
                         value: convert(subheading)
                     )},
@@ -293,6 +295,7 @@ struct HTMLRenderer {
         } else {
             names = .languageSpecificSymbol([SourceLanguage: String](
                 symbol.titleVariants.allValues.compactMap({ trait, title in
+                    // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
                     guard let languageID = trait.interfaceLanguage else { return nil }
                     return (key: SourceLanguage(id: languageID), value: title)
                 }),
@@ -314,6 +317,7 @@ struct HTMLRenderer {
         // Title
         let titleVariants = symbol.titleVariants.allValues.sorted(by: { $0.trait < $1.trait})
         for (trait, variant) in titleVariants {
+            // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
             guard let lang = trait.interfaceLanguage else { continue }
             
             var classes: [String] = []
@@ -371,6 +375,7 @@ struct HTMLRenderer {
             
             var fragmentsByLanguageID = [SourceLanguage: [SymbolGraph.Symbol.DeclarationFragments.Fragment]]()
             for (trait, variant) in symbol.declarationVariants.allValues {
+                // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
                 guard let languageID = trait.interfaceLanguage else { continue }
                 fragmentsByLanguageID[SourceLanguage(id: languageID)] = variant.values.first?.declarationFragments
             }
@@ -404,6 +409,7 @@ struct HTMLRenderer {
                 renderer.parameters(
                     .init(
                         symbol.parametersSectionVariants.allValues.map { trait, parameters in (
+                            // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
                             key:   trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift,
                             value: parameters.parameters.map {
                                 .init(name: $0.name, content: $0.contents)
@@ -421,6 +427,7 @@ struct HTMLRenderer {
                 renderer.returns(
                     .init(
                         symbol.returnsSectionVariants.allValues.map { trait, returnSection in (
+                            // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
                             key:   trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift,
                             value: returnSection.content
                         )},
@@ -515,6 +522,7 @@ struct HTMLRenderer {
 // Note; this isn't a Comparable conformance because I wanted it to be private to this file.
 private extension DocumentationDataVariantsTrait {
     static func < (lhs: DocumentationDataVariantsTrait, rhs: DocumentationDataVariantsTrait) -> Bool {
+        // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
         (lhs.interfaceLanguage ?? "") < (rhs.interfaceLanguage ?? "")
     }
 }

From 4c60f0c865fa84072e012f3d5437b0b84d7301b5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 28 Nov 2025 11:46:16 +0100
Subject: [PATCH 56/68] Share logic with the JSON file writer for creating
 files and directories

---
 .../Actions/Convert/ConvertAction.swift       |  4 +-
 .../FileWritingHTMLContentConsumer.swift      | 11 +++-
 .../JSONEncodingRenderNodeWriter.swift        | 63 +++++++++----------
 .../FileWritingHTMLContentConsumerTests.swift | 22 +++----
 4 files changed, 51 insertions(+), 49 deletions(-)

diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
index 5c2cc9e008..e6d6e03bf6 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
@@ -252,7 +252,7 @@ public struct ConvertAction: AsyncAction {
 //        }
 
         let indexHTML: URL?
-        if let htmlTemplateDirectory, transformForStaticHosting, !includeContentInEachHTMLFile {
+        if let htmlTemplateDirectory, transformForStaticHosting || includeContentInEachHTMLFile {
             let indexHTMLUrl = temporaryFolder.appendingPathComponent(
                 HTMLTemplate.indexFileName.rawValue,
                 isDirectory: false
@@ -303,7 +303,7 @@ public struct ConvertAction: AsyncAction {
             context: context,
             indexer: indexer,
             enableCustomTemplates: experimentalEnableCustomTemplates,
-            transformForStaticHostingIndexHTML: indexHTML,
+            transformForStaticHostingIndexHTML: includeContentInEachHTMLFile ? nil : indexHTML,
             bundleID: inputs.id
         )
         
diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
index 4d394775ea..780dda5aa6 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
@@ -61,6 +61,7 @@ struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
         }
     }
     private var htmlTemplate: HTMLTemplate
+    private let fileWriter: JSONEncodingRenderNodeWriter
     
     init(
         targetFolder: URL,
@@ -72,6 +73,11 @@ struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
         self.fileManager = fileManager
         self.htmlTemplate = try HTMLTemplate(data: fileManager.contents(of: htmlTemplate))
         self.prettyPrintOutput = prettyPrintOutput
+        self.fileWriter = JSONEncodingRenderNodeWriter(
+            targetFolder: targetFolder,
+            fileManager: fileManager,
+            transformForStaticHostingIndexHTML: nil
+        )
     }
     
     func consume(
@@ -86,9 +92,8 @@ struct FileWritingHTMLContentConsumer: HTMLContentConsumer {
             prettyPrint: prettyPrintOutput
         )
         
-        let url = targetFolder.appendingPathComponent(reference.path)
-        try? fileManager.createDirectory(at: url, withIntermediateDirectories: true, attributes: nil)
-        try fileManager.createFile(at: url.appendingPathComponent("index.html"), contents: Data(htmlString.utf8), options: .atomic)
+        let relativeFilePath = NodeURLGenerator.fileSafeReferencePath(reference, lowercased: true) + "/index.html"
+        try fileWriter.write(Data(htmlString.utf8), toFileSafePath: relativeFilePath)
     }
 }
 
diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/JSONEncodingRenderNodeWriter.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/JSONEncodingRenderNodeWriter.swift
index 30ac26eb0d..ff543a0ace 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/JSONEncodingRenderNodeWriter.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/JSONEncodingRenderNodeWriter.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2025 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -15,7 +15,6 @@ import SwiftDocC
 ///
 /// The render node writer writes the JSON files into a hierarchy of folders and subfolders based on the relative URL for each node.
 class JSONEncodingRenderNodeWriter {
-    private let renderNodeURLGenerator: NodeURLGenerator
     private let targetFolder: URL
     private let transformForStaticHostingIndexHTML: URL?
     private let fileManager: any FileManagerProtocol
@@ -27,9 +26,6 @@ class JSONEncodingRenderNodeWriter {
     ///   - targetFolder: The folder to which the writer object writes the files.
     ///   - fileManager: The file manager with which the writer object writes data to files.
     init(targetFolder: URL, fileManager: any FileManagerProtocol, transformForStaticHostingIndexHTML: URL?) {
-        self.renderNodeURLGenerator = NodeURLGenerator(
-            baseURL: targetFolder.appendingPathComponent("data", isDirectory: true)
-        )
         self.targetFolder = targetFolder
         self.transformForStaticHostingIndexHTML = transformForStaticHostingIndexHTML
         self.fileManager = fileManager
@@ -52,34 +48,11 @@ class JSONEncodingRenderNodeWriter {
             lowercased: true
         )
         
-        // The path on disk to write the render node JSON file at.
-        let renderNodeTargetFileURL = renderNodeURLGenerator
-            .urlForReference(
-                renderNode.identifier,
-                fileSafePath: fileSafePath
-            )
-            .appendingPathExtension("json")
-        
-        let renderNodeTargetFolderURL = renderNodeTargetFileURL.deletingLastPathComponent()
-        
-        // On Linux sometimes it takes a moment for the directory to be created and that leads to
-        // errors when trying to write files concurrently in the same target location.
-        // We keep an index in `directoryIndex` and create new sub-directories as needed.
-        // When the symbol's directory already exists no code is executed during the lock below
-        // besides the set lookup.
-        try directoryIndex.sync { directoryIndex in
-            let (insertedRenderNodeTargetFolderURL, _) = directoryIndex.insert(renderNodeTargetFolderURL)
-            if insertedRenderNodeTargetFolderURL {
-                try fileManager.createDirectory(
-                    at: renderNodeTargetFolderURL,
-                    withIntermediateDirectories: true,
-                    attributes: nil
-                )
-            }
-        }
-        
-        let data = try renderNode.encodeToJSON(with: encoder, renderReferenceCache: renderReferenceCache)
-        try fileManager.createFile(at: renderNodeTargetFileURL, contents: data, options: nil)
+        try write(
+            renderNode.encodeToJSON(with: encoder, renderReferenceCache: renderReferenceCache),
+            // The path on disk to write the render node JSON file at.
+            toFileSafePath: "data/\(fileSafePath).json"
+        )
         
         guard let indexHTML = transformForStaticHostingIndexHTML else {
             return
@@ -115,4 +88,28 @@ class JSONEncodingRenderNodeWriter {
             try fileManager._copyItem(at: indexHTML, to: htmlTargetFileURL)
         }
     }
+    
+    func write(_ data: Data, toFileSafePath fileSafePath: String) throws {
+        // The path on disk to write the data at.
+        let fileURL = targetFolder.appendingPathComponent(fileSafePath, isDirectory: false)
+        let containingFolderURL = fileURL.deletingLastPathComponent()
+        
+        // On Linux sometimes it takes a moment for the directory to be created and that leads to
+        // errors when trying to write files concurrently in the same target location.
+        // We keep an index in `directoryIndex` and create new sub-directories as needed.
+        // When the symbol's directory already exists no code is executed during the lock below
+        // besides the set lookup.
+        try directoryIndex.sync { directoryIndex in
+            let (insertedRenderNodeTargetFolderURL, _) = directoryIndex.insert(containingFolderURL)
+            if insertedRenderNodeTargetFolderURL {
+                try fileManager.createDirectory(
+                    at: containingFolderURL,
+                    withIntermediateDirectories: true,
+                    attributes: nil
+                )
+            }
+        }
+        
+        try fileManager.createFile(at: fileURL, contents: data, options: nil)
+    }
 }
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 527d4b8af5..1d524eda41 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -173,18 +173,18 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         XCTAssertEqual(fileSystem.dump(subHierarchyFrom: "/output-dir"), """
         output-dir/
         ╰─ documentation/
-           ╰─ ModuleName/
-              ├─ SomeArticle/
+           ╰─ modulename/
+              ├─ index.html
+              ├─ somearticle/
               │  ╰─ index.html
-              ├─ SomeClass/
-              │  ├─ index.html
-              │  ╰─ someMethod(with:and:)/
-              │     ╰─ index.html
-              ╰─ index.html
+              ╰─ someclass/
+                 ├─ index.html
+                 ╰─ somemethod(with:and:)/
+                    ╰─ index.html
         """)
         
         
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/ModuleName/index.html")), encoding: .utf8)), """
+        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/index.html")), encoding: .utf8)), """
         <html>
           <head>
             <meta charset="utf-8" />
@@ -230,7 +230,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </html>
         """)
         
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/ModuleName/SomeClass/index.html")), encoding: .utf8)), """
+        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/someclass/index.html")), encoding: .utf8)), """
         <html>
           <head>
             <meta charset="utf-8" />
@@ -272,7 +272,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </html>
         """)
         
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/ModuleName/SomeClass/someMethod(with:and:)/index.html")), encoding: .utf8)), """
+        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/someclass/somemethod(with:and:)/index.html")), encoding: .utf8)), """
         <html>
           <head>
             <meta charset="utf-8" />
@@ -345,7 +345,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </html>
         """)
         
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/ModuleName/SomeArticle/index.html")), encoding: .utf8)), """
+        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/somearticle/index.html")), encoding: .utf8)), """
         <html>
           <head>
             <meta charset="utf-8" />

From 7225dd911b30d8c9e85e0eddbb723355ce6a21fa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 28 Nov 2025 14:54:17 +0100
Subject: [PATCH 57/68] Include Mentioned In links in the HTML content

---
 .../Model/Rendering/HTML/HTMLRenderer.swift       | 15 +++++++++++++++
 .../FileWritingHTMLContentConsumerTests.swift     | 13 +++++++++++--
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 64f2ecd547..98186dfc79 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -445,6 +445,21 @@ struct HTMLRenderer {
             articleElement.addChild(.element(named: "hr")) // Separate the sections with a thematic break
         }
         
+        if FeatureFlags.current.isMentionedInEnabled {
+            separateCurationIfNeeded()
+            
+            let mentions = context.articleSymbolMentions.articlesMentioning(reference)
+            if !mentions.isEmpty {
+                articleElement.addChild(
+                    renderer.selfReferencingSection(named: "Mentioned In", content: [
+                        .element(named: "ul", children: mentions.compactMap { reference in
+                            context.documentationCache[reference].map { .element(named: "li", children: [.text($0.name.description)]) }
+                        })
+                    ])
+                )
+            }
+        }
+        
         // Discussion
         if let discussion = symbol.discussion {
             separateCurationIfNeeded()
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 1d524eda41..970ad05d38 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -27,7 +27,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             
             ## Custom discussion
             
-            It explains how a developer can perform some task using this module.
+            It explains how a developer can perform some task using ``SomeClass`` in this module.
             
             ### Details
             
@@ -254,6 +254,12 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 <code>class SomeClass</code>
             </pre>
         </section>
+        <section>
+            <h2>Mentioned In</h2>
+            <ul>
+                <li>Some article</li>
+            </ul>
+        </section>
         <section>
             <h2>Topics</h2>
             <h3>Instance Methods</h3>
@@ -369,7 +375,10 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </section>
         <section>
             <h2>Custom discussion</h2>
-            <p>It explains how a developer can perform some task using this module.</p>
+            <p>It explains how a developer can perform some task using <a href="../SomeClass/index.html">
+                    <code>SomeClass</code>
+                </a>
+                 in this module.</p>
             <h3>Details</h3>
             <p>This subsection describes something more detailed.</p>
         </section>

From 8fe0e0bee733d88f708034921a68c1d80933d0ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 28 Nov 2025 15:10:37 +0100
Subject: [PATCH 58/68] Further minimize the concise HTML by avoiding most
 <section> elements

---
 .../DocCHTML/MarkupRenderer+Parameters.swift  |   2 +-
 Sources/DocCHTML/MarkupRenderer+Returns.swift |  28 ++-
 Sources/DocCHTML/MarkupRenderer+Topics.swift  |   2 +-
 .../Model/Rendering/HTML/HTMLRenderer.swift   |  28 ++-
 .../MarkdownRenderer+PageElementsTests.swift  | 147 ++++++++------
 .../DocCHTMLTests/MarkdownRendererTests.swift |   7 +
 .../FileWritingHTMLContentConsumerTests.swift | 180 ++++++++----------
 7 files changed, 205 insertions(+), 189 deletions(-)

diff --git a/Sources/DocCHTML/MarkupRenderer+Parameters.swift b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
index c7309e6a3f..32ef4ccc97 100644
--- a/Sources/DocCHTML/MarkupRenderer+Parameters.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
@@ -28,7 +28,7 @@ package extension MarkdownRenderer {
         }
     }
     
-    func parameters(_ info: [SourceLanguage: [ParameterInfo]]) -> XMLElement {
+    func parameters(_ info: [SourceLanguage: [ParameterInfo]]) -> [XMLNode] {
         let info = RenderHelpers.sortedLanguageSpecificValues(info)
         let items: [XMLElement] = switch info.count {
         case 1:
diff --git a/Sources/DocCHTML/MarkupRenderer+Returns.swift b/Sources/DocCHTML/MarkupRenderer+Returns.swift
index 131c94666b..6d92a60a07 100644
--- a/Sources/DocCHTML/MarkupRenderer+Returns.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Returns.swift
@@ -18,7 +18,7 @@ package import Markdown
 package import DocCCommon
 
 package extension MarkdownRenderer {
-    func returns(_ languageSpecificSections: [SourceLanguage: [any Markup]]) -> XMLElement {
+    func returns(_ languageSpecificSections: [SourceLanguage: [any Markup]]) -> [XMLNode] {
         let info = RenderHelpers.sortedLanguageSpecificValues(languageSpecificSections)
         let items: [XMLNode] = if info.count == 1 {
             info.first!.value.map { visit($0) } // Verified to exist above
@@ -43,25 +43,23 @@ package extension MarkdownRenderer {
         return selfReferencingSection(named: "Return Value", content: items)
     }
     
-    func selfReferencingSection(named sectionName: String, content: [XMLNode]) -> XMLElement {
-        let headingContent: XMLNode
-        let sectionAttributes: [String: String]
-        
+    func selfReferencingSection(named sectionName: String, content: [XMLNode]) -> [XMLNode] {
         switch goal {
         case .richness:
             let id = urlReadableFragment(sectionName.lowercased())
-            headingContent = .element(named: "a", children: [.text(sectionName)], attributes: ["href": "#\(id)"])
-            sectionAttributes = ["id": id]
+            
+            return [.element(
+                named: "section",
+                children: [
+                    .element(named: "h2", children: [
+                        .element(named: "a", children: [.text(sectionName)], attributes: ["href": "#\(id)"])
+                    ])
+                ] + content,
+                attributes: ["id": id]
+            )]
         case .conciseness:
-            headingContent = .text(sectionName)
-            sectionAttributes = [:]
+            return [.element(named: "h2", children: [.text(sectionName)]) as XMLNode] + content
         }
-        
-        return .element(
-            named: "section",
-            children: [.element(named: "h2", children: [headingContent])] + content,
-            attributes: sectionAttributes
-        )
     }
 }
 
diff --git a/Sources/DocCHTML/MarkupRenderer+Topics.swift b/Sources/DocCHTML/MarkupRenderer+Topics.swift
index 6c274298a3..5516bbe606 100644
--- a/Sources/DocCHTML/MarkupRenderer+Topics.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Topics.swift
@@ -30,7 +30,7 @@ package extension MarkdownRenderer {
         }
     }
     
-    func groupedSection(named sectionName: String, groups taskGroups: [SourceLanguage: [TaskGroupInfo]]) -> XMLElement {
+    func groupedSection(named sectionName: String, groups taskGroups: [SourceLanguage: [TaskGroupInfo]]) -> [XMLNode] {
         let taskGroups = RenderHelpers.sortedLanguageSpecificValues(taskGroups)
         
         let items: [XMLElement] = if taskGroups.count == 1 {
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 98186dfc79..cbcade684e 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -218,7 +218,7 @@ struct HTMLRenderer {
         
         // Discussion
         if let discussion = article.discussion {
-            articleElement.addChild(makeDiscussion(discussion, isSymbol: false))
+            articleElement.addChildren(makeDiscussion(discussion, isSymbol: false))
         }
         
         func separateCurationIfNeeded() {
@@ -234,7 +234,7 @@ struct HTMLRenderer {
             separateCurationIfNeeded()
             
             // TODO: Support language specific topic sections
-            articleElement.addChild(
+            articleElement.addChildren(
                 renderer.groupedSection(named: "Topics", groups: [
                     .swift: topics.taskGroups.map { group in
                         .init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
@@ -250,7 +250,7 @@ struct HTMLRenderer {
         if let seeAlso = article.seeAlso {
             separateCurationIfNeeded()
             
-            articleElement.addChild(
+            articleElement.addChildren(
                 renderer.groupedSection(named: "See Also", groups: [
                     .swift: seeAlso.taskGroups.map { group in
                         .init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
@@ -405,7 +405,7 @@ struct HTMLRenderer {
         
         // Parameters
         if !symbol.parametersSectionVariants.allValues.isEmpty {
-            articleElement.addChild(
+            articleElement.addChildren(
                 renderer.parameters(
                     .init(
                         symbol.parametersSectionVariants.allValues.map { trait, parameters in (
@@ -423,7 +423,7 @@ struct HTMLRenderer {
         
         // Return value
         if !symbol.returnsSectionVariants.allValues.isEmpty {
-            articleElement.addChild(
+            articleElement.addChildren(
                 renderer.returns(
                     .init(
                         symbol.returnsSectionVariants.allValues.map { trait, returnSection in (
@@ -450,7 +450,7 @@ struct HTMLRenderer {
             
             let mentions = context.articleSymbolMentions.articlesMentioning(reference)
             if !mentions.isEmpty {
-                articleElement.addChild(
+                articleElement.addChildren(
                     renderer.selfReferencingSection(named: "Mentioned In", content: [
                         .element(named: "ul", children: mentions.compactMap { reference in
                             context.documentationCache[reference].map { .element(named: "li", children: [.text($0.name.description)]) }
@@ -464,7 +464,7 @@ struct HTMLRenderer {
         if let discussion = symbol.discussion {
             separateCurationIfNeeded()
             
-            articleElement.addChild(makeDiscussion(discussion, isSymbol: true))
+            articleElement.addChildren(makeDiscussion(discussion, isSymbol: true))
         }
         
         // Topics
@@ -488,7 +488,7 @@ struct HTMLRenderer {
             if !taskGroupInfo.isEmpty {
                 separateCurationIfNeeded()
                 
-                articleElement.addChild(renderer.groupedSection(named: "Topics", groups: [.swift: taskGroupInfo]))
+                articleElement.addChildren(renderer.groupedSection(named: "Topics", groups: [.swift: taskGroupInfo]))
             }
         }
         
@@ -496,7 +496,7 @@ struct HTMLRenderer {
         if let seeAlso = symbol.seeAlso {
             separateCurationIfNeeded()
             
-            articleElement.addChild(
+            articleElement.addChildren(
                 renderer.groupedSection(named: "See Also", groups: [
                     .swift: seeAlso.taskGroups.map { group in
                         .init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
@@ -517,7 +517,7 @@ struct HTMLRenderer {
         )
     }
     
-    private func makeDiscussion(_ discussion: DiscussionSection, isSymbol: Bool) -> XMLNode {
+    private func makeDiscussion(_ discussion: DiscussionSection, isSymbol: Bool) -> [XMLNode] {
         var remaining = discussion.content[...]
         
         let title: String
@@ -541,3 +541,11 @@ private extension DocumentationDataVariantsTrait {
         (lhs.interfaceLanguage ?? "") < (rhs.interfaceLanguage ?? "")
     }
 }
+
+private extension XMLElement {
+    func addChildren(_ nodes: [XMLNode]) {
+        for node in nodes {
+            addChild(node)
+        }
+    }
+}
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index 81cf8d23f0..632a6719ae 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -116,22 +116,39 @@ struct MarkdownRenderer_PageElementsTests {
                 """)),
             ]
         ])
-        let expectedHTMLStart = switch goal {
-        case .richness: """
+        
+        switch goal {
+        case .richness:
+            #expect(parameters.rendered(prettyFormatted: true) == """
             <section id="parameters">
             <h2>
                 <a href="#parameters">Parameters</a>
             </h2>
-            """
-        case .conciseness: """
-            <section>
+            <dl>
+                <dt>
+                    <code>First</code>
+                </dt>
+                <dd>
+                    <p>Some <i>formatted</i>
+                         description with <code>code</code>
+                    </p>
+                </dd>
+                <dt>
+                    <code>Second</code>
+                </dt>
+                <dd>
+                    <p>Some <b>other</b>
+                         <i>formatted</i>
+                         description</p>
+                    <p>That spans two paragraphs</p>
+                </dd>
+            </dl>
+            </section>
+            """)
+        case .conciseness:
+            #expect(parameters.rendered(prettyFormatted: true) == """
             <h2>Parameters</h2>
-            """
-        }
-        
-        #expect(parameters.rendered(prettyFormatted: true) == """
-        \(expectedHTMLStart)
-        <dl>
+            <dl>
             <dt>
                 <code>First</code>
             </dt>
@@ -149,9 +166,9 @@ struct MarkdownRenderer_PageElementsTests {
                      description</p>
                 <p>That spans two paragraphs</p>
             </dd>
-        </dl>
-        </section>
-        """)
+            </dl>
+            """)
+        }
     }
     
     @Test
@@ -312,25 +329,28 @@ struct MarkdownRenderer_PageElementsTests {
         let parameters = makeRenderer(goal: goal).returns([
             .swift: parseMarkup(string: "First paragraph\n\nSecond paragraph")
         ])
-        let expectedHTMLStart = switch goal {
-        case .richness: """
+        
+        let commonHTML = """
+        <p>First paragraph</p>
+        <p>Second paragraph</p>
+        """
+        
+        switch goal {
+        case .richness:
+            #expect(parameters.rendered(prettyFormatted: true) == """
             <section id="return-value">
             <h2>
                 <a href="#return-value">Return Value</a>
             </h2>
-            """
-        case .conciseness: """
-            <section>
+            \(commonHTML)
+            </section>
+            """)
+        case .conciseness:
+            #expect(parameters.rendered(prettyFormatted: true) == """
             <h2>Return Value</h2>
-            """
+            \(commonHTML)
+            """)
         }
-        
-        #expect(parameters.rendered(prettyFormatted: true) == """
-        \(expectedHTMLStart)
-        <p>First paragraph</p>
-        <p>Second paragraph</p>
-        </section>
-        """)
     }
     
     @Test(arguments: RenderGoal.allCases)
@@ -339,26 +359,29 @@ struct MarkdownRenderer_PageElementsTests {
             .swift:      parseMarkup(string: "First paragraph\n\nSecond paragraph"),
             .objectiveC: parseMarkup(string: "Other language's paragraph"),
         ])
-        let expectedHTMLStart = switch goal {
-        case .richness: """
+        
+        let commonHTML = """
+        <p class="swift-only">First paragraph</p>
+        <p class="swift-only">Second paragraph</p>
+        <p class="occ-only">Other language’s paragraph</p>
+        """
+        
+        switch goal {
+        case .richness:
+            #expect(parameters.rendered(prettyFormatted: true) == """
             <section id="return-value">
             <h2>
                 <a href="#return-value">Return Value</a>
             </h2>
-            """
-        case .conciseness: """
-            <section>
+            \(commonHTML)
+            </section>
+            """)
+        case .conciseness:
+            #expect(parameters.rendered(prettyFormatted: true) == """
             <h2>Return Value</h2>
-            """
+            \(commonHTML)
+            """)
         }
-        
-        #expect(parameters.rendered(prettyFormatted: true) == """
-        \(expectedHTMLStart)
-        <p class="swift-only">First paragraph</p>
-        <p class="swift-only">Second paragraph</p>
-        <p class="occ-only">Other language’s paragraph</p>
-        </section>
-        """)
     }
     
     @Test(arguments: RenderGoal.allCases)
@@ -586,33 +609,31 @@ struct MarkdownRenderer_PageElementsTests {
             """)
         case .conciseness:
             #expect(groupedSection.rendered(prettyFormatted: true) == """
-            <section>
             <h2>\(expectedGroupTitle)</h2>
             <h3>Group title</h3>
             <p>Some description of this group</p>
             <ul>
-                <li>
-                    <a href="../../SomeClass/index.html">
-                        <code>class SomeClass</code>
-                        <p>Some <i>formatted</i>
-                             description of this class</p>
-                    </a>
-                </li>
-                <li>
-                    <a href="../../SomeArticle/index.html">
-                        <p>Some Article</p>
-                        <p>Some <b>formatted</b>
-                             description of this <i>article</i>
-                            .</p>
-                    </a>
-                </li>
-                <li>
-                    <a href="../../SomeClass/someMethod(with:and:)/index.html">
-                        <code>func someMethod(with: Int, and: String)</code>
-                    </a>
-                </li>
+            <li>
+                <a href="../../SomeClass/index.html">
+                    <code>class SomeClass</code>
+                    <p>Some <i>formatted</i>
+                         description of this class</p>
+                </a>
+            </li>
+            <li>
+                <a href="../../SomeArticle/index.html">
+                    <p>Some Article</p>
+                    <p>Some <b>formatted</b>
+                         description of this <i>article</i>
+                        .</p>
+                </a>
+            </li>
+            <li>
+                <a href="../../SomeClass/someMethod(with:and:)/index.html">
+                    <code>func someMethod(with: Int, and: String)</code>
+                </a>
+            </li>
             </ul>
-            </section>
             """)
         }
     }
diff --git a/Tests/DocCHTMLTests/MarkdownRendererTests.swift b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
index 3c5a9c3f5c..97e8800391 100644
--- a/Tests/DocCHTMLTests/MarkdownRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
@@ -619,6 +619,13 @@ extension Sequence<XMLNode> {
     }
 }
 
+extension Sequence<XMLElement> {
+    func rendered(prettyFormatted: Bool) -> String {
+        map { $0.rendered(prettyFormatted: prettyFormatted) }
+            .joined(separator: prettyFormatted ? "\n" : "")
+    }
+}
+
 struct SingleValueLinkProvider: LinkProvider {
     var elementToReturn: LinkedElement?
     func element(for path: URL) -> LinkedElement? {
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 970ad05d38..1dfe9eee60 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -203,27 +203,25 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <p>Some <b>formatted</b>
                  description of this module</p>
         </section>
-        <section>
-            <h2>Topics</h2>
-            <h3>Something custom</h3>
-            <p>A custom <i>formatted</i>
-                 description of this topic section</p>
-            <ul>
-                <li>
-                    <a href="SomeArticle/index.html">
-                        <p>Some article</p>
-                        <p>This is an <i>formatted</i>
-                             article.</p>
-                    </a>
-                </li>
-                <li>
-                    <a href="SomeClass/index.html">
-                        <code>class SomeClass</code>
-                        <p>Some in-source description of this class.</p>
-                    </a>
-                </li>
-            </ul>
-        </section>
+        <h2>Topics</h2>
+        <h3>Something custom</h3>
+        <p>A custom <i>formatted</i>
+             description of this topic section</p>
+        <ul>
+            <li>
+                <a href="SomeArticle/index.html">
+                    <p>Some article</p>
+                    <p>This is an <i>formatted</i>
+                         article.</p>
+                </a>
+            </li>
+            <li>
+                <a href="SomeClass/index.html">
+                    <code>class SomeClass</code>
+                    <p>Some in-source description of this class.</p>
+                </a>
+            </li>
+        </ul>
         </article></noscript>
             <div id="app"></div>
           </body>
@@ -254,24 +252,20 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 <code>class SomeClass</code>
             </pre>
         </section>
-        <section>
-            <h2>Mentioned In</h2>
-            <ul>
-                <li>Some article</li>
-            </ul>
-        </section>
-        <section>
-            <h2>Topics</h2>
-            <h3>Instance Methods</h3>
-            <ul>
-                <li>
-                    <a href="someMethod(with:and:)/index.html">
-                        <code>func someMethod(with first: Int, and second: String) -&gt; Bool</code>
-                        <p>Some in-source description of this method.</p>
-                    </a>
-                </li>
-            </ul>
-        </section>
+        <h2>Mentioned In</h2>
+        <ul>
+            <li>Some article</li>
+        </ul>
+        <h2>Topics</h2>
+        <h3>Instance Methods</h3>
+        <ul>
+            <li>
+                <a href="someMethod(with:and:)/index.html">
+                    <code>func someMethod(with first: Int, and second: String) -&gt; Bool</code>
+                    <p>Some in-source description of this method.</p>
+                </a>
+            </li>
+        </ul>
         </article></noscript>
             <div id="app"></div>
           </body>
@@ -305,46 +299,38 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                 <code>func someMethod(with first: Int, and second: String) -&gt; Bool</code>
             </pre>
         </section>
-        <section>
-            <h2>Parameters</h2>
-            <dl>
-                <dt>
-                    <code>first</code>
-                </dt>
-                <dd>
-                    <p>Description of the <code>first</code>
-                         parameter.</p>
-                </dd>
-                <dt>
-                    <code>second</code>
-                </dt>
-                <dd>
-                    <p>Description of the <code>second</code>
-                         parameter.</p>
-                </dd>
-            </dl>
-        </section>
-        <section>
-            <h2>Return Value</h2>
-            <p>Description of the return value.</p>
-        </section>
-        <section>
-            <h2>Discussion</h2>
-            <p>Further description of this method and how to use it.</p>
-        </section>
-        <section>
-            <h2>See Also</h2>
-            <h3>Related Documentation</h3>
-            <ul>
-                <li>
-                    <a href="../../SomeArticle/index.html">
-                        <p>Some article</p>
-                        <p>This is an <i>formatted</i>
-                             article.</p>
-                    </a>
-                </li>
-            </ul>
-        </section>
+        <h2>Parameters</h2>
+        <dl>
+            <dt>
+                <code>first</code>
+            </dt>
+            <dd>
+                <p>Description of the <code>first</code>
+                     parameter.</p>
+            </dd>
+            <dt>
+                <code>second</code>
+            </dt>
+            <dd>
+                <p>Description of the <code>second</code>
+                     parameter.</p>
+            </dd>
+        </dl>
+        <h2>Return Value</h2>
+        <p>Description of the return value.</p>
+        <h2>Discussion</h2>
+        <p>Further description of this method and how to use it.</p>
+        <h2>See Also</h2>
+        <h3>Related Documentation</h3>
+        <ul>
+            <li>
+                <a href="../../SomeArticle/index.html">
+                    <p>Some article</p>
+                    <p>This is an <i>formatted</i>
+                         article.</p>
+                </a>
+            </li>
+        </ul>
         </article></noscript>
             <div id="app"></div>
           </body>
@@ -373,27 +359,23 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
             <p id="abstract">This is an <i>formatted</i>
                  article.</p>
         </section>
-        <section>
-            <h2>Custom discussion</h2>
-            <p>It explains how a developer can perform some task using <a href="../SomeClass/index.html">
-                    <code>SomeClass</code>
+        <h2>Custom discussion</h2>
+        <p>It explains how a developer can perform some task using <a href="../SomeClass/index.html">
+                <code>SomeClass</code>
+            </a>
+             in this module.</p>
+        <h3>Details</h3>
+        <p>This subsection describes something more detailed.</p>
+        <h2>See Also</h2>
+        <h3>Related Documentation</h3>
+        <ul>
+            <li>
+                <a href="../SomeClass/index.html">
+                    <code>class SomeClass</code>
+                    <p>Some in-source description of this class.</p>
                 </a>
-                 in this module.</p>
-            <h3>Details</h3>
-            <p>This subsection describes something more detailed.</p>
-        </section>
-        <section>
-            <h2>See Also</h2>
-            <h3>Related Documentation</h3>
-            <ul>
-                <li>
-                    <a href="../SomeClass/index.html">
-                        <code>class SomeClass</code>
-                        <p>Some in-source description of this class.</p>
-                    </a>
-                </li>
-            </ul>
-        </section>
+            </li>
+        </ul>
         </article></noscript>
             <div id="app"></div>
           </body>

From 49cb6299af1eff100e11d8bdc8fd2378c8c22407 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 28 Nov 2025 17:30:12 +0100
Subject: [PATCH 59/68] Avoid creating sections with only a heading in the HTML
 output

---
 Sources/DocCHTML/MarkupRenderer+Parameters.swift | 2 ++
 Sources/DocCHTML/MarkupRenderer+Returns.swift    | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/Sources/DocCHTML/MarkupRenderer+Parameters.swift b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
index 32ef4ccc97..b453b463c8 100644
--- a/Sources/DocCHTML/MarkupRenderer+Parameters.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
@@ -30,6 +30,8 @@ package extension MarkdownRenderer {
     
     func parameters(_ info: [SourceLanguage: [ParameterInfo]]) -> [XMLNode] {
         let info = RenderHelpers.sortedLanguageSpecificValues(info)
+        guard info.contains(where: { _, params in !params.isEmpty }) else { return [] }
+        
         let items: [XMLElement] = switch info.count {
         case 1:
             [_singleLanguageParameters(info.first!.value)] // Verified to exist above
diff --git a/Sources/DocCHTML/MarkupRenderer+Returns.swift b/Sources/DocCHTML/MarkupRenderer+Returns.swift
index 6d92a60a07..ef624c84e3 100644
--- a/Sources/DocCHTML/MarkupRenderer+Returns.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Returns.swift
@@ -44,6 +44,8 @@ package extension MarkdownRenderer {
     }
     
     func selfReferencingSection(named sectionName: String, content: [XMLNode]) -> [XMLNode] {
+        guard !content.isEmpty else { return [] }
+        
         switch goal {
         case .richness:
             let id = urlReadableFragment(sectionName.lowercased())

From 2df6b8dc5b5b4975c45711d92081239c255a6c3e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 28 Nov 2025 17:40:23 +0100
Subject: [PATCH 60/68] Lowercase links in the HTML to avoid making assumptions
 about a case insensitive hosting environment.

---
 Sources/DocCHTML/MarkdownRenderer.swift       |  1 +
 .../MarkdownRenderer+PageElementsTests.swift  | 32 +++++++++----------
 .../DocCHTMLTests/MarkdownRendererTests.swift | 10 +++---
 .../FileWritingHTMLContentConsumerTests.swift | 12 +++----
 4 files changed, 28 insertions(+), 27 deletions(-)

diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index a972e68e8b..f0c367b59d 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -264,6 +264,7 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
             + toComponents.dropFirst(commonPrefixLength)
        
         return relativeComponents.joined(separator: "/")
+            .lowercased() // Don't make assumptions about a case insensitive hosting environment.
     }
     
     func visit(_ image: Image) -> XMLNode {
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index 632a6719ae..16217a2a6e 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -306,12 +306,12 @@ struct MarkdownRenderer_PageElementsTests {
                  <span class="token-identifier">doSomething</span>
                 (<span class="token-externalParam">with</span>
                  <span class="token-internalParam">first</span>
-                : <a class="token-typeIdentifier" href="../../FirstParameterValue/index.html">FirstParameterValue</a>
+                : <a class="token-typeIdentifier" href="../../firstparametervalue/index.html">FirstParameterValue</a>
                 , <span class="token-externalParam">and</span>
                  <span class="token-internalParam">second</span>
-                : <a class="token-typeIdentifier" href="../../SecondParameterValue/index.html">SecondParameterValue</a>
+                : <a class="token-typeIdentifier" href="../../secondparametervalue/index.html">SecondParameterValue</a>
                 ) <span class="token-keyword">throws</span>
-                -&gt; <a class="token-typeIdentifier" href="../../ReturnValue/index.html">ReturnValue</a>
+                -&gt; <a class="token-typeIdentifier" href="../../returnvalue/index.html">ReturnValue</a>
             </code>
             </pre>
             """)
@@ -449,22 +449,22 @@ struct MarkdownRenderer_PageElementsTests {
                  <span class="token-identifier">doSomething</span>
                 (<span class="token-externalParam">with</span>
                  <span class="token-internalParam">first</span>
-                : <a class="token-typeIdentifier" href="../../FirstParameterValue/index.html">FirstParameterValue</a>
+                : <a class="token-typeIdentifier" href="../../firstparametervalue/index.html">FirstParameterValue</a>
                 , <span class="token-externalParam">and</span>
                  <span class="token-internalParam">second</span>
-                : <a class="token-typeIdentifier" href="../../SecondParameterValue/index.html">SecondParameterValue</a>
+                : <a class="token-typeIdentifier" href="../../secondparametervalue/index.html">SecondParameterValue</a>
                 ) <span class="token-keyword">throws</span>
-                -&gt; <a class="token-typeIdentifier" href="../../ReturnValue/index.html">ReturnValue</a>
+                -&gt; <a class="token-typeIdentifier" href="../../returnvalue/index.html">ReturnValue</a>
             </code>
-            <code class="occ-only">- (<a class="token-typeIdentifier" href="../../ReturnValue/index.html">ReturnValue</a>
+            <code class="occ-only">- (<a class="token-typeIdentifier" href="../../returnvalue/index.html">ReturnValue</a>
                 ) <span class="token-identifier">doSomethingWithFirst</span>
-                : (<a class="token-typeIdentifier" href="../../FirstParameterValue/index.html">FirstParameterValue</a>
+                : (<a class="token-typeIdentifier" href="../../firstparametervalue/index.html">FirstParameterValue</a>
                 ) <span class="token-internalParam">first</span>
                  <span class="token-identifier">andSecond</span>
-                : (<a class="token-typeIdentifier" href="../../SecondParameterValue/index.html">SecondParameterValue</a>
+                : (<a class="token-typeIdentifier" href="../../secondparametervalue/index.html">SecondParameterValue</a>
                 ) <span class="token-internalParam">second</span>
                  <span class="token-identifier">error</span>
-                : (<a class="token-typeIdentifier" href="../../../Foundation/NSError/index.html">NSError</a>
+                : (<a class="token-typeIdentifier" href="../../../foundation/nserror/index.html">NSError</a>
                  **) <span class="token-internalParam">error</span>
                 ;</code>
             </pre>
@@ -556,7 +556,7 @@ struct MarkdownRenderer_PageElementsTests {
             <p>Some description of this group</p>
             <ul>
                 <li>
-                    <a href="../../SomeClass/index.html">
+                    <a href="../../someclass/index.html">
                         <code class="swift-only">
                             <span class="decorator">class </span>
                             <span class="identifier">Some<wbr/>
@@ -572,7 +572,7 @@ struct MarkdownRenderer_PageElementsTests {
                     </a>
                 </li>
                 <li>
-                    <a href="../../SomeArticle/index.html">
+                    <a href="../../somearticle/index.html">
                         <p>Some Article</p>
                         <p>Some <b>formatted</b>
                              description of this <i>article</i>
@@ -580,7 +580,7 @@ struct MarkdownRenderer_PageElementsTests {
                     </a>
                 </li>
                 <li>
-                    <a href="../../SomeClass/someMethod(with:and:)/index.html">
+                    <a href="../../someclass/somemethod(with:and:)/index.html">
                         <code class="swift-only">
                             <span class="decorator">func </span>
                             <span class="identifier">some<wbr/>
@@ -614,14 +614,14 @@ struct MarkdownRenderer_PageElementsTests {
             <p>Some description of this group</p>
             <ul>
             <li>
-                <a href="../../SomeClass/index.html">
+                <a href="../../someclass/index.html">
                     <code>class SomeClass</code>
                     <p>Some <i>formatted</i>
                          description of this class</p>
                 </a>
             </li>
             <li>
-                <a href="../../SomeArticle/index.html">
+                <a href="../../somearticle/index.html">
                     <p>Some Article</p>
                     <p>Some <b>formatted</b>
                          description of this <i>article</i>
@@ -629,7 +629,7 @@ struct MarkdownRenderer_PageElementsTests {
                 </a>
             </li>
             <li>
-                <a href="../../SomeClass/someMethod(with:and:)/index.html">
+                <a href="../../someclass/somemethod(with:and:)/index.html">
                     <code>func someMethod(with: Int, and: String)</code>
                 </a>
             </li>
diff --git a/Tests/DocCHTMLTests/MarkdownRendererTests.swift b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
index 97e8800391..485fd50d66 100644
--- a/Tests/DocCHTMLTests/MarkdownRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
@@ -369,7 +369,7 @@ struct MarkdownRendererTests {
             prettyFormatted: true,
             matches: """
             <p>
-            <a href="../SomeArticle/index.html">Some Article Title</a>
+            <a href="../somearticle/index.html">Some Article Title</a>
             </p>
             """
         )
@@ -390,7 +390,7 @@ struct MarkdownRendererTests {
             prettyFormatted: true,
             matches: """
             <p>
-            <a href="../SomeClass/someMethod(_:_:)/index.html">
+            <a href="../someclass/somemethod(_:_:)/index.html">
                 <code>some<wbr/>
                     Method(<wbr/>
                     _:<wbr/>
@@ -407,7 +407,7 @@ struct MarkdownRendererTests {
             prettyFormatted: true,
             matches: """
             <p>
-            <a href="../SomeClass/someMethod(_:_:)/index.html">
+            <a href="../someclass/somemethod(_:_:)/index.html">
                 <code class="swift-only">do<wbr/>
                     Something(<wbr/>
                     with:<wbr/>
@@ -428,7 +428,7 @@ struct MarkdownRendererTests {
             rendering: "[Custom _formatted_ title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
             elementToReturn: makeExampleMethodWithDifferentLanguageRepresentations(),
             matches: """
-            <p><a href="../SomeClass/someMethod(_:_:)/index.html">Custom <i>formatted</i> title</a></p>
+            <p><a href="../someclass/somemethod(_:_:)/index.html">Custom <i>formatted</i> title</a></p>
             """
         )
         
@@ -437,7 +437,7 @@ struct MarkdownRendererTests {
             rendering: "[Some `CustomSymbolName` title](doc://com.example.test/documentation/Something/SomeClass/someMethod(_:_:))", // Simulate a link that's been locally resolved already
             elementToReturn: makeExampleMethodWithDifferentLanguageRepresentations(),
             matches: """
-            <p><a href="../SomeClass/someMethod(_:_:)/index.html">Some <code>Custom<wbr/>Symbol<wbr/>Name</code> title</a></p>
+            <p><a href="../someclass/somemethod(_:_:)/index.html">Some <code>Custom<wbr/>Symbol<wbr/>Name</code> title</a></p>
             """
         )
         
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 1dfe9eee60..02398d4da0 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -209,14 +209,14 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
              description of this topic section</p>
         <ul>
             <li>
-                <a href="SomeArticle/index.html">
+                <a href="somearticle/index.html">
                     <p>Some article</p>
                     <p>This is an <i>formatted</i>
                          article.</p>
                 </a>
             </li>
             <li>
-                <a href="SomeClass/index.html">
+                <a href="someclass/index.html">
                     <code>class SomeClass</code>
                     <p>Some in-source description of this class.</p>
                 </a>
@@ -260,7 +260,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         <h3>Instance Methods</h3>
         <ul>
             <li>
-                <a href="someMethod(with:and:)/index.html">
+                <a href="somemethod(with:and:)/index.html">
                     <code>func someMethod(with first: Int, and second: String) -&gt; Bool</code>
                     <p>Some in-source description of this method.</p>
                 </a>
@@ -324,7 +324,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         <h3>Related Documentation</h3>
         <ul>
             <li>
-                <a href="../../SomeArticle/index.html">
+                <a href="../../somearticle/index.html">
                     <p>Some article</p>
                     <p>This is an <i>formatted</i>
                          article.</p>
@@ -360,7 +360,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                  article.</p>
         </section>
         <h2>Custom discussion</h2>
-        <p>It explains how a developer can perform some task using <a href="../SomeClass/index.html">
+        <p>It explains how a developer can perform some task using <a href="../someclass/index.html">
                 <code>SomeClass</code>
             </a>
              in this module.</p>
@@ -370,7 +370,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         <h3>Related Documentation</h3>
         <ul>
             <li>
-                <a href="../SomeClass/index.html">
+                <a href="../someclass/index.html">
                     <code>class SomeClass</code>
                     <p>Some in-source description of this class.</p>
                 </a>

From f746d75fb3b7709291bb3f2a5de51de49b41e6f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 28 Nov 2025 18:23:58 +0100
Subject: [PATCH 61/68] Fix links in Mentioned In section

---
 Sources/DocCHTML/MarkdownRenderer.swift                  | 2 +-
 .../SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift    | 9 ++++++++-
 .../FileWritingHTMLContentConsumerTests.swift            | 4 +++-
 3 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index f0c367b59d..a3f81a923c 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -248,7 +248,7 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
         )
     }
     
-    func path(to other: URL) -> String {
+    package func path(to other: URL) -> String {
         let from = path
         let to   = other
         
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index cbcade684e..ca47ee90e3 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -451,9 +451,16 @@ struct HTMLRenderer {
             let mentions = context.articleSymbolMentions.articlesMentioning(reference)
             if !mentions.isEmpty {
                 articleElement.addChildren(
+                    // FIXME: Create a dedicated MarkdownRenderer method for the "Mentioned In" section
                     renderer.selfReferencingSection(named: "Mentioned In", content: [
                         .element(named: "ul", children: mentions.compactMap { reference in
-                            context.documentationCache[reference].map { .element(named: "li", children: [.text($0.name.description)]) }
+                            context.documentationCache[reference].map {
+                                .element(named: "li", children: [
+                                    .element(named: "a", children: [.text($0.name.description)], attributes: [
+                                        "href": renderer.path(to: $0.reference.url) + "/index.html"
+                                    ])
+                                ])
+                            }
                         })
                     ])
                 )
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 02398d4da0..2fd76076a0 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -254,7 +254,9 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </section>
         <h2>Mentioned In</h2>
         <ul>
-            <li>Some article</li>
+            <li>
+                <a href="../somearticle/index.html">Some article</a>
+            </li>
         </ul>
         <h2>Topics</h2>
         <h3>Instance Methods</h3>

From f5f29236d8e4f86fd2a13120daa6167c79121a1c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 28 Nov 2025 18:24:27 +0100
Subject: [PATCH 62/68] Fix trailing comma in parameters for compatibility with
 Swift 6.0

---
 Sources/DocCHTML/XMLNode+element.swift | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Sources/DocCHTML/XMLNode+element.swift b/Sources/DocCHTML/XMLNode+element.swift
index c30d92a2cb..e41c61da5f 100644
--- a/Sources/DocCHTML/XMLNode+element.swift
+++ b/Sources/DocCHTML/XMLNode+element.swift
@@ -18,7 +18,7 @@ extension XMLNode {
     package static func element(
         named name: String,
         children: [XMLNode]? = nil,
-        attributes: [String: String]? = nil,
+        attributes: [String: String]? = nil
     ) -> XMLElement {
         let attributeNodes: [XMLNode]?
         if let attributes, !attributes.isEmpty {

From 5468d4844a87973e482a9419e7fee6abf7d54f4e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 28 Nov 2025 18:28:01 +0100
Subject: [PATCH 63/68] Update how FoundationXML is imported

---
 Sources/DocCHTML/MarkdownRenderer.swift                   | 6 ++++++
 Sources/DocCHTML/MarkupRenderer+Availability.swift        | 3 ++-
 Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift         | 4 +++-
 Sources/DocCHTML/MarkupRenderer+Declaration.swift         | 3 ++-
 Sources/DocCHTML/MarkupRenderer+Parameters.swift          | 3 ++-
 Sources/DocCHTML/MarkupRenderer+Returns.swift             | 4 +++-
 Sources/DocCHTML/MarkupRenderer+Topics.swift              | 4 +++-
 Sources/DocCHTML/WordBreak.swift                          | 3 ++-
 Sources/DocCHTML/XMLNode+element.swift                    | 3 ++-
 .../SwiftDocC/Infrastructure/ConvertOutputConsumer.swift  | 3 ---
 .../Model/Rendering/HTML/HTMLContentConsumer.swift        | 3 ++-
 Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift | 8 +++++---
 .../Actions/Convert/FileWritingHTMLContentConsumer.swift  | 6 ++++++
 .../MarkdownRenderer+PageElementsTests.swift              | 7 +++++++
 Tests/DocCHTMLTests/MarkdownRendererTests.swift           | 7 +++++++
 Tests/DocCHTMLTests/WordBreakTests.swift                  | 7 +++++++
 16 files changed, 59 insertions(+), 15 deletions(-)

diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index a3f81a923c..f696232d33 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -8,7 +8,13 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+package import FoundationXML
+package import FoundationEssentials
+#else
 package import Foundation
+#endif
 package import Markdown
 
 /// The primary goal for the rendered HTML output.
diff --git a/Sources/DocCHTML/MarkupRenderer+Availability.swift b/Sources/DocCHTML/MarkupRenderer+Availability.swift
index e70439cdcb..3c47245240 100644
--- a/Sources/DocCHTML/MarkupRenderer+Availability.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Availability.swift
@@ -8,10 +8,11 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-package import Foundation
 #if canImport(FoundationXML)
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 package import FoundationXML
+#else
+package import Foundation
 #endif
 
 package extension MarkdownRenderer {
diff --git a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
index 9c14df034b..5016d307b3 100644
--- a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
@@ -8,10 +8,12 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-package import Foundation
 #if canImport(FoundationXML)
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 package import FoundationXML
+package import FoundationEssentials
+#else
+package import Foundation
 #endif
 
 package extension MarkdownRenderer {
diff --git a/Sources/DocCHTML/MarkupRenderer+Declaration.swift b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
index d42d645e36..1596766d6f 100644
--- a/Sources/DocCHTML/MarkupRenderer+Declaration.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Declaration.swift
@@ -8,10 +8,11 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-package import Foundation
 #if canImport(FoundationXML)
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 package import FoundationXML
+#else
+package import Foundation
 #endif
 
 package import DocCCommon
diff --git a/Sources/DocCHTML/MarkupRenderer+Parameters.swift b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
index b453b463c8..a173807036 100644
--- a/Sources/DocCHTML/MarkupRenderer+Parameters.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Parameters.swift
@@ -8,10 +8,11 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-package import Foundation
 #if canImport(FoundationXML)
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 package import FoundationXML
+#else
+package import Foundation
 #endif
 
 package import Markdown
diff --git a/Sources/DocCHTML/MarkupRenderer+Returns.swift b/Sources/DocCHTML/MarkupRenderer+Returns.swift
index ef624c84e3..5491aea3b5 100644
--- a/Sources/DocCHTML/MarkupRenderer+Returns.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Returns.swift
@@ -8,10 +8,12 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-package import Foundation
 #if canImport(FoundationXML)
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 package import FoundationXML
+internal import struct Foundation.CharacterSet
+#else
+package import Foundation
 #endif
 
 package import Markdown
diff --git a/Sources/DocCHTML/MarkupRenderer+Topics.swift b/Sources/DocCHTML/MarkupRenderer+Topics.swift
index 5516bbe606..9f65cc5978 100644
--- a/Sources/DocCHTML/MarkupRenderer+Topics.swift
+++ b/Sources/DocCHTML/MarkupRenderer+Topics.swift
@@ -8,10 +8,12 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-package import Foundation
 #if canImport(FoundationXML)
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 package import FoundationXML
+package import FoundationEssentials
+#else
+package import Foundation
 #endif
 
 package import Markdown
diff --git a/Sources/DocCHTML/WordBreak.swift b/Sources/DocCHTML/WordBreak.swift
index d8b9ddad8c..e86f12151f 100644
--- a/Sources/DocCHTML/WordBreak.swift
+++ b/Sources/DocCHTML/WordBreak.swift
@@ -8,10 +8,11 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-package import Foundation
 #if canImport(FoundationXML)
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 package import FoundationXML
+#else
+package import Foundation
 #endif
 
 package import DocCCommon
diff --git a/Sources/DocCHTML/XMLNode+element.swift b/Sources/DocCHTML/XMLNode+element.swift
index e41c61da5f..5f35f71b03 100644
--- a/Sources/DocCHTML/XMLNode+element.swift
+++ b/Sources/DocCHTML/XMLNode+element.swift
@@ -8,10 +8,11 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-package import Foundation
 #if canImport(FoundationXML)
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 package import FoundationXML
+#else
+package import Foundation
 #endif
 
 extension XMLNode {
diff --git a/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift b/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift
index d15e16b77d..288e84334e 100644
--- a/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift
+++ b/Sources/SwiftDocC/Infrastructure/ConvertOutputConsumer.swift
@@ -8,8 +8,6 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-public import Foundation
-
 /// 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
@@ -58,7 +56,6 @@ public extension ConvertOutputConsumer {
     func consume(renderReferenceStore: RenderReferenceStore) throws {}
     func consume(buildMetadata: BuildMetadata) throws {}
     func consume(linkResolutionInformation: SerializableLinkResolutionInformation) throws {}
-    func consume(page: XMLNode, for reference: ResolvedTopicReference) throws {}
 }
 
 // Default implementation so that conforming types don't need to implement deprecated API.
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLContentConsumer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLContentConsumer.swift
index 28a3ecf4ff..51162bd476 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLContentConsumer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLContentConsumer.swift
@@ -8,10 +8,11 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-package import Foundation
 #if canImport(FoundationXML)
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 package import FoundationXML
+#else
+package import Foundation
 #endif
 
 /// A consumer for HTML content produced during documentation conversion.
diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index ca47ee90e3..96a0d53b33 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -8,10 +8,12 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-import Foundation
 #if canImport(FoundationXML)
 // FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
 import FoundationXML
+import FoundationEssentials
+#else
+import Foundation
 #endif
 import DocCHTML
 import Markdown
@@ -407,12 +409,12 @@ struct HTMLRenderer {
         if !symbol.parametersSectionVariants.allValues.isEmpty {
             articleElement.addChildren(
                 renderer.parameters(
-                    .init(
+                    [SourceLanguage: [MarkdownRenderer<ContextLinkProvider>.ParameterInfo]](
                         symbol.parametersSectionVariants.allValues.map { trait, parameters in (
                             // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
                             key:   trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift,
                             value: parameters.parameters.map {
-                                .init(name: $0.name, content: $0.contents)
+                                MarkdownRenderer<ContextLinkProvider>.ParameterInfo(name: $0.name, content: $0.contents)
                             }
                         )},
                         uniquingKeysWith: { _, new in new }
diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
index 780dda5aa6..657aff508f 100644
--- a/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
+++ b/Sources/SwiftDocCUtilities/Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
@@ -8,7 +8,13 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+import FoundationXML
+import FoundationEssentials
+#else
 import Foundation
+#endif
 import SwiftDocC
 import DocCHTML
 
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index 16217a2a6e..c449303d64 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -8,7 +8,14 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
+#if canImport(FoundationEssentials)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+import FoundationXML
+import FoundationEssentials
+#else
 import Foundation
+#endif
+
 import Testing
 import DocCHTML
 @testable import SwiftDocC
diff --git a/Tests/DocCHTMLTests/MarkdownRendererTests.swift b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
index 485fd50d66..cd995f870c 100644
--- a/Tests/DocCHTMLTests/MarkdownRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
@@ -8,7 +8,14 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
+#if canImport(FoundationXML)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+import FoundationXML
+import FoundationEssentials
+#else
 import Foundation
+#endif
+
 import Testing
 import DocCHTML
 @testable import SwiftDocC
diff --git a/Tests/DocCHTMLTests/WordBreakTests.swift b/Tests/DocCHTMLTests/WordBreakTests.swift
index 892f1ddc56..bd35d27fab 100644
--- a/Tests/DocCHTMLTests/WordBreakTests.swift
+++ b/Tests/DocCHTMLTests/WordBreakTests.swift
@@ -8,7 +8,14 @@
  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
+#if canImport(FoundationEssentials)
+// FIXME: See if we can avoid depending on XMLNode/XMLParser to avoid needing to import FoundationXML
+import FoundationXML
+import FoundationEssentials
+#else
 import Foundation
+#endif
+
 import Testing
 import DocCHTML
 

From de766b9fd991a0df7d1f26c89728de981aa94396 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 1 Dec 2025 15:22:23 +0100
Subject: [PATCH 64/68] Update XML string comparisons to account for formatting
 differences across platforms

---
 Sources/DocCHTML/MarkdownRenderer.swift       | 20 ++++-----
 .../MarkdownRenderer+PageElementsTests.swift  | 36 +++++++--------
 .../DocCHTMLTests/MarkdownRendererTests.swift | 44 ++++++++++++++++---
 .../FileWritingHTMLContentConsumerTests.swift | 38 +++++++++++++---
 4 files changed, 98 insertions(+), 40 deletions(-)

diff --git a/Sources/DocCHTML/MarkdownRenderer.swift b/Sources/DocCHTML/MarkdownRenderer.swift
index f696232d33..d45848c442 100644
--- a/Sources/DocCHTML/MarkdownRenderer.swift
+++ b/Sources/DocCHTML/MarkdownRenderer.swift
@@ -171,7 +171,7 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
             return .text("")
         }
         
-        if link.childCount > 0 {
+        guard link.isAutolink else {
             var customTitle = [XMLNode]()
             for child in link.inlineChildren {
                 if let code = child as? InlineCode {
@@ -181,16 +181,14 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
                 }
             }
             
-            if customTitle != [.text(destination.absoluteString)] {
-                return .element(
-                    named: "a",
-                    children: customTitle,
-                    attributes: [
-                        // Use relative links for DocC elements, and the full link otherwise.
-                        "href": linkProvider.element(for: destination).flatMap { path(to: $0.path) } ?? destination.absoluteString
-                    ]
-                )
-            }
+            return .element(
+                named: "a",
+                children: customTitle,
+                attributes: [
+                    // Use relative links for DocC elements, and the full link otherwise.
+                    "href": linkProvider.element(for: destination).flatMap { path(to: $0.path) } ?? destination.absoluteString
+                ]
+            )
         }
         
         // Make a relative link
diff --git a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
index c449303d64..8d8f9c7732 100644
--- a/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift
@@ -53,7 +53,7 @@ struct MarkdownRenderer_PageElementsTests {
         let breadcrumbs = makeRenderer(goal: goal, elementsToReturn: elements).breadcrumbs(references: elements.map { $0.path }, currentPageNames: .single(.conceptual("ThisPage")))
         switch goal {
         case .richness:
-            #expect(breadcrumbs.rendered(prettyFormatted: true) == """
+            breadcrumbs.assertMatches(prettyFormatted: true, expectedXMLString: """
             <nav id="breadcrumbs">
             <ul>
                 <li>
@@ -70,7 +70,7 @@ struct MarkdownRenderer_PageElementsTests {
             </nav>
             """)
         case .conciseness:
-            #expect(breadcrumbs.rendered(prettyFormatted: true) == """
+            breadcrumbs.assertMatches(prettyFormatted: true, expectedXMLString: """
             <ul>
             <li>
                 <a href="../../index.html">ModuleName</a>
@@ -93,7 +93,7 @@ struct MarkdownRenderer_PageElementsTests {
         ])
         switch goal {
         case .richness:
-            #expect(availability.rendered(prettyFormatted: true) == """
+            availability.assertMatches(prettyFormatted: true, expectedXMLString: """
             <ul id="availability">
             <li aria-label="First 1.2–3.4, Introduced in First 1.2 and deprecated in First 3.4" class="deprecated" role="text" title="Introduced in First 1.2 and deprecated in First 3.4">First 1.2–3.4</li>
             <li aria-label="Second 1.2.3+, Available on 1.2.3 and later" role="text" title="Available on 1.2.3 and later">Second 1.2.3+</li>
@@ -101,7 +101,7 @@ struct MarkdownRenderer_PageElementsTests {
             </ul>
             """)
         case .conciseness:
-            #expect(availability.rendered(prettyFormatted: true) == """
+            availability.assertMatches(prettyFormatted: true, expectedXMLString: """
             <ul id="availability">
             <li>First 1.2–3.4</li>
             <li>Second 1.2.3+</li>
@@ -126,7 +126,7 @@ struct MarkdownRenderer_PageElementsTests {
         
         switch goal {
         case .richness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <section id="parameters">
             <h2>
                 <a href="#parameters">Parameters</a>
@@ -153,7 +153,7 @@ struct MarkdownRenderer_PageElementsTests {
             </section>
             """)
         case .conciseness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <h2>Parameters</h2>
             <dl>
             <dt>
@@ -192,7 +192,7 @@ struct MarkdownRenderer_PageElementsTests {
                 .init(name: "ObjectiveCOnly", content: parseMarkup(string: "Only available in Objective-C")),
             ],
         ])
-        #expect(parameters.rendered(prettyFormatted: true) == """
+        parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
         <section id="parameters">
         <h2>
             <a href="#parameters">Parameters</a>
@@ -240,7 +240,7 @@ struct MarkdownRenderer_PageElementsTests {
                 .init(name: "Third", content: parseMarkup(string: "Some description")),
             ],
         ])
-        #expect(parameters.rendered(prettyFormatted: true) == """
+        parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
         <section id="parameters">
         <h2>
             <a href="#parameters">Parameters</a>
@@ -306,7 +306,7 @@ struct MarkdownRenderer_PageElementsTests {
         ])
         switch goal {
         case .richness:
-            #expect(declaration.rendered(prettyFormatted: true) == """
+            declaration.assertMatches(prettyFormatted: true, expectedXMLString: """
             <pre id="declaration">
             <code>
                 <span class="token-keyword">func</span>
@@ -323,7 +323,7 @@ struct MarkdownRenderer_PageElementsTests {
             </pre>
             """)
         case .conciseness:
-            #expect(declaration.rendered(prettyFormatted: true) == """
+            declaration.assertMatches(prettyFormatted: true, expectedXMLString: """
             <pre>
             <code>func doSomething(with first: FirstParameterValue, and second: SecondParameterValue) throws-&gt; ReturnValue</code>
             </pre>
@@ -344,7 +344,7 @@ struct MarkdownRenderer_PageElementsTests {
         
         switch goal {
         case .richness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <section id="return-value">
             <h2>
                 <a href="#return-value">Return Value</a>
@@ -353,7 +353,7 @@ struct MarkdownRenderer_PageElementsTests {
             </section>
             """)
         case .conciseness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <h2>Return Value</h2>
             \(commonHTML)
             """)
@@ -375,7 +375,7 @@ struct MarkdownRenderer_PageElementsTests {
         
         switch goal {
         case .richness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <section id="return-value">
             <h2>
                 <a href="#return-value">Return Value</a>
@@ -384,7 +384,7 @@ struct MarkdownRenderer_PageElementsTests {
             </section>
             """)
         case .conciseness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <h2>Return Value</h2>
             \(commonHTML)
             """)
@@ -449,7 +449,7 @@ struct MarkdownRenderer_PageElementsTests {
         ])
         switch goal {
         case .richness:
-            #expect(declaration.rendered(prettyFormatted: true) == """
+            declaration.assertMatches(prettyFormatted: true, expectedXMLString: """
             <pre id="declaration">
             <code class="swift-only">
                 <span class="token-keyword">func</span>
@@ -478,7 +478,7 @@ struct MarkdownRenderer_PageElementsTests {
             """)
             
         case .conciseness:
-            #expect(declaration.rendered(prettyFormatted: true) == """
+            declaration.assertMatches(prettyFormatted: true, expectedXMLString: """
             <pre>
             <code>func doSomething(with first: FirstParameterValue, and second: SecondParameterValue) throws-&gt; ReturnValue</code>
             </pre>
@@ -552,7 +552,7 @@ struct MarkdownRenderer_PageElementsTests {
         
         switch goal {
         case .richness:
-            #expect(groupedSection.rendered(prettyFormatted: true) == """
+            groupedSection.assertMatches(prettyFormatted: true, expectedXMLString: """
             <section id="\(expectedSectionID)">
             <h2>
                 <a href="#\(expectedSectionID)">\(expectedGroupTitle)</a>
@@ -615,7 +615,7 @@ struct MarkdownRenderer_PageElementsTests {
             </section>
             """)
         case .conciseness:
-            #expect(groupedSection.rendered(prettyFormatted: true) == """
+            groupedSection.assertMatches(prettyFormatted: true, expectedXMLString: """
             <h2>\(expectedGroupTitle)</h2>
             <h3>Group title</h3>
             <p>Some description of this group</p>
diff --git a/Tests/DocCHTMLTests/MarkdownRendererTests.swift b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
index cd995f870c..e40569387a 100644
--- a/Tests/DocCHTMLTests/MarkdownRendererTests.swift
+++ b/Tests/DocCHTMLTests/MarkdownRendererTests.swift
@@ -573,9 +573,7 @@ struct MarkdownRendererTests {
             )
         )
         let htmlNodes = Document(parsing: markdownContent, options: .parseSymbolLinks).children.map { renderer.visit($0) }
-        let htmlString = htmlNodes.rendered(prettyFormatted: prettyFormatted)
-        
-        #expect(htmlString == expectedHTML, sourceLocation: sourceLocation)
+        htmlNodes.assertMatches(prettyFormatted: prettyFormatted, expectedXMLString: expectedHTML, sourceLocation: sourceLocation)
     }
     
     private func makeExampleMethodWithDifferentLanguageRepresentations() -> LinkedElement {
@@ -610,7 +608,11 @@ struct MarkdownRendererTests {
 // MARK: Helpers
 
 extension XMLNode {
-    func rendered(prettyFormatted: Bool) -> String {
+    func assertMatches(prettyFormatted: Bool, expectedXMLString: String, sourceLocation: Testing.SourceLocation = #_sourceLocation) {
+        _assertMatches(actualXMLString: rendered(prettyFormatted: prettyFormatted), expectedXMLString: expectedXMLString, sourceLocation: sourceLocation)
+    }
+    
+    fileprivate func rendered(prettyFormatted: Bool) -> String {
         if prettyFormatted {
             xmlString(options: [.nodePrettyPrint, .nodeCompactEmptyElement])
         } else {
@@ -620,19 +622,49 @@ extension XMLNode {
 }
 
 extension Sequence<XMLNode> {
-    func rendered(prettyFormatted: Bool) -> String {
+    func assertMatches(prettyFormatted: Bool, expectedXMLString: String, sourceLocation: Testing.SourceLocation = #_sourceLocation) {
+        _assertMatches(actualXMLString: rendered(prettyFormatted: prettyFormatted), expectedXMLString: expectedXMLString, sourceLocation: sourceLocation)
+    }
+    
+    private func rendered(prettyFormatted: Bool) -> String {
         map { $0.rendered(prettyFormatted: prettyFormatted) }
             .joined(separator: prettyFormatted ? "\n" : "")
     }
 }
 
 extension Sequence<XMLElement> {
-    func rendered(prettyFormatted: Bool) -> String {
+    func assertMatches(prettyFormatted: Bool, expectedXMLString: String, sourceLocation: Testing.SourceLocation = #_sourceLocation) {
+        _assertMatches(actualXMLString: rendered(prettyFormatted: prettyFormatted), expectedXMLString: expectedXMLString, sourceLocation: sourceLocation)
+    }
+    
+    private func rendered(prettyFormatted: Bool) -> String {
         map { $0.rendered(prettyFormatted: prettyFormatted) }
             .joined(separator: prettyFormatted ? "\n" : "")
     }
 }
 
+private func _assertMatches(actualXMLString: String, expectedXMLString: String, sourceLocation: Testing.SourceLocation = #_sourceLocation) {
+    // XMLNode on macOS and Linux pretty print with different indentation.
+    // To compare the XML structure without getting false positive failures because of indentation and other formatting differences,
+    // we explicitly process each string into an easy-to-compare format.
+    func formatForTestComparison(_ xmlString: String) -> String {
+        // This is overly simplified and won't result in "pretty" XML for general use but sufficient for test content comparisons
+        xmlString
+            // Put each tag on its own line
+            .replacingOccurrences(of: ">", with: ">\n")
+            // Remove leading indentation
+            .components(separatedBy: .newlines)
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .joined(separator: "\n")
+            // Explicitly escape a few HTML characters that appear in the test content
+            .replacingOccurrences(of: "–", with: "&#x2013;") // en-dash
+            .replacingOccurrences(of: "—", with: "&#x2014;") // em-dash
+    }
+    
+    #expect(formatForTestComparison(actualXMLString) == formatForTestComparison(expectedXMLString), sourceLocation: sourceLocation)
+}
+
 struct SingleValueLinkProvider: LinkProvider {
     var elementToReturn: LinkedElement?
     func element(for path: URL) -> LinkedElement? {
diff --git a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
index 2fd76076a0..811fa0214e 100644
--- a/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
+++ b/Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift
@@ -183,8 +183,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     ╰─ index.html
         """)
         
-        
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/index.html")), encoding: .utf8)), """
+        try assert(readHTML: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/index.html")), matches: """
         <html>
           <head>
             <meta charset="utf-8" />
@@ -228,7 +227,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </html>
         """)
         
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/someclass/index.html")), encoding: .utf8)), """
+        try assert(readHTML: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/someclass/index.html")), matches: """
         <html>
           <head>
             <meta charset="utf-8" />
@@ -274,7 +273,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </html>
         """)
         
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/someclass/somemethod(with:and:)/index.html")), encoding: .utf8)), """
+        try assert(readHTML: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/someclass/somemethod(with:and:)/index.html")), matches: """
         <html>
           <head>
             <meta charset="utf-8" />
@@ -339,7 +338,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </html>
         """)
         
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/somearticle/index.html")), encoding: .utf8)), """
+        try assert(readHTML: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/somearticle/index.html")), matches: """
         <html>
           <head>
             <meta charset="utf-8" />
@@ -387,6 +386,8 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
 
 }
 
+// MARK: Helpers
+
 private class TestOutputConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
     func consume(renderNode: RenderNode) throws { }
     func consume(assetsInBundle bundle: DocumentationBundle) throws { }
@@ -400,3 +401,30 @@ private class TestOutputConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
     func consume(linkResolutionInformation: SerializableLinkResolutionInformation) throws { }
     func consume(externalRenderNode: ExternalRenderNode) throws { }
 }
+
+private func assert(readHTML: Data, matches expectedHTML: String, file: StaticString = #filePath, line: UInt = #line) {
+    // XMLNode on macOS and Linux pretty print with different indentation.
+    // To compare the XML structure without getting false positive failures because of indentation and other formatting differences,
+    // we explicitly process each string into an easy-to-compare format.
+    func formatForTestComparison(_ xmlString: String) -> String {
+        // This is overly simplified and won't result in "pretty" XML for general use but sufficient for test content comparisons
+        xmlString
+            // Put each tag on its own line
+            .replacingOccurrences(of: ">", with: ">\n")
+            // Remove leading indentation
+            .components(separatedBy: .newlines)
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .joined(separator: "\n")
+            // Explicitly escape a few HTML characters that appear in the test content
+            .replacingOccurrences(of: "–", with: "&#x2013;") // en-dash
+            .replacingOccurrences(of: "—", with: "&#x2014;") // em-dash
+    }
+    
+    XCTAssertEqual(
+        formatForTestComparison(String(decoding: readHTML, as: UTF8.self)),
+        formatForTestComparison(expectedHTML),
+        file: file,
+        line: line
+    )
+}

From 48607e2e197e05c7d4a2148458ec125e8ab374c2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 1 Dec 2025 16:00:40 +0100
Subject: [PATCH 65/68] Prefer using SourceLanguage values over string
 identifiers

---
 .../Model/Rendering/HTML/HTMLRenderer.swift   | 42 +++++++++----------
 1 file changed, 20 insertions(+), 22 deletions(-)

diff --git a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
index 96a0d53b33..de0747c972 100644
--- a/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
@@ -41,8 +41,7 @@ private struct ContextLinkProvider: DocCHTML.LinkProvider {
                // This symbol has multiple unique names
                 let titles = [SourceLanguage: String](
                     titles.map { trait, title in
-                        // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
-                        ((trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift), title)
+                        (trait.sourceLanguage ?? .swift, title)
                     },
                     uniquingKeysWith: { _, new in new }
                 )
@@ -95,8 +94,7 @@ private struct ContextLinkProvider: DocCHTML.LinkProvider {
                 // This symbol has multiple unique names
                 subheadings = .languageSpecificSymbol(.init(
                     allSubheadings.map { trait, subheading in (
-                        // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
-                        key:   (trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift),
+                        key:   trait.sourceLanguage ?? .swift,
                         value: convert(subheading)
                     )},
                     uniquingKeysWith: { _, new in new }
@@ -297,9 +295,8 @@ struct HTMLRenderer {
         } else {
             names = .languageSpecificSymbol([SourceLanguage: String](
                 symbol.titleVariants.allValues.compactMap({ trait, title in
-                    // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
-                    guard let languageID = trait.interfaceLanguage else { return nil }
-                    return (key: SourceLanguage(id: languageID), value: title)
+                    guard let language = trait.sourceLanguage else { return nil }
+                    return (key: language, value: title)
                 }),
                 uniquingKeysWith: { _, new in new }
             ))
@@ -319,12 +316,11 @@ struct HTMLRenderer {
         // Title
         let titleVariants = symbol.titleVariants.allValues.sorted(by: { $0.trait < $1.trait})
         for (trait, variant) in titleVariants {
-            // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
-            guard let lang = trait.interfaceLanguage else { continue }
+            guard let language = trait.sourceLanguage else { continue }
             
             var classes: [String] = []
             if titleVariants.count > 1 {
-                classes.append("\(lang)-only")
+                classes.append("\(language.id)-only")
             }
             if isDeprecated {
                 classes.append("deprecated")
@@ -375,15 +371,14 @@ struct HTMLRenderer {
         if !symbol.declarationVariants.allValues.isEmpty {
             // FIXME: Display platform specific declarations
             
-            var fragmentsByLanguageID = [SourceLanguage: [SymbolGraph.Symbol.DeclarationFragments.Fragment]]()
+            var fragmentsByLanguage = [SourceLanguage: [SymbolGraph.Symbol.DeclarationFragments.Fragment]]()
             for (trait, variant) in symbol.declarationVariants.allValues {
-                // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
-                guard let languageID = trait.interfaceLanguage else { continue }
-                fragmentsByLanguageID[SourceLanguage(id: languageID)] = variant.values.first?.declarationFragments
+                guard let language = trait.sourceLanguage else { continue }
+                fragmentsByLanguage[language] = variant.values.first?.declarationFragments
             }
             
-            if fragmentsByLanguageID.values.contains(where: { !$0.isEmpty }) {
-                hero.addChild( renderer.declaration(fragmentsByLanguageID) )
+            if fragmentsByLanguage.values.contains(where: { !$0.isEmpty }) {
+                hero.addChild( renderer.declaration(fragmentsByLanguage) )
             }
         }
         
@@ -411,8 +406,7 @@ struct HTMLRenderer {
                 renderer.parameters(
                     [SourceLanguage: [MarkdownRenderer<ContextLinkProvider>.ParameterInfo]](
                         symbol.parametersSectionVariants.allValues.map { trait, parameters in (
-                            // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
-                            key:   trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift,
+                            key:   trait.sourceLanguage ?? .swift,
                             value: parameters.parameters.map {
                                 MarkdownRenderer<ContextLinkProvider>.ParameterInfo(name: $0.name, content: $0.contents)
                             }
@@ -429,8 +423,7 @@ struct HTMLRenderer {
                 renderer.returns(
                     .init(
                         symbol.returnsSectionVariants.allValues.map { trait, returnSection in (
-                            // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
-                            key:   trait.interfaceLanguage.map { SourceLanguage(id: $0) } ?? .swift,
+                            key:   trait.sourceLanguage ?? .swift,
                             value: returnSection.content
                         )},
                         uniquingKeysWith: { _, new in new }
@@ -546,8 +539,13 @@ struct HTMLRenderer {
 // Note; this isn't a Comparable conformance because I wanted it to be private to this file.
 private extension DocumentationDataVariantsTrait {
     static func < (lhs: DocumentationDataVariantsTrait, rhs: DocumentationDataVariantsTrait) -> Bool {
-        // FIXME: Use 'sourceLanguage' once https://github.com/swiftlang/swift-docc/pull/1355 is merged
-        (lhs.interfaceLanguage ?? "") < (rhs.interfaceLanguage ?? "")
+        if let lhs = lhs.sourceLanguage {
+            if let rhs = rhs.sourceLanguage {
+                return lhs < rhs
+            }
+            return true // nil is after anything
+        }
+        return false // nil is after anything
     }
 }
 

From 011b1ab749d6165592e84c3d6aa424659a41faca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Tue, 2 Dec 2025 19:39:40 +0100
Subject: [PATCH 66/68] Update file names to match already renamed type

---
 Sources/DocCHTML/CMakeLists.txt                      | 12 +++++++-----
 ...ity.swift => MarkdownRenderer+Availability.swift} |  0
 ...umbs.swift => MarkdownRenderer+Breadcrumbs.swift} |  0
 ...tion.swift => MarkdownRenderer+Declaration.swift} |  0
 ...eters.swift => MarkdownRenderer+Parameters.swift} |  0
 ...+Returns.swift => MarkdownRenderer+Returns.swift} |  0
 ...er+Topics.swift => MarkdownRenderer+Topics.swift} |  0
 7 files changed, 7 insertions(+), 5 deletions(-)
 rename Sources/DocCHTML/{MarkupRenderer+Availability.swift => MarkdownRenderer+Availability.swift} (100%)
 rename Sources/DocCHTML/{MarkupRenderer+Breadcrumbs.swift => MarkdownRenderer+Breadcrumbs.swift} (100%)
 rename Sources/DocCHTML/{MarkupRenderer+Declaration.swift => MarkdownRenderer+Declaration.swift} (100%)
 rename Sources/DocCHTML/{MarkupRenderer+Parameters.swift => MarkdownRenderer+Parameters.swift} (100%)
 rename Sources/DocCHTML/{MarkupRenderer+Returns.swift => MarkdownRenderer+Returns.swift} (100%)
 rename Sources/DocCHTML/{MarkupRenderer+Topics.swift => MarkdownRenderer+Topics.swift} (100%)

diff --git a/Sources/DocCHTML/CMakeLists.txt b/Sources/DocCHTML/CMakeLists.txt
index 41c84f5c46..81059fff5e 100644
--- a/Sources/DocCHTML/CMakeLists.txt
+++ b/Sources/DocCHTML/CMakeLists.txt
@@ -9,11 +9,13 @@ See https://swift.org/LICENSE.txt for license information
 
 add_library(DocCHTML STATIC
   LinkProvider.swift
-  MarkupRenderer+Availability.swift
-  MarkupRenderer+Breadcrumbs.swift
-  MarkupRenderer+Declaration.swift
-  MarkupRenderer+Parameters.swift
-  MarkupRenderer.swift
+  MarkdownRenderer+Availability.swift
+  MarkdownRenderer+Breadcrumbs.swift
+  MarkdownRenderer+Declaration.swift
+  MarkdownRenderer+Parameters.swift
+  MarkdownRenderer+Returns.swift
+  MarkdownRenderer+Topics.swift
+  MarkdownRenderer.swift
   WordBreak.swift
   XMLNode+element.swift)
 target_link_libraries(DocCHTML PUBLIC
diff --git a/Sources/DocCHTML/MarkupRenderer+Availability.swift b/Sources/DocCHTML/MarkdownRenderer+Availability.swift
similarity index 100%
rename from Sources/DocCHTML/MarkupRenderer+Availability.swift
rename to Sources/DocCHTML/MarkdownRenderer+Availability.swift
diff --git a/Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift b/Sources/DocCHTML/MarkdownRenderer+Breadcrumbs.swift
similarity index 100%
rename from Sources/DocCHTML/MarkupRenderer+Breadcrumbs.swift
rename to Sources/DocCHTML/MarkdownRenderer+Breadcrumbs.swift
diff --git a/Sources/DocCHTML/MarkupRenderer+Declaration.swift b/Sources/DocCHTML/MarkdownRenderer+Declaration.swift
similarity index 100%
rename from Sources/DocCHTML/MarkupRenderer+Declaration.swift
rename to Sources/DocCHTML/MarkdownRenderer+Declaration.swift
diff --git a/Sources/DocCHTML/MarkupRenderer+Parameters.swift b/Sources/DocCHTML/MarkdownRenderer+Parameters.swift
similarity index 100%
rename from Sources/DocCHTML/MarkupRenderer+Parameters.swift
rename to Sources/DocCHTML/MarkdownRenderer+Parameters.swift
diff --git a/Sources/DocCHTML/MarkupRenderer+Returns.swift b/Sources/DocCHTML/MarkdownRenderer+Returns.swift
similarity index 100%
rename from Sources/DocCHTML/MarkupRenderer+Returns.swift
rename to Sources/DocCHTML/MarkdownRenderer+Returns.swift
diff --git a/Sources/DocCHTML/MarkupRenderer+Topics.swift b/Sources/DocCHTML/MarkdownRenderer+Topics.swift
similarity index 100%
rename from Sources/DocCHTML/MarkupRenderer+Topics.swift
rename to Sources/DocCHTML/MarkdownRenderer+Topics.swift

From cd0ecb2674f099b9b45d43506ed6d1bfc8a53d87 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 3 Dec 2025 10:42:32 +0100
Subject: [PATCH 67/68] Update Windows CMake file lists

---
 Sources/SwiftDocC/CMakeLists.txt          | 2 ++
 Sources/SwiftDocCUtilities/CMakeLists.txt | 1 +
 2 files changed, 3 insertions(+)

diff --git a/Sources/SwiftDocC/CMakeLists.txt b/Sources/SwiftDocC/CMakeLists.txt
index ff8bbca0e3..ce74f882ea 100644
--- a/Sources/SwiftDocC/CMakeLists.txt
+++ b/Sources/SwiftDocC/CMakeLists.txt
@@ -175,6 +175,8 @@ add_library(SwiftDocC
   Model/Rendering/Diffing/Differences.swift
   Model/Rendering/Diffing/RenderNode+Diffable.swift
   Model/Rendering/DocumentationContentRenderer.swift
+  Model/Rendering/HTML/HTMLContentConsumer.swift
+  Model/Rendering/HTML/HTMLRenderer.swift
   Model/Rendering/LinkTitleResolver.swift
   "Model/Rendering/Navigation Tree/RenderHierarchy.swift"
   "Model/Rendering/Navigation Tree/RenderHierarchyChapter.swift"
diff --git a/Sources/SwiftDocCUtilities/CMakeLists.txt b/Sources/SwiftDocCUtilities/CMakeLists.txt
index c419ba4807..374d6a0f2c 100644
--- a/Sources/SwiftDocCUtilities/CMakeLists.txt
+++ b/Sources/SwiftDocCUtilities/CMakeLists.txt
@@ -14,6 +14,7 @@ add_library(SwiftDocCUtilities STATIC
   Action/Actions/Convert/ConvertAction.swift
   Action/Actions/Convert/ConvertFileWritingConsumer.swift
   Action/Actions/Convert/CoverageDataEntry+generateSummary.swift
+  Action/Actions/Convert/FileWritingHTMLContentConsumer.swift
   Action/Actions/Convert/Indexer.swift
   Action/Actions/Convert/JSONEncodingRenderNodeWriter.swift
   Action/Actions/CoverageAction.swift

From 90a24304097cebc1da22e3e1c51dcc664961b46c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 3 Dec 2025 10:46:39 +0100
Subject: [PATCH 68/68] Copy over Windows CMake workaround from other target's
 CMake file list

---
 Sources/DocCHTML/CMakeLists.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Sources/DocCHTML/CMakeLists.txt b/Sources/DocCHTML/CMakeLists.txt
index 81059fff5e..996b373c4b 100644
--- a/Sources/DocCHTML/CMakeLists.txt
+++ b/Sources/DocCHTML/CMakeLists.txt
@@ -18,6 +18,12 @@ add_library(DocCHTML STATIC
   MarkdownRenderer.swift
   WordBreak.swift
   XMLNode+element.swift)
+target_link_libraries(DocCHTML PRIVATE
+  DocCCommon)
 target_link_libraries(DocCHTML PUBLIC
   SwiftMarkdown::Markdown
   DocC::SymbolKit)
+# FIXME(compnerd) workaround leaking dependencies
+target_link_libraries(SwiftDocC PUBLIC
+  libcmark-gfm
+  libcmark-gfm-extensions)