Some reference-style markdown links don't render

[natikgadzhi]

Description

Disclaimer: capturing the issue, but I'm still working to capture the details and make a reproduction project.

I was onboarding to swift-syntax, reading the docs, and noticed that on https://swiftpackageindex.com/apple/swift-syntax/main/documentation/swiftsyntax/changingswiftsyntax#Adding-and-Removing-Syntax-Nodes, some links defined with square brackets resolve, but some don't.

For example:

When it is time to commit changes to the Swift Syntax repository, most cases
of adding syntax will require a single PR to swift-syntax. Added
syntactic elements will require corresponding changes to the included
SwiftParser library. For an introduction on parsing Swift nodes, see
[the article on Parsing Basics][ParserBasics].

The last link does not resolve. Here's it's source code. But [Swift Compiler repository][Swiftc] and [swift-stress-tester][swift-stress-tester] resolve just fine.

I actually didn't know [this format of links][is a thing] in Markdown at all — and didn't find anything in Swift-DocC documentaiton about them — so I'm not sure if they are supposed to be supported.

I don't know if this is a swift-docc problem, or swift-docc-render or swift-markdown — and I'm happy to look into it, diagnose, and work on a fix.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

All reference-style links should resolve and render as links, as long as the link URL is provided in the markdown source.

For this source file, all links should render, as they all have valid markdown reference links in the bottom of the source file. https://github.com/apple/swift-syntax/blob/5a914f9c07b4db4984e56bed0964f2518dd0dc1d/Sources/SwiftSyntax/Documentation.docc/Contributing/ChangingSwiftSyntax.md?plain=1#L76

Actual behavior

Several links don't resolve and don't convert to links, leaving [{label}][{url}] format.

Steps To Reproduce

I've reproduced the problem locally on Xcode Version 15.0 beta 4 (15A5195m).

1. Grab swift-syntax repository
2. Open in Xcode
3. Product -> Build documentation
4. The resulting documentation archive also has broken links in the local documentation viewer.

I have NOT yet tried reproducing using:

• Using swift package manager and swift-docc-plugin.
• Using swift-docc from main branch.
• Using an example Playground code using swift-markdown and the example source file from swift-syntax.

I will do that once I have a chance later today or over the weekend.

Swift-DocC Version Information

No response

Swift Compiler Version Information

❯ swiftc --version
swift-driver version: 1.75.2 Apple Swift version 5.8.1 (swiftlang-5.8.0.124.5 clang-1403.0.22.11.100)
Target: arm64-apple-macosx14.0

[ahoppen]

It seems that the key here is an @Comment {} section. If a @Comment section is between the usage of the link and the link’s declaration, it doesn’t get resolved.

E.g.

Renders fine:

[swift-stress-tester][swift-stress-tester]
[swift-stress-tester]: https://github.com/apple/swift-stress-tester
@Comment {}

Doesn’t render correctly

[swift-stress-tester][swift-stress-tester]
@Comment {}
[swift-stress-tester]: https://github.com/apple/swift-stress-tester

[natikgadzhi]

My gut feeling then is that the swift-markdown is doing it's job just fine, but the snippets of text are considered in isolation. I.e. a block of text before @Comment, the comment block itself, and after comment, are processed independently, hence the link in block 1 has no idea how to resolve if its definition is in block 3.

@ethan-kusters, I would love to take a look at how swift-docc is processing documents and work on this, but it probably will eat up some of your time for reviews and guidance. Should I go for it? ;)

[d-ronnqvist]

@ethan-kusters, I would love to take a look at how swift-docc is processing documents and work on this, but it probably will eat up some of your time for reviews and guidance. Should I go for it? ;)

Go for it. If this sounds interesting to you we can help you with questions, guidance, and reviews.