x/pkgsite: serve status badge similar to godoc.org

[icza]

What did you do?

It would be nice to have a badge that can be used on other sites (e.g. github.com) that link to the documentation page of the module / package.

For example, using a URL like this:

https://godoc.org/github.com/icza/bitio?status.svg

Serves an image, a badge which is often used on the package's repository to link to the documentation, like this one:

A similar feature like

https://pkg.go.dev/github.com/icza/bitio?status.svg

Would be useful. Some configuration via URL parameters (like size, color etc) would also be cool.

What did you expect to see?

To have a badge image served similar to godoc.org's response.

What did you see instead?

Request is redirected to https://pkg.go.dev/github.com/icza/bitio?tab=doc and the HTML page is served.

[oliverpool]

I just handcrafted a badge on https://shields.io:

[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/url/of/your-module)

Feel free to tweak the parameters to improve it :-)

The resulting svg could be statically saved somewhere on https://pkg.go.dev (since it is not package dependent).

Edit: use flat-square

[integrii]

I was able to get a nice badge for flaggy with the following code in my README.md (inspired from @oliverpool above):

<a href="https://pkg.go.dev/github.com/integrii/flaggy"> <img src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white"></a>

[julieqiu]

Thanks for the suggestions! Our UX team is working on creating a badge for pkg.go.dev documentation reference.

/cc @fflewddur

[quasilyte]

There are tons of godoc badges out there that lead to a site that is basically deprecated.

Is there a reason not to approve the one @oliverpool provided and make it official so everyone can start the migration?

I'm tempted to use it, but if there will be a new recommended badge after several months it will be quite painful to update all README documents again.

Is there a confirmation that an official badge will be provided? I don't want to sound skeptical, but it seems like the priority for this is very low and it can be delayed for ~infinity. :)

Subjectively, it's better to have a "no, unlikely" answer than "yes, there will be" without any guarantees.

[julieqiu]

An official badge will be provided - our goal is to have one available in the next month.

[lmittmann]

@julieqiu github.com/google/go-cmp is using this shields.io badge which would be a great default badge:

[gopherbot]

Change https://golang.org/cl/241273 mentions this issue: content/static: add badge generation for package authors

[oliverpool]

You can see the rendered version here: https://www.svgviewer.dev/s/SYc1TNlk

[jamalc]

You can now generate a badge here: https://pkg.go.dev/badge. I'll update go.dev/about with instructions.

[jamalc]

🤦 There is a typo in the markdown snippet #40216. I'll post here again once we deploy the fix.

[ryboe]

Thanks, Go team! 👏

You can generate the badge line yourself by following this template:

[![PkgGoDev](https://pkg.go.dev/badge/<MODULE NAME>)](https://pkg.go.dev/<MODULE NAME>)

For example, the badge for my github.com/ryboe/q repo looks like this:

[![PkgGoDev](https://pkg.go.dev/badge/github.com/ryboe/q)](https://pkg.go.dev/github.com/ryboe/q)

[jamalc]

The fix for #40216 is out!

[ostcar]

Thank you for your work!

The description of the form of the badge generator is a bit misleading. The field is called URL so I expected, that a package path with an (https-) schema was requested. It would be nice, if the generator could detect the schema and remove it. Or the field should be renamed to something like package path.

For example I used the URL

https://github.com/ostcar/topic

But correct is

github.com/ostcar/topic

[jamalc]

Hi, ostcar! 👋

Since this issue is closed please file a new issue here where people can discuss. I have a few thoughts on this as well and the work done here is just a starting point to guide building out this feature.

Thank you!