Fix a doc anchor is not encoded correctly (#867)

* Fix a doc anchor is not encoded correctly

* Add a test for rendering heading anchors

* Pass stored unencoded fragment

* Remove the unsuitable test case

Also apply suggestions from code review.

* Apply suggestions from code review

* Treat a link destination as the "authored link"

* Revert "Treat a link destination as the "authored link""

This reverts commit 4e3f8da.

* Mark the test article as a technology root

Author: hironytic

Sources/SwiftDocC/Infrastructure/NodeURLGenerator.swift

@@ -171,7 +171,7 @@ public struct NodeURLGenerator {
             )
         } else {
             let url = baseURL.appendingPathComponent(safePath, isDirectory: false)
-            return url.withFragment(reference.url.fragment)
+            return url.withFragment(reference.fragment)
         }
     }
 

Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

@@ -51,7 +51,7 @@ struct RenderContentCompiler: MarkupVisitor {
     }
 
     mutating func visitHeading(_ heading: Heading) -> [RenderContent] {
-        return [RenderBlockContent.heading(.init(level: heading.level, text: heading.plainText, anchor: urlReadableFragment(heading.plainText)))]
+        return [RenderBlockContent.heading(.init(level: heading.level, text: heading.plainText, anchor: urlReadableFragment(heading.plainText).addingPercentEncoding(withAllowedCharacters: .urlFragmentAllowed)))]
     }
 
     mutating func visitListItem(_ listItem: ListItem) -> [RenderContent] {

Tests/SwiftDocCTests/Model/RenderContentMetadataTests.swift

@@ -297,4 +297,24 @@ class RenderContentMetadataTests: XCTestCase {
             default: XCTFail("Unexpected element")
         }
     }
+    
+    func testHeadingAnchorShouldBeEncoded() throws {
+        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        var renderContentCompiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleIdentifier: bundle.identifier, path: "/path", fragment: nil, sourceLanguage: .swift))
+        
+        let source = """
+        ## テスト
+        """
+        let document = Document(parsing: source)
+        
+        let result = try XCTUnwrap(renderContentCompiler.visit(document.child(at: 0)!))
+        let element = try XCTUnwrap(result.first as? RenderBlockContent)
+        switch element {
+        case .heading(let heading):
+            XCTAssertEqual(heading.level, 2)
+            XCTAssertEqual(heading.text, "テスト")
+            XCTAssertEqual(heading.anchor, "%E3%83%86%E3%82%B9%E3%83%88", "The UTF-8 representation of テスト is E3 83 86 E3 82 B9 E3 83 88")
+        default: XCTFail("Unexpected element")
+        }
+    }
 }

Tests/SwiftDocCTests/Rendering/HeadingAnchorTests.swift

@@ -0,0 +1,63 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2024 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 SwiftDocCTestUtilities
+
+class HeadingAnchorTests: XCTestCase {
+    func testEncodeHeadingAnchor() throws {
+        let catalogURL = try createTempFolder(content: [
+            Folder(name: "unit-test.docc", content: [
+                TextFile(name: "Root.md", utf8Content: """
+                # My root page
+                
+                This single article defines two headings and links to them
+                
+                @Metadata {
+                  @TechnologyRoot
+                }
+
+                ### テスト
+                - <doc:#テスト>
+                
+                ### Some heading
+                - <doc:#Some-heading>
+                """),
+            ])
+        ])
+        let (_, bundle, context) = try loadBundle(from: catalogURL)
+        
+        let reference = try XCTUnwrap(context.soleRootModuleReference)
+        let node = try context.entity(with: reference)
+        let renderContext = RenderContext(documentationContext: context, bundle: bundle)
+        let converter = DocumentationContextConverter(bundle: bundle, context: context, renderContext: renderContext)
+        let renderNode = try XCTUnwrap(converter.renderNode(for: node, at: nil))
+
+        // Check heading anchors are encoded
+        let contentSection = try XCTUnwrap(renderNode.primaryContentSections.first as? ContentRenderSection)
+        let headings: [RenderBlockContent.Heading] = contentSection.content.compactMap {
+            if case .heading(let heading) = $0 {
+                return heading
+            } else {
+                return nil
+            }
+        }
+        XCTAssertEqual(headings[0].anchor, "%E3%83%86%E3%82%B9%E3%83%88")
+        XCTAssertEqual(headings[1].anchor, "Some-heading")
+        
+        // Check links to them
+        let testTopic0 = try XCTUnwrap(renderNode.references["doc://unit-test/documentation/Root#%E3%83%86%E3%82%B9%E3%83%88"] as? TopicRenderReference)
+        XCTAssertEqual(testTopic0.url, "/documentation/root#%E3%83%86%E3%82%B9%E3%83%88")
+        let testTopic1 = try XCTUnwrap(renderNode.references["doc://unit-test/documentation/Root#Some-heading"] as? TopicRenderReference)
+        XCTAssertEqual(testTopic1.url, "/documentation/root#Some-heading")
+    }
+}