Symbol links with custom authored titles are rendered in code voice

[ethan-kusters]

Description

Symbol links with custom authored titles are rendered in code voice

If I write a doc link with a title like

Check out [this great function](doc:Sloth/eat(_:quantity:)).

the rendered output is

Check out `this great function`.

With this great function in code voice. The custom title should respect the formatting that was provided in the link title.

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.

Swift-DocC Version Information

88d0fd6676f2a2ee2d169d813420645cf6bfd52d

[ethan-kusters]

CC: @Kyle-Ye maybe you're interested in taking a look at this? It looks related to the work for swiftlang/swift-docc#271.

[ethan-kusters]

rdar://108515663

[Kyle-Ye]

CC: @Kyle-Ye maybe you're interested in taking a look at this? It looks related to the work for swiftlang/swift-docc#271.

Sorry @ethan-kusters, I'm not sure what the specific question you raised is. Does it mean that we need to respect the format in the original title, but it is not?

Could you give me an expected behavior and actual behavior (Adding some code snippet or screenshot would be appreciated.)

[Kyle-Ye]

CC: @Kyle-Ye maybe you're interested in taking a look at this? It looks related to the work for swiftlang/swift-docc#271.

Looking at the screenshot of swiftlang/swift-docc#376, I can't see what the problem is for

Check out [this great function](doc:Sloth/eat(_:quantity:)).

[ethan-kusters]

Looking at the screenshot of swiftlang/swift-docc#376, I can't see what the problem is for

Check out [this great function](doc:Sloth/eat(_:quantity:)).

That screenshot demonstrates the issue I believe:

The "Hi" link text in "Check out Hi" is rendered with the default font while the "this great function" link text is rendered in monospace.

Monospace should only be used if the user actually specifies it, for example:

Check out [`this great function`](doc:Sloth/eat(_:quantity:)).

---

So expected behavior for:

Check out [this great function](doc:Sloth/eat(_:quantity:)).

would be seeing that "this great function" rendered with the default styling. Instead, I'm seeing it rendered in monospace code font.

[Kyle-Ye]

Got it. I'll check and try to fix it this weekend.

[Kyle-Ye]

The generated data/documentation/slothcreator.json on swift-docc side is OK.

But the corresponding reference doc://SlothCreator/documentation/SlothCreator/Sloth/eat(_:quantity:) is determined as an internal symbol by swift-docc-render.

https://github.com/apple/swift-docc-render/blob/adadcb3e5784f899720315915640a453da3f11f6/src/components/ContentNode/Reference.vue#L49-L51

So currently swift-docc-render will add "CodeVoice" style to it. "CodeVoice" will use "code" tag defined in "src/styles/base/_typography.scss" which set font-family to mono family.

The same is true before swiftlang/swift-docc#376.

https://github.com/apple/swift-docc-render/blob/adadcb3e5784f899720315915640a453da3f11f6/src/components/ContentNode/ReferenceInternalSymbol.vue#L13-L15
https://github.com/apple/swift-docc-render/blob/adadcb3e5784f899720315915640a453da3f11f6/src/components/ContentNode/CodeVoice.vue#L11-L13
https://github.com/apple/swift-docc-render/blob/adadcb3e5784f899720315915640a453da3f11f6/src/styles/base/_typography.scss#L200-L204

So what would be your expected behaviour? Should 4 and 5 both show non-code style text?

4 [doc:Sloth/eat(_:quantity:)](doc:Sloth/eat(_:quantity:))
5 [this great function](doc:Sloth/eat(_:quantity:))

cc @ethan-kusters

[Kyle-Ye]

TL,DR:
The custom title did respect the formatting that was provided in the link title in swift-docc side(The json content).

But if it was internal symbol, swif-docc-render will add custom css effect to it. Maybe this should fall into a swift-docc-render issue. 🤔️

[ethan-kusters]

I think you're right – DocC-Render should be respecting the formatting provided in the overridingTitleInlineContent value instead of forcing monospace. I'll transfer this there.

[mportiz08]

Sounds reasonable, although I worry a bit about there being an expectation that a link to a symbol would be in code voice by default. I think this is probably the right way to go though since it allows for that flexibility.

I didn't even realize you could provide a custom title for a DocC symbol link now 😮

[Kyle-Ye]

I didn't even realize you could provide a custom title for a DocC symbol link now 😮

This feature is tracked as a bug via swiftlang/swift-docc#271 and implemented by swiftlang/swift-docc#376 @mportiz08