Relaxing structure requirements for Topics sections

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``

Future directions

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.

Implementation

I'd love to hear your feedback about this!

6 Likes

I am in favour of this enhancement. It never quite made sense to me why I had to artificially create a topic group, just to curate items within the navigator.

2 Likes

I think this is a great improvement to the general user-experience of Swift-DocC, especially for folks just learning how to use DocC. It's something a newcomer to Swift-DocC would likely expect to "just work".

Additionally, I think requiring documentation writers to create a topics section title for a page that has a single topic section often leads to redundancy and unnecessary friction in the authoring process. In my opinion, the value in naming topic sections generally only comes when there are multiple topic sections – a single, unnamed topic section can be a great way to add structure to a documentation site.

It would be great to resolve [SR-15543] Support named sections in "See Also" · Issue #203 · apple/swift-docc · GitHub soon as well so that both Topics and See Also sections have parity as far as support for both named and unnamed sections.

Thank you for your work on this! Really excited to see this landing.

1 Like

what does it look like (visually) when you mix heading levels? do the links in the anonymous section get rendered in a larger font than the links in the named sections?

Great question, the only change in this case on the rendering side is that the anonymous section doesn't have a title. There are no font changes. @dhristov attached an a screenshot of that case in his PR: Add support for rendering Topics sections without topic group headings by dobromir-hristov · Pull Request #443 · apple/swift-docc-render · GitHub

1 Like

Thanks everyone, I merged the PR to main.

2 Likes