Generate URLs for shields.io metadata badges—typically used in repository READMEs—using R.
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.
- Simple: bare bones functionality
- More complex: introducing a logo and changing the style
- Custom logo: adding your own logo
- A CRAN package DOI badge
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:
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.
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.
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.
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.
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.
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.
