Generate URLs for shields.io metadata badges—typically used in repository READMEs—using R.
Installation
You can install {badgr} from R-universe with:
install.packages("badgr", repos = "https://matt-dray.r-universe.dev")Please file an issue with your ideas or to report bugs.
Examples
- Simple: bare bones functionality
- More complex: introducing a logo and changing the style
- Custom logo: adding your own logo
- A CRAN package DOI badge
1. Simple
This is a basic example that shows you how to generate the simplest possible badge.
library(badgr)
badge <- get_badge(
"Left bit", "Right bit", "blue",
to_clipboard = FALSE, # don't copy to clipboard
browser_preview = FALSE # don't send to browser
)The output looks like this:
badge
#> [1] "https://img.shields.io/badge/Left_bit-Right_bit-blue?style=flat"Which looks like this when rendered in your README file:
2. More complex
Let’s use a few more arguments. For example, we can include a pre-prepared logo from Simple Icons and provide a link that will be added to the Markdown, so clicking the badge will take you to that site.
get_badge(
label = "Left bit",
message = "Right bit",
color = "red",
style = "for-the-badge", # default was 'flat'
label_color = "blue", # colour for the left side
md_link = "https://shields.io", # include a link in the Markdown
logo_simple = "RStudio", # a simpleicons.org logo
logo_color = "white", # a color for that logo
logo_width = 20, # pad width around logo
browser_preview = FALSE,
to_clipboard = FALSE
)
#> [1] "[](https://shields.io)"Which looks like this:
Clicking it will take you to the link specified by the md_link argument.
3. Custom logo
What if you don’t want to use a logo from Simple Icons? You can use your own. Here, for example, I’m using a small gif of the logo from my blog.
# Path to custom logo
logo <- "https://raw.githubusercontent.com/matt-dray/rostrum-blog/master/static/images/favicon.gif"
get_badge(
label = "rostrum.blog",
message = "post",
color = "008900", # color can be supplied as hex
label_color = "black",
md_link = "https://www.rostrum.blog/",
logo_path = logo,
browser_preview = FALSE,
to_clipboard = FALSE
)
#> [1] "[](https://www.rostrum.blog/)"Which looks like this:
The image will be subtly animated, depending on your browser.
Again, you can click this badge to be taken to the link specified in md_link, i.e. https://www.rostrum.blog/.
Note that the output Markdown string for this example was much longer than for the previous examples and contains what looks like semi-random characters. This is the result of converting the image into base64 with base64enc::base64encode(). This is a requirement for embedding a custom icon into a shields.io badge.
4. CRAN DOI
CRAN added DOIs to packages in mid-2024, which can be fetched with tools::CRAN_package_db(). There’s a dedicated {badgr} function to generate a DOI badge for a package, assuming the package is on CRAN and has a DOI recorded.
You only need to supply a package name, but you can also use additional arguments from get_badge() if you wish.
get_cran_doi_badge(
package_name = "datapasta",
browser_preview = FALSE,
to_clipboard = FALSE
)
#> [1] "[](https://doi.org/10.32614/CRAN.package.datapasta)"It looks like this:
Click it to resolve the DOI, which takes you to the CRAN page for the package. And yes, that tasteful blue is sampled from the R logo.
Disclaimer
I’m not affiliated with the excellent shields.io. You can back or donate to them. Find out more from their website, Twitter, Discord or go to the source code.
Similar projects
Somehow I missed the existence of the {badger} package by Guangchuang Yu, which is on CRAN. It contains functions for several pre-baked badge types, plus badge_custom().
I think the major difference is that {badgr} has a little more flexibility than {badger} for custom badge arguments and {badgr} also allows for custom icons to be added.
Code of Conduct
Please note that the {badgr} project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
