CC @pjweinb

Thank you for the report. I agree we should fix those links.

There are several different things going on in the example, some of which we can fix.

1. The reason [absolute markdown links] doesn't work is that the block containing its definition is not recognized as a link definition block, because #Example is not recognized as a URL. Removing that line produces links for [absolute markdown links]
2. We can generate pkg.go.dev links for fmt.Println and fmt.
3. go doc does not seem to generate any kind of link for [Block]. What link might be generated, remembering that links are to URLs? ('go to definition' isn't implemented by a URL)

I don't think it matters, but vscode does not implement the same version of markdown as GitHub.

Change https://go.dev/cl/469715 mentions this issue: gopls/hove: add documentation links to hover

1. The reason [absolute markdown links] doesn't work is that the block containing its definition is not recognized as a link definition block, because #Example is not recognized as a URL. Removing that line produces links for [absolute markdown links]

Is this expected behavior? I would think it should be possible to link to another anchor on the same page in the generated docs for https://pkg.go.dev (for example, something in fmt might link to #hdr-Printing or #example-Stringer)? I guess maybe this deserves a separate issue for go doc and/or pkgsite, since that behavior would determine how gopls should behave?

3. go doc does not seem to generate any kind of link for [Block]. What link might be generated, remembering that links are to URLs? ('go to definition' isn't implemented by a URL)

This is a good point — in the context of the editor, "go to definition" would be convenient, but linking to https://pkg.go.dev for the current package would probably also work for packages that have docs published there. I would expect that https://pkg.go.dev normally generates these as URL fragments like mentioned above, but in the editor that wouldn't work as expected.

I looked into how another language server I use implemented "go to definition" for this particular use case, and it looks like they use a nonstandard LSP extension to provide the client with a clickable "go to definition" command 😞. So I guess short of implementing something like that, just using https://pkg.go.dev is probably the most reasonable option.

It is expected behavior. from tip.golang.org/doc/comment A span of unindented non-blank lines defines link targets when every line is of the form “[Text]: URL”.

Hmm, I guess more precisely what I meant was: is it expected that #Example is not recognized as a URL?

I guess technically it is a URI but not a URL (according to RFCs 3986 and 1738), but I think common usage would indicate that fragments can be considered as URLs (in fact, in the docs you linked the href attribute is used as an example of the ways these URLs can be used. <a href="#frag"> is a fairly common usage of this attribute).

All that to say — if fragments like this are never intended to be supported, then perhaps the documentation should be updated to explicitly indicate this (something like relative URLs without a scheme are not supported, or just an explicit mention of what definition is being used for "URL").

Or, if these kinds of links should be supported, then perhaps the behavior of go doc and gopls should be adjusted to support them.