Unresolved H4 links

[Kyle-Ye]

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?

[Kyle-Ye]

cc @franklinsch

[krilnon]

It's probably worth at least asking whether DocC might want to support > H3 heading anchors, especially given our focus here on longer-form content where it's more likely that content will have headings with more depth.

[Kyle-Ye]

It's probably worth at least asking whether DocC might want to support > H3 heading anchors, especially given our focus here on longer-form content where it's more likely that content will have headings with more depth.

I'm +1 for support "> H3 heading anchors" (Whether by default or via a flag)

What's your opinion on this? Or we could make some discussion on tomorrow's meeting @franklinsch

[Kyle-Ye]

What's your opinion on this? Or we could make some discussion on tomorrow's meeting @franklinsch

Ping @franklinsch

[franklinsch]

Sorry I missed this. Supporting links to >h3 makes sense to me!

[Kyle-Ye]

After #403 is merged, there will only 1 warning left for swift-book 👇

Input: /Users/kyle/Workspace/Github/swift-docc-project/swift-book/Sources/TSPL/TSPL.docc
Template: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../share/docc/render
/Users/kyle/Workspace/Github/swift-docc-project/swift-book/Sources/TSPL/TSPL.docc/LanguageGuide/AdvancedOperators.md:5:43: warning: Link in document summary will not be displayed
Summary should only contain (formatted) text. To resolve this issue, place links and images elsewhere in the document, or remove them.
========================================
Starting Local Preview Server
	 Address: http://localhost:8080/
========================================

Which is tracked by #1

[amartini51]

Thanks @Kyle-Ye! Confirmed that the H4 link in the revision history works now.

Before:

After: