Repository: apple/swift-docc (swift)

Issue:
Unresolved H4 links
In some places, TSPL links to a H4 as an anchor point — for example:

```
// In Statements.md
#### Switching Over Future Enumeration Cases

// In Attributes.md and RevisionHistory.md
<doc:Statements#Switching-Over-Future-Enumeration-Cases>
```

However, swift-docc currently only supports H1, H2 and H3 as an anchor to reference.

https://github.com/apple/swift-docc/blob/5fe2d1331eba2243163366e4d25259b86a44e5db/Sources/SwiftDocC/Model/DocumentationNode.swift#L113-L124

Should we update the structure of content in this repo or should this be a feature/bug on swift-docc to be fixed?

If we are going to fix it on swift-docc, should we add a flag to let the consumer decide which heading level we should add as anchor or just extend it to level 4?

Pull request:
Bug/issue #, if applicable:

Close https://github.com/apple/swift-book/issues/36

## Summary

Relaxing requirement of anchorSection for headings.

Swift DocC originally only support H2 and H3 for anchor section.

After this MR, it will expand into all non-H1 headings.

See discussion at https://github.com/apple/swift-book/issues/36#issuecomment-1272955489

## Dependencies

None

## Testing

1. See DocumentationNodeTests.swift

2. Screenshots
Before this PR:

![SCR-20221011-131](https://user-images.githubusercontent.com/43724855/194918471-74d76a06-3733-4e6a-ac2c-7534ed78b164.png)

After this PR:

![SCR-20221011-12o](https://user-images.githubusercontent.com/43724855/194918531-81bb2b2f-4932-4d3a-95c3-398d236f67db.png)

## Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

- [x] Added tests
- [x] Ran the `./bin/test` script and it succeeded
- [x] Updated documentation if necessary

Patch:
diff --git a/Sources/SwiftDocC/Model/DocumentationNode.swift b/Sources/SwiftDocC/Model/DocumentationNode.swift
index 84b289ac44..a6856a02dc 100644
--- a/Sources/SwiftDocC/Model/DocumentationNode.swift
+++ b/Sources/SwiftDocC/Model/DocumentationNode.swift
@@ -112,10 +112,10 @@ public struct DocumentationNode {
         
         for discussion in discussionSections {
             for child in discussion.content {
-                // For any H2/H3 sections found in the topic's discussion
+                // 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, heading.level < 4 {
+                if let heading = child as? Heading, heading.level > 1 {
                     anchorSections.append(
                         AnchorSection(reference: reference.withFragment(heading.plainText), title: heading.plainText)
                     )


Test patch:
diff --git a/Tests/SwiftDocCTests/Model/DocumentationNodeTests.swift b/Tests/SwiftDocCTests/Model/DocumentationNodeTests.swift
new file mode 100644
index 0000000000..b3f3ff9951
--- /dev/null
+++ b/Tests/SwiftDocCTests/Model/DocumentationNodeTests.swift
@@ -0,0 +1,44 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 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
+@testable import SwiftDocC
+import XCTest
+
+class DocumentationNodeTests: XCTestCase {
+    func testH4AndUpAnchorSections() throws {
+        let articleSource = """
+        # Title
+
+        ## Heading2
+
+        ### Heading3
+        
+        #### Heading4
+        
+        ##### Heading5
+
+        ###### Heading6
+        """
+        
+        let article = Article(markup: Document(parsing: articleSource, options: []), metadata: nil, redirects: nil, options: [:])
+        let node = try DocumentationNode(
+            reference: ResolvedTopicReference(bundleIdentifier: "org.swift.docc", path: "/blah", sourceLanguage: .swift),
+            article: article
+        )
+        XCTAssertEqual(node.anchorSections.count, 5)
+        for (index, anchorSection) in node.anchorSections.enumerated() {
+            let expectedTitle = "Heading\(index + 2)"
+            XCTAssertEqual(anchorSection.title, expectedTitle)
+            XCTAssertEqual(anchorSection.reference, node.reference.withFragment(expectedTitle))
+        }
+    }
+}