https://github.com/matt-dray/badgr
:shield::sparkles: R package: generate URLs for shields.io metadata badges
https://github.com/matt-dray/badgr
badge r r-package rstats
Last synced: 30 days ago
JSON representation
:shield::sparkles: R package: generate URLs for shields.io metadata badges
- Host: GitHub
- URL: https://github.com/matt-dray/badgr
- Owner: matt-dray
- License: other
- Created: 2020-05-06T21:19:47.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-12T12:15:31.000Z (10 months ago)
- Last Synced: 2025-03-09T01:11:57.546Z (about 1 month ago)
- Topics: badge, r, r-package, rstats
- Language: R
- Homepage: https://matt-dray.github.io/badgr/
- Size: 149 KB
- Stars: 16
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- jimsghstars - matt-dray/badgr - :shield::sparkles: R package: generate URLs for shields.io metadata badges (R)
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# {badgr}
[](https://www.repostatus.org/#inactive)
[](https://github.com/matt-dray/badgr/actions/workflows/R-CMD-check.yaml)
[](https://www.rostrum.blog/2020/05/08/readme-badge/)
Generate URLs for [shields.io](https://shields.io/) metadata badges—typically used in repository READMEs—using R.
## Installation
You can install {badgr} from [R-universe](https://ropensci.org/r-universe/) with:
```{r, eval=FALSE}
install.packages("badgr", repos = "https://matt-dray.r-universe.dev")
```
Please [file an issue](https://github.com/matt-dray/badgr/issues) with your ideas or to report bugs.
## Examples
1. Simple: bare bones functionality
1. More complex: introducing a logo and changing the style
1. Custom logo: adding your own logo
1. A CRAN package DOI badge
### 1. Simple
This is a basic example that shows you how to generate the simplest possible badge.
```{r}
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:
```{r}
badge
```
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](https://simpleicons.org/) and provide a link that will be added to the Markdown, so clicking the badge will take you to that site.
```{r}
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
)
```
Which looks like this:
[](https://shields.io)
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](https://simpleicons.org/)? You can use your own. Here, for example, I'm using [a small gif](https://raw.githubusercontent.com/matt-dray/rostrum-blog/master/static/images/favicon.gif) of the logo from [my blog](https://www.rostrum.blog/).
```{r}
# 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
)
```
Which looks like this:
[](https://www.rostrum.blog/)
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](https://en.wikipedia.org/wiki/Base64) with `base64enc::base64encode()`. This is a requirement for embedding a custom icon into a shields.io badge.
### 4. CRAN DOI
CRAN added [DOIs](https://www.doi.org/) 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.
```{r}
get_cran_doi_badge(
package_name = "datapasta",
browser_preview = FALSE,
to_clipboard = FALSE
)
```
It looks like this:
[](https://doi.org/10.32614/CRAN.package.datapasta)
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](https://shields.io/). You can [back or donate to them](https://opencollective.com/shields). Find out more from their [website](https://shields.io/), [Twitter](https://twitter.com/Shields_io), [Discord](https://discord.com/invite/HjJCwm5) or go to [the source code](https://github.com/badges/shields).
## Similar projects
Somehow I missed the existence of [the {badger} package](https://github.com/GuangchuangYu/badger) by [Guangchuang Yu](https://guangchuangyu.github.io/), 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](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.