link to specific title/paragraph of other article

[Saafo]

link to specific title/paragraph of other article

[d-ronnqvist]

This should already work on the main branch although the link syntax is slightly different.

For me locally, the links in this example article resolve to the "Overview" and "Function1" sections:

# Function

## Overview

Two ways to link to this "Overview" section:

- <doc:Overview>
- <doc:Article#Overview>

Two ways to link to the "Function1" "section below:

- <doc:Function1>
- <doc:Article#Function1>

### Function1

Summary1

[Saafo]

@d-ronnqvist Thanks for the reply. But I have some questions:

1. Is this feature being documented on any where? I didn't find this on the Formatting your documentation content | Apple Developer Documentation page.
2. The name of article Article or title name Function1 seems doesn't support i18n, like Chinese. Will it being supported or is there any plan to support this?
3. If I have two titles with the same name "Function1", one is under "Overview" and another under "Topics", how to differentiate the two titles?
4. the link <doc:Article#Function1> seems doesn't support jumping to definition in Xcode markdown editor using control + cmd + click, while <doc:Article> works fine. Is it a bug or a feature which is not implemented yet?

[d-ronnqvist]

• Is this feature being documented on any where? I didn't find this on the Formatting your documentation content | Apple Developer Documentation page.

These changes—and the rest of the main branch—are still in development. The DocC documentation at Swift.org or at developer.apple.com only cover features of DocC that are released on that are in beta.

The Link to Symbols and Other Content subsection of the DocC documentation would be a good page to describe how to link to subsections once this feature is available in a release or in a beta.

• The name of article Article or title name Function1 seems doesn't support i18n, like Chinese. Will it being supported or is there any plan to support this?

Can you tell me more about the behavior you're seeing? Are there any warnings or errors? How does the link appear on the rendered page?

I'm still tracking one bug that behaves like that where the link resolves correctly but still renders as unresolved.

• If I have two titles with the same name "Function1", one is under "Overview" and another under "Topics", how to differentiate the two titles?

That's one tradeoff between the various designs; uniqueness vs brevity.

I suspect that multiple sections with the same title will be comparatively uncommon. Because of this I prefer writing the linked-to heading name directly instead of the paths through the headings to that subheading. The downside of this is that two subheadings have a higher risk of having the same name. Since heading names aren't unique it's also possible—but even less likely in practice—that two subheading with the same name are descendants of two headings with the same name. This means that the full #H1/H2/H3/... paths aren't guaranteed to be unique either.

In the future I could see #345 being used to support giving each heading its own identifier and thus allowing the documentation authors to differentiate between the headings by giving them different identifiers.

• the link <doc:Article#Function1> seems doesn't support jumping to definition in Xcode markdown editor using control + cmd + click, while <doc:Article> works fine. Is it a bug or a feature which is not implemented yet?

Any Xcode behavior is out of scope for this repo.

[Saafo]

These changes—and the rest of the main branch—are still in development. The DocC documentation at Swift.org or at developer.apple.com only cover features of DocC that are released on that are in beta.

Well I've test the link to subsections feature on Xcode 14.2, Swift 5.7.2, and it works. Does this means the feature is already released or partially finished?

Can you tell me more about the behavior you're seeing? Are there any warnings or errors? How does the link appear on the rendered page?

I'm still tracking one bug that behaves like that where the link resolves correctly but still renders as unresolved.

I've test this case on Xcode, there are no warning or errors, when I click the link, it will jump to that page, but can't successfully locate accurately to the subsection. (You can use the Character "中文" to test)

In the future I could see #345 being used to support giving each heading its own identifier and thus allowing the documentation authors to differentiate between the headings by giving them different identifiers.

#345 Seems exact I want! Expecting to that! And thanks for this info!

Any Xcode behavior is out of scope for this repo.

Get it. Bugs on Xcode should file a report. I thought it might related to DocC.