How-to link to a symbol's topic section?

Development Swift-DocC
1

Hi,

in an article, I'd like to link to a symbol topic section I created with an extension file. Is that possible?

Neither

See the various [initializers](<doc:someClass#initializers>).

nor

See the various [initializers](``someClass#initializers``).

will be correctly resolved/rendered in the browser.

someClass is an existing symbol for which I grouped related functions as a topic section initializers in an extension file:

# someClass

## Topics

### Initializers

- `init(special:)`
- ...
2

Hey @MarcoEidinger - today symbol links are only at the granularity of the entire symbol. There's no extension concept on them to search for subsections within that symbol's page. Same thing happens with full articles - meaning you can't reference sections a specific section within an article either - at least through the the symbol (the double-backtick or doc: structures).

The only way that you might be able to provide something equivalent is to use a full HTML link, but even within that, I'm not confident (I haven't looked) to see if there are section markers included in the HTML generated by Docc-render to allow that to work in most cases.

3

No, linking to topic sections isn't supported today.

It's possible to link to general authored headings using <doc:SomeClass#Heading-name> (or <doc:#Heading-name> if you're linking to a heading on the same page).

We don't document this as a supported feature because it only works for authored headings and not for automatic headings (for example the "Overview" or "Relationships" headings) and not for topic sections (neither authored nor automatic).

This distinction doesn't really make sense to a documentation author—and is really only caused by boring implementation details of how headings and topic sections are modeled differently in the implementation—so we felt that it would cause less confusion to not to document it yet.

It's correct that symbol links only allow you to link to symbols but symbol links and documentation links in DocC also share the same inner syntax so it's possible to write ``SomeClass#Heading-name`` but you'll get a warning and a fix it that replaces the symbol link with <doc:> since a heading isn't a symbol.

I don't know if that's more or less confusing than supporting symbol links to headings on symbol pages. When we're ready to document this as fully supported we'll revisit that warning to see what we want to do about headings in symbol links.

4 Likes
4

Thank you, @ronnqvist (and also @Joseph_Heck) for the detailed response. You confirmed my suspicion that linking to topic sections isn't supported today. Maybe one day .. a developer can dream :slight_smile:

1 Like