README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![Last Commit](https://img.shields.io/github/last-commit/friendly/colorize)](https://github.com/friendly/colorize/)
<!-- badges: end -->


```{r setup}
#| echo: false
library(colorize)
```

# colorize  

**Version 0.2.0**


<img src="man/figures/logo.jpg" height="120" style="float:right; height:120px;"/>
The `colorize` package provides some simple functions for printing text in color in markdown or Quarto documents,
to be rendered as HTML or LaTeX.

This is useful when writing about the use of colors in graphs or tables, where you want to print
their names in their actual color to give a direct impression of the color, like "red" shown in `r colorize("red")`, or
"blue" shown in `r colorize("blue")`. This is similar to the use of *direct labels* in graphs, which are perceptually bound closely
to what is portrayed, rather than an _indirect legend_, which takes more cognitive energy to see what data in referred to
in the graph.

The following functions are provided:

* `colorize(text, color)`: Print the `text` in a given `color`, as in `r colorize("this text in red", "red")`
* `colorize_bg(text, color)`: Print the `text` with a background in `color`, as in `r colorize_bg("this text in red", "red")`
* `colorbox(text, color, ...)`: Print `text` with background in color, but where the text is given a contrasting color designed to be most legible, as in `r colorbox("this text in red", "red")`

In the examples above, note the difference between `colorize_bg()` and `colorbox()`: when the desired color is `r colorize("red")`,
`colorbox()` uses a lighter color (white) so the text contrasts more with the darker background.

This is somewhat similar to what RStudio does when you enter color names or hex values in code, but `colorbox()` uses
`colorspace::contrast_ratio(textcolor, color, ...)` to find the `textcolor` that **contrasts best** against the background `color`.

![](man/figures/test_colors.png)

The uses of color for text in visualization is far more general than represented here.
Brath (2020) is a wonderful source for inspiration!

## Installation


`colorize` is not yet on CRAN.
You can install the development version of colorize from either the GitHub repo or r-universe, as follows:


``` r
remotes::install.github("friendly/colorize")
# or:
install.packages('colorize', repos = c('https://friendly.r-universe.dev'))
```

The package vignette, `vignette("colorbox", package = "colorize")` describes the use of these functions.

## Example

This example simply shows how a set of color names is rendered in HTML encoding. It doesn't print them in their colors.

```{r example}
library(colorize)
# define some color names

test_colors <- c("red", "blue", "green",
                 "white", "black", "gray",
                 "pink", "yellow", "darkgreen")

sapply(test_colors, colorize)
```

## Related

For a purely Quarto approach, [quarto-highlight-text](https://m.canouil.dev/quarto-highlight-text/)
is a Quarto extension that allows you to highlight text in a document for various formats: HTML, LaTeX, Typst, Docx, PowerPoint, Reveal.js, and Beamer.
 

## Citation

If you find this package useful in your work, you can cite it as:

  Friendly M, Zeileis A (2025). _colorize: Render Text in Color for Markdown/Quarto Documents_. R package version 0.2.0,
  <https://github.com/friendly/colorize>.


## References

Brath, R. (2020). _Visualizing with Text_. A K Peters/CRC Press. https://doi.org/10.1201/9780429290565