Support local paths in hover MarkdownString

[szotp]

Currently paths to images / links used in hover docs must be absolute, otherwise they will not work. Consider a file main.ts:

/**
 * [link](main.ts)
 */
function main() {
}

If you hover over main and click the link, it will attempt to open /main.ts file, which does not exist.
I think it would be sensible if the behavior was exactly the same as with markdown preview.
Example of file main.md:

[link](main.ts)

Here, clicking the link would properly open the main.ts file, assuming that it's in the same directory.

Here is a project with these two files:
project.zip

[vscodebot]

This feature request is now a candidate for our backlog. The community has 60 days to upvote the issue. If it receives 20 upvotes we will move it to our backlog. If not, we will close it. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[vscodebot]

This feature request has not yet received the 20 community upvotes it takes to make to our backlog. 10 days to go. To learn more about how we handle feature requests, please see our documentation.

Happy Coding

[vscodebot]

This feature request has not yet received the 20 community upvotes it takes to make to our backlog. 10 days to go. To learn more about how we handle feature requests, please see our documentation.

Happy Coding

[vscodebot]

🙂 This feature request received a sufficient number of community upvotes and we moved it to our backlog. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[roblourens]

I'm in the area and this could be useful, but needs API changes. I'd suggest adding a baseUrl to MarkdownString.

export class MarkdownString {

	// ...

	/**
	 * Relative paths in links and images will be resolved relative to this Uri.
	 */
	baseUri?: Uri;

[mjbvz]

Yes I think that would work

This gets tricky on web though. For images, we'd need to first resolve the absolute local path to the image (baseUri + path) and then map that path to a uri that can serve up the image on web

[jrieken]

I'd suggest adding a baseUrl to MarkdownString.

This need good thought... Sure, internally we can make such a change but I have worries wrt the API. We actually don't allow the creation of relative uris (for most common schemes) and we expect the generator of markdown string to have handled this. Wouldn't it be enough to default to the corresponding resource uri when encountering relative uris in markdown?

[zbjornson]

It looks like this is already supposed to work since #18824, but obviously it doesn't.

add a custom link normalizer. If the incoming link has no scheme, try to resolve it relative to the current file or workspace. Links like /file.ext are relative to the workspace, while links like file.ext or ./file.ext are relative to the current file.

[roblourens]

@zbjornson the markdown preview extension which renders markdown in a webview is a different thing from the API we are talking about here. Relative links do still work there.

and we expect the generator of markdown string to have handled this

Maybe - do we expect that the relevant extensions already have to parse/rewrite markdown coming from a jsdoc comment or somewhere else? If so then no problem, if not then it's probably adding some overhead to make them parse all markdown to resolve links.

[tvvignesh]

Was trying this today and it is trying to find the file in /path/ which doesn't exist. Then stumbled across this issue. Would be great to have this so that I can link the file(s) as relevant to a function in the JSDOC.

[baflo]

Are there any updates to this topic or alternative ways to link to non-TS files in jsdoc?

[mjbvz]

Depends on upstream work microsoft/TypeScript#47718

Instead of markdown, I think it would be better to express these file links using JSDoc syntax (this syntax does not exist today)

That way we could update file paths in documentation when you move the linked to file, and also include file link jsdocs in the file all references to file results

[DanTup]

@mjbvz this is effecting other languages than JS/TS, where JSDoc might not make sense (eg. Dart-Code/Dart-Code#2390). Is there a reason markdown can't work?

[mjbvz]

@DanTup See #142051

[sebastian-fredriksson-bernholtz]

Should this be closed? This seems to be working - on Mac OS v14.3.1 VSCode 1.90.1 with all extensions disabled, editor.links not explicitly set.

Screen.Recording.2024-06-19.at.05.25.19.mov