Support linking to authored task groups / topic sections (#842)

* Support linking to topic sections

rdar://78908451

* Fix typo in test data

* Document how to link to headings and task groups

* Add comment about preserving order of anchor sections

Author: d-ronnqvist

Sources/SwiftDocC/Model/DocumentationNode.swift

@@ -107,21 +107,42 @@ public struct DocumentationNode {
         } else if let discussionVariants = (semantic as? Symbol)?.discussionVariants {
             discussionSections = discussionVariants.allValues.map(\.variant)
         } else {
-            return
+            discussionSections = []
+        }
+        
+        anchorSections.removeAll()
+        var seenAnchorTitles = Set<String>()
+        
+        func addAnchorSection(title: String) {
+            // To preserve the order of headings and task groups in the content, we use *both* a `Set` and
+            // an `Array` to ensure unique titles and to accumulate the linkable anchor section elements.
+            guard !title.isEmpty, !seenAnchorTitles.contains(title) else { return }
+            seenAnchorTitles.insert(title)
+            anchorSections.append(
+                AnchorSection(reference: reference.withFragment(title), title: title)
+            )
         }
 
         for discussion in discussionSections {
             for child in discussion.content {
-                // For any non-H1 Heading sections found in the topic's discussion
-                // create an `AnchorSection` and add it to `anchorSections`
-                // so we can index all anchors found in the bundle for link resolution.
                 if let heading = child as? Heading, heading.level > 1 {
-                    anchorSections.append(
-                        AnchorSection(reference: reference.withFragment(heading.plainText), title: heading.plainText)
-                    )
+                    addAnchorSection(title: heading.plainText)
                 }
             }
         }
+        
+        let taskGroups: [TaskGroup]?
+        if let article = semantic as? Article {
+            taskGroups = article.topics?.taskGroups
+        } else if let symbol = semantic as? Symbol {
+            taskGroups = symbol.topics?.taskGroups
+        } else {
+            taskGroups = nil
+        }
+        
+        for taskGroup in taskGroups ?? [] {
+            addAnchorSection(title: taskGroup.heading?.plainText ?? "Topics")
+        }
     }
 
     /// Initializes a documentation node with all its initial values.

Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md

@@ -173,6 +173,13 @@ a colon (`:`), the name of the article, and a greater-than symbol
 <doc:GettingStarted>
 ```
 
+If the article's file name contains whitespace characters, replace each consecutive sequence of whitespace characters with a dash. 
+For example, the link to an article with a file name "Getting Started.md" is
+
+```
+<doc:Getting-Started>
+```
+
 When DocC resolves the link, it uses the article's page title as the link's 
 text, and the article's filename as the link's URL. Links to tutorials follow 
 the same format, except you must add the `/tutorials/` prefix to the path: 
@@ -186,6 +193,41 @@ symbol's path between the colon (`:`) and the terminating greater-than
 symbol (`>`).
 `<doc:Sloth/init(name:color:power:)>`
 
+### Navigate to a Heading or Task Group
+
+To add a link to heading or task group on another page, use a `<doc:>` link to the page and end the link with a hash (`#`) followed by the name of the heading. 
+If the heading text contains whitespace or punctuation characters, replace each consecutive sequence of whitespace characters with a dash and optionally remove the punctuation characters. 
+
+For example, consider this level 3 heading with a handful of punctuation characters:
+
+```
+### (1) "Example": Sloth's diet.
+```
+
+A link to this heading can either include all the punctuation characters from the heading text or remove some or all of the punctuation characters.
+
+```
+<doc:OtherPage#(1)-"Example":-Sloth's-diet.>
+<doc:OtherPage#1-Example-Sloths-diet>
+```
+
+> Note:
+> Links to headings or task groups on symbol pages use `<doc:>` syntax. 
+
+To add a link to heading or task group on the current page, use a `<doc:>` link that starts with the name of the heading. If you prefer you can include the hash (`#`) prefix before the heading name. For example, both these links resolve to a heading named "Some heading title" on the current page:
+
+```
+<doc:#Some-heading-title>
+<doc:Some-heading-title>
+```
+
+If a task group is empty or none of its links resolve successfully, it's not possible to link to that task group because it will be omitted from the rendered page. Linking to generated per-symbol-kind task groups is not supported.
+
+> Earlier Versions:
+> Before Swift-DocC 6.0, links to task groups isn't supported. The syntax above only works for links to general headings.
+>
+> Before Swift-DocC 5.9, links to same-page headings don't support a leading hash (`#`) character.
+
 ### Include web links
 
 To include a regular web link, add a set of brackets (`[]`) and 

Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift

@@ -12,7 +12,7 @@ import XCTest
 import SymbolKit
 @testable import SwiftDocC
 import Markdown
-import SwiftDocCTestUtilities
+@_spi(FileManagerProtocol) import SwiftDocCTestUtilities
 
 func diffDescription(lhs: String, rhs: String) -> String {
     let leftLines = lhs.components(separatedBy: .newlines)
@@ -905,7 +905,7 @@ class DocumentationContextTests: XCTestCase {
         XCTAssertEqual(myProtocolSymbol.topics?.taskGroups.first?.heading?.detachedFromParent.debugDescription(),
                         """
                         Heading level: 3
-                        └─ Text "Task Group Excercising Symbol Links"
+                        └─ Text "Task Group Exercising Symbol Links"
                         """)
         XCTAssertEqual(myProtocolSymbol.topics?.taskGroups.first?.links.count, 3)
         XCTAssertEqual(myProtocolSymbol.topics?.taskGroups.first?.links[0].destination, "doc://com.example.documentation/documentation/MyKit/MyClass")
@@ -2986,7 +2986,7 @@ let expected = """
         XCTAssertEqual(taskGroup.links.count, 16)
 
         XCTAssertEqual(node.anchorSections.first?.title, "Overview")
-        for (index, anchor) in node.anchorSections.dropFirst().enumerated() {
+        for (index, anchor) in node.anchorSections.dropFirst().dropLast().enumerated() {
             XCTAssertEqual(taskGroup.links.dropFirst(index * 2 + 0).first?.destination, anchor.reference.absoluteString)
             XCTAssertEqual(taskGroup.links.dropFirst(index * 2 + 1).first?.destination, anchor.reference.absoluteString)
         }
@@ -2995,11 +2995,141 @@ let expected = """
         XCTAssertEqual(node.anchorSections.dropFirst(2).first?.reference.absoluteString, "doc://com.test.docc/documentation/article#Apostrophe-firsts-second")
         XCTAssertEqual(node.anchorSections.dropFirst(3).first?.reference.absoluteString, "doc://com.test.docc/documentation/article#Prime-firsts-second")
 
-        XCTAssertEqual(node.anchorSections.dropLast(2).last?.reference.absoluteString, "doc://com.test.docc/documentation/article#Em-dash-first-second")
-        XCTAssertEqual(node.anchorSections.dropLast().last?.reference.absoluteString, "doc://com.test.docc/documentation/article#Triple-hyphen-first-second")
-        XCTAssertEqual(node.anchorSections.last?.reference.absoluteString, "doc://com.test.docc/documentation/article#Emoji-%F0%9F%92%BB")
+        XCTAssertEqual(node.anchorSections.dropLast(3).last?.reference.absoluteString, "doc://com.test.docc/documentation/article#Em-dash-first-second")
+        XCTAssertEqual(node.anchorSections.dropLast(2).last?.reference.absoluteString, "doc://com.test.docc/documentation/article#Triple-hyphen-first-second")
+        XCTAssertEqual(node.anchorSections.dropLast().last?.reference.absoluteString, "doc://com.test.docc/documentation/article#Emoji-%F0%9F%92%BB")
     }
 
+    func testResolvingLinksToTopicSections() throws {
+        let fileSystem = try TestFileSystem(folders: [
+            Folder(name: "unit-test.docc", content: [
+                JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(moduleName: "ModuleName")),
+                
+                TextFile(name: "ModuleName.md", utf8Content: """
+                # ``ModuleName``
+                
+                A symbol with two topic section
+                
+                ## Topics
+                
+                ### One
+                
+                - <doc:First>
+                
+                ### Two
+                
+                - <doc:Second>
+                """),
+                
+                TextFile(name: "First.md", utf8Content: """
+                # The first article
+                
+                An article with a top-level topic section
+                
+                ## Topics
+                
+                - <doc:Third>
+                """),
+                
+                TextFile(name: "Second.md", utf8Content: """
+                # The second article
+                
+                An article with a named topic section
+                
+                ## Topics
+                
+                ### Some topic section
+                
+                - <doc:Third>
+                """),
+                
+                TextFile(name: "Third.md", utf8Content: """
+                # The third article
+                
+                An article that links to the various topic sections
+                
+                - <doc:ModuleName#One>
+                - <doc:ModuleName#Two>
+                - <doc:First#Topics>
+                - <doc:Second#Some-topic-section>
+                - <doc:Third#Another-topic-section>
+                - <doc:#Another-topic-section>
+                
+                ## Topics
+                
+                ### Another topic section
+                
+                - <doc:Fourth>
+                """),
+                
+                TextFile(name: "Fourth.md", utf8Content: """
+                # The fourth article
+                
+                An article that only exists to be linked to
+                """),
+            ])
+        ])
+        
+        let workspace = DocumentationWorkspace()
+        let context = try DocumentationContext(dataProvider: workspace)
+        try workspace.registerProvider(fileSystem)
+        
+        XCTAssert(context.problems.isEmpty, "Unexpected problems: \(context.problems.map(\.diagnostic.summary).sorted())")
+        
+        let reference = try XCTUnwrap(context.knownPages.first(where: { $0.lastPathComponent == "Third" }))
+        let entity = try context.entity(with: reference)
+        
+        struct LinkAggregator: MarkupWalker {
+            var destinations: [String] = []
+            
+            mutating func visitLink(_ link: Link) -> () {
+                if let destination = link.destination {
+                    destinations.append(destination)
+                }
+            }
+            mutating func visitSymbolLink(_ symbolLink: SymbolLink) -> () {
+                if let destination = symbolLink.destination {
+                    destinations.append(destination)
+                }
+            }
+        }
+        
+        // Verify that the links are resolved in the in-memory model
+        
+        var linkAggregator = LinkAggregator()
+        let list = try XCTUnwrap((entity.semantic as? Article)?.discussion?.content.first as? UnorderedList)
+        linkAggregator.visit(list)
+        
+        XCTAssertEqual(linkAggregator.destinations, [
+            "doc://unit-test/documentation/ModuleName#One",
+            "doc://unit-test/documentation/ModuleName#Two",
+            "doc://unit-test/documentation/unit-test/First#Topics",
+            "doc://unit-test/documentation/unit-test/Second#Some-topic-section",
+            "doc://unit-test/documentation/unit-test/Third#Another-topic-section",
+            "doc://unit-test/documentation/unit-test/Third#Another-topic-section",
+        ])
+        
+        // Verify that the links are resolved in the render model.
+        let bundle = try XCTUnwrap(context.registeredBundles.first)
+        let converter = DocumentationNodeConverter(bundle: bundle, context: context)
+        let renderNode = try converter.convert(entity, at: nil)
+        
+        let overviewSection = try XCTUnwrap(renderNode.primaryContentSections.first as? ContentRenderSection)
+        guard case .unorderedList(let unorderedList) = overviewSection.content.dropFirst().first else {
+            XCTFail("The first element of the Overview section (after the heading) should be an unordered list")
+            return
+        }
+        
+        XCTAssertEqual(unorderedList.items.map(\.content.firstParagraph.first), [
+            .reference(identifier: RenderReferenceIdentifier("doc://unit-test/documentation/ModuleName#One"), isActive: true, overridingTitle: nil, overridingTitleInlineContent: nil),
+            .reference(identifier: RenderReferenceIdentifier("doc://unit-test/documentation/ModuleName#Two"), isActive: true, overridingTitle: nil, overridingTitleInlineContent: nil),
+            .reference(identifier: RenderReferenceIdentifier("doc://unit-test/documentation/unit-test/First#Topics"), isActive: true, overridingTitle: nil, overridingTitleInlineContent: nil),
+            .reference(identifier: RenderReferenceIdentifier("doc://unit-test/documentation/unit-test/Second#Some-topic-section"), isActive: true, overridingTitle: nil, overridingTitleInlineContent: nil),
+            .reference(identifier: RenderReferenceIdentifier("doc://unit-test/documentation/unit-test/Third#Another-topic-section"), isActive: true, overridingTitle: nil, overridingTitleInlineContent: nil),
+            .reference(identifier: RenderReferenceIdentifier("doc://unit-test/documentation/unit-test/Third#Another-topic-section"), isActive: true, overridingTitle: nil, overridingTitleInlineContent: nil),
+        ])
+    }
+    
     func testWarnOnMultipleMarkdownExtensions() throws {
         let fileContent = """
         # ``MyKit/MyClass/myFunction()``

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

@@ -1111,6 +1111,14 @@ class PathHierarchyTests: XCTestCase {
         let articleID = try tree.find(path: "/Test-Bundle/Default-Code-Listing-Syntax", onlyFindSymbols: false)
         XCTAssertNil(tree.lookup[articleID]!.symbol)
         XCTAssertEqual(tree.lookup[articleID]!.name, "Default-Code-Listing-Syntax")
+        
+        let modulePageTaskGroupID = try tree.find(path: "/MyKit#Extensions-to-other-frameworks", onlyFindSymbols: false)
+        XCTAssertNil(tree.lookup[modulePageTaskGroupID]!.symbol)
+        XCTAssertEqual(tree.lookup[modulePageTaskGroupID]!.name, "Extensions-to-other-frameworks")
+        
+        let symbolPageTaskGroupID = try tree.find(path: "/MyKit/MyProtocol#Task-Group-Exercising-Symbol-Links", onlyFindSymbols: false)
+        XCTAssertNil(tree.lookup[symbolPageTaskGroupID]!.symbol)
+        XCTAssertEqual(tree.lookup[symbolPageTaskGroupID]!.name, "Task-Group-Exercising-Symbol-Links")
     }
 
     func testMixedLanguageFramework() throws {
@@ -1755,6 +1763,105 @@ class PathHierarchyTests: XCTestCase {
         XCTAssertEqual(paths[memberID], "/ModuleName/ContainerName-qwwf/MemberName1")
     }
 
+    func testLinkToTopicSection() throws {
+        let exampleDocumentation = Folder(name: "unit-test.docc", content: [
+            JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
+                moduleName: "ModuleName",
+                symbols: [
+                    ("some-symbol-id", .swift, ["SymbolName"]),
+                ],
+                relationships: []
+            )),
+            
+            TextFile(name: "ModuleName.md", utf8Content: """
+            # ``ModuleName``
+            
+            A module with some named topic sections
+            
+            ## Other level 2 heading
+            
+            Some content
+            
+            ### Other level 3 heading
+            
+            Some more content
+            
+            ## Topics
+            
+            ### My classes
+            
+            - ``SymbolName``
+            
+            ### My articles
+            
+            - <doc:Article>
+            """),
+            
+            TextFile(name: "Article.md", utf8Content: """
+            # Some Article
+            
+            An article with a top-level topic section
+            
+            ## Topics
+            
+            - ``SymbolName``
+            """)
+        ])
+        
+        let tempURL = try createTempFolder(content: [exampleDocumentation])
+        let (_, _, context) = try loadBundle(from: tempURL)
+        let tree = context.linkResolver.localResolver.pathHierarchy
+        
+        print(tree.dump())
+        
+        let moduleID = try tree.find(path: "/ModuleName", onlyFindSymbols: true)
+        // Relative link from the module to a topic section
+        do {
+            let topicSectionID = try tree.find(path: "#My-classes", parent: moduleID, onlyFindSymbols: false)
+            let node = try XCTUnwrap(tree.lookup[topicSectionID])
+            XCTAssertNil(node.symbol)
+            XCTAssertEqual(node.name, "My-classes")
+        }
+        
+        // Absolute link to a topic section on the module page
+        do {
+            let topicSectionID = try tree.find(path: "/ModuleName#My-classes", parent: nil, onlyFindSymbols: false)
+            let node = try XCTUnwrap(tree.lookup[topicSectionID])
+            XCTAssertNil(node.symbol)
+            XCTAssertEqual(node.name, "My-classes")
+        }
+        
+        // Absolute link to a heading on the module page
+        do {
+            let headingID = try tree.find(path: "/ModuleName#Other-level-2-heading", parent: nil, onlyFindSymbols: false)
+            let node = try XCTUnwrap(tree.lookup[headingID])
+            XCTAssertNil(node.symbol)
+            XCTAssertEqual(node.name, "Other-level-2-heading")
+        }
+        
+        // Relative link to a heading on the module page
+        do {
+            let headingID = try tree.find(path: "#Other-level-3-heading", parent: moduleID, onlyFindSymbols: false)
+            let node = try XCTUnwrap(tree.lookup[headingID])
+            XCTAssertNil(node.symbol)
+            XCTAssertEqual(node.name, "Other-level-3-heading")
+        }
+        
+        // Relative link to a top-level topic section on another page
+        do {
+            let topicSectionID = try tree.find(path: "Article#Topics", parent: moduleID, onlyFindSymbols: false)
+            let node = try XCTUnwrap(tree.lookup[topicSectionID])
+            XCTAssertNil(node.symbol)
+            XCTAssertEqual(node.name, "Topics")
+        }
+        
+        let paths = tree.caseInsensitiveDisambiguatedPaths(includeDisambiguationForUnambiguousChildren: true)
+        XCTAssertEqual(paths.values.sorted(), [
+            "/ModuleName",
+            "/ModuleName/SymbolName",
+        ], "The hierarchy only computes paths for symbols, not for headings or topic sections")
+    }
+    
     func testModuleAndCollidingTechnologyRootHasPathsForItsSymbols() throws {
         let symbolID = "some-symbol-id"