Document how to reference a label in GitHub-flavored Markdown

[TonyGravagno]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax

What part(s) of the article would you like to see updated?

#referencing-issues-and-pull-requests

I propose adding a new section here, "Referencing Labels". This feature is not directly supported by Github, but it is possible in a standard manner with a feature provided by shields.io. For example: is created with image link:
![label: Content](https://img.shields.io/github/labels/github/docs/content)

Documentation: https://shields.io/category/issue-tracking - See and click topic 'GitHub labels'.

Because this is dynamically generated, the color of the image is always accurate at the time of rendering/viewing, not just at the time of text entry. The alt text covers for missing images or communications issues.

As this is a useful and requested feature, I think it would be helpful to add the suggestion to the doc, even if the feature is not built-in to Github itself. If the shields.io service goes away, Github will have much greater issues than this one feature, and the doc can be modified as required.

TY

Additional information

On approval, I'll submit a PR for the new content.

Someone may suggest adding notes about shields for milestones and other features supported by shields.io. I suggest we process this one request first and consider other such requests on their own merits.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[PythonCoderAS]

I don't think this is allowed because shields.io is a third-party service.

[TonyGravagno]

I don't think this is allowed because shields.io is a third-party service.

Thanks for the challenge...

• There's no reason not to reference another site. Other sites are mentioned in these docs for similar purposes.
• In particular, shields.io site is not competitive with Github or Microsoft.
• There is no endorsement or implication of affiliation with a reference to that site.
• That site is non-commercial, publicly supported, and entirely based on the badges/shields FOSS hosted here at Github.
• It's not a volatile link. There are 5.7 million instances in Github public repo code where shields.io is already used for dynamic and static badges. The suggestion here is simply to document the established standard for what people already do, and change it later in the almost certain never to happen scenario where the site changes.
• Microsoft could choose to fork and implement the shields project, and suggest to all that they can get shields from there. A decision had been made not to do that. Given that decision it seems reasonable to support documenting how to use the feature at it exists.
• This doc page documents how to add a dynamic badge for workflow, using data from this site as the source. Because this site doesn't document how to use other dynamic data that is readily available, people in the FOSS community filled the gap. That saved Github/Microsoft some effort and should be rewarded with a reciprocal gesture of recognition. Let's document how to get the data from github.com directly, if it's possible, or, let's document where we know people can use this existing functionality. It's just data.

Ref functionality supported by the Github API, implemented in the badge/shields project FOSS (source for shields.io).

See also the badges/shields PR for this.

Ping @pfaion @calebcartwright

[PythonCoderAS]

@TonyGravagno let me be clear, the issue is describing it enough that it seems to be official. I was thinking something that would be acceptable could be a sentence that just reads "Third-party services like shields.io allow dynamically creating images of repository labels."

[TonyGravagno]

I agree that would be ideal and I will ensure it's presented like this if the enhancement is approved. Thanks.

[janiceilene]

👋 Thanks so much for opening an issue and clearly explaining your reasoning @TonyGravagno! Since this isn't a GitHub feature and is a totally optional thing that users can choose to add if they're interested, we're not going to add it to the docs 💛

Thank you for your interest and passion in improving the GitHub docs! ✨

[styfle]

It seems like GitHub must have a native way to do this because I'm seeing it in this PR: nodejs/node#43310

I'm not seeing this feature documented however so perhaps its beta? 🤔

[PythonCoderAS]

It seems like GitHub must have a native way to do this because I'm seeing it in this PR: nodejs/node#43310

I'm not seeing this feature documented however so perhaps its beta? 🤔

Oh it's simple, just put in a normal link to the label. For example:

https://github.com/github/docs/labels/content

-> content This issue or pull request belongs to the Docs Content team

[styfle]

Cool! I don't see that documented though.

Perhaps it should be added to Autolinked References and URLs

[PythonCoderAS]

Maybe open a different issue for that?

[Sakhilemasina]

is my job application to glassdoor successful?

…

On Fri, 10 Jun 2022, 20:52 Tony Gravagno, ***@***.***> wrote: Code of Conduct - I have read and agree to the GitHub Docs project's Code of Conduct <https://github.com/github/docs/blob/main/CODE_OF_CONDUCT.md> What article on docs.github.com is affected? https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax What part(s) of the article would you like to see updated? #referencing-issues-and-pull-requests <https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#referencing-issues-and-pull-requests> I propose adding a new section here, "Referencing Labels". This feature is not directly supported by Github, but it is possible in a standard manner with a feature provided by shields.io. For example: [image: label: github/docs/labels/content] <https://camo.githubusercontent.com/88ffd2affeb1676fb3f37ddf2e141ad01eaa1cb31f16ab7acf168fcb6c10f642/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6162656c732f6769746875622f646f63732f636f6e74656e74> is created with image link:  Documentation: https://shields.io/category/issue-tracking - See and click topic 'GitHub labels'. Because this is dynamically generated, the color of the image is always accurate at the time of rendering/viewing, not just at the time of text entry. The alt text covers for missing images or communications issues. As this is a useful and requested <isaacs/github#305> feature, I think it would be helpful to add the suggestion to the doc, even if the feature is not built-in to Github itself. If the shields.io service goes away, Github will have much greater issues than this one feature, and the doc can be modified as required. TY Additional information On approval, I'll submit a PR for the new content. Someone may suggest adding notes about shields for milestones and other features supported by shields.io. I suggest we process this one request first and consider other such requests on their own merits. — Reply to this email directly, view it on GitHub <#18537>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AV73JDUVKJGMCHRJUZYWLR3VOOFH3ANCNFSM5YOROTBA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[styfle]

I created #18704