Currently, DocC requires links in Topics sections to be grouped into topic groups, which are specified using level-3 headings:
## Topics ### My Topic Group - ``MyStruct`` - ``MyClass``
I'd like to propose no longer requiring writing level-3 headings in order to write links in Topics sections:
## Topics - ``MyStruct`` - ``MyClass``
This is supported in See Also sections, so it makes sense to bring the behavior to Topics sections as well. I see this as being particularly useful for pages that don't curate many symbols, where a topic group name that makes sense is not obvious.
On the rendering side, you'll just see the links without the topic groups headings, so the example above would render as:
You're still able to declare topic groups using level-3 headings after the first block of links, if you wish, and they get rendered the same way they currently do:
## Topics - ``MyStruct`` ### My Topic Group - ``MyClass``
Currently, See Also sections are authored without level-3 headings and their links are automatically grouped by DocC in a section called 'Related Documentation'. It would make sense to implement the reverse of this proposal as a future direction, i.e., to allow authoring titled groups in See Also sections.
- DocC compiler PR: Add support for defining Topics sections without topic group headings by franklinsch · Pull Request #393 · apple/swift-docc · GitHub
- DocC-Render PR (thanks @dhristov!): Add support for rendering Topics sections without topic group headings by dobromir-hristov · Pull Request #443 · apple/swift-docc-render · GitHub
I'd love to hear your feedback about this!