swiftlang / swift-docc

Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.
https://swift.org/documentation/docc
Apache License 2.0
1.19k stars 127 forks source link

Impossible to put same link in body and see also with different title #480

Open a-docc-user opened 1 year ago

a-docc-user commented 1 year ago

Description

Markdown

For more information see the [specification](https://example.com).

## See Also
- [Full Name of the Specification](https://example.com)

Checklist

Expected Behavior

Expected Result

For more information see the specification.

See Also

Actual behavior

Actual Result

For more information see the specification.

See Also

Steps To Reproduce

  1. Put following documentation:
    
    For more information see the [specification](https://example.com).

See Also

Swift-DocC Version Information

Latest Xcode and also master

Swift Compiler Version Information

swift-driver version: 1.62.15 Apple Swift version 5.7.2 (swiftlang-5.7.2.135.5 clang-1400.0.29.51)
Target: arm64-apple-macosx13.0
franklinsch commented 1 year ago

@Kyle-Ye would this be resolved as part of https://github.com/apple/swift-docc/pull/376?

Kyle-Ye commented 1 year ago

Yes, I think this is a duplicate issue of #271.

Kyle-Ye commented 1 year ago

~Yes, I think this is a duplicate issue of #271.~

[Update] After carefully reviewing it again, I found that it is a different issue. The current PR does not solve it.

The reason for this is that current seeAlsoSections implementation only store identifiers of link and then retrieve the title from the references using identifier matching.

"seeAlsoSections": [
    {
        "title": "Related Documentation",
        "identifiers": ["https://example.com", "https://example3.com"]
    }
]

To solve the problem, maybe we should update the seeAlsoSections implementation to store a overrideTitle here to support this feature.

Kyle-Ye commented 1 year ago

I just finish a draft implementation on this, any suggestion on this? @franklinsch