link to specific title/paragraph of other article

[Saafo]

Feature Name

Link to Article Paragraph

Description

• Assume we have two Articles, Sloth.md and Funtion.md
• In Function.md, Outline is like:

# Function

## Overview

Summary

### Function1

Summary1

• ❌ Currently, if we want to insert a link to the Function1 paragraph of Function.md, we have to write this in Sloth.md:

please reference to the part of `Function1` of <doc:Function>.

• ✅ Expected we can jumping to the specific paragraph by:

please reference to <doc:Function/Overview/Function1>

and will be rendered as(or something like this):

please reference to Function#Function1

Motivation

When we describe many functions in Function.md, or we just list three functions, but each function description are very long, it is expected to jump to specific paragraph in the long page.

Importance

We can make articles also have jump-able outlines just like variables or functions in code structs or classes

Alternatives Considered

No response

[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.

[Saafo]

1. The link to subsections works on 6.0.
2. The i18n title doc link is solved by Fix a doc anchor is not encoded correctly #867 .
3. Stable names for headings and internal <doc:> links #345 is a good feature, will tracking it. But with the i18n title issue solved, it's not important as before.