Author: Brodie Gaslam

# ANSI CSI SGR Sequences in Rmarkdown

#### Brodie Gaslam

### Browsers Do Not Interpret ANSI CSI SGR Sequences

Over the past few years color has been gaining traction in the R terminal, particularly since Gábor Csárdi’s crayon made it easy to format text with ANSI CSI SGR sequences. At the same time the advent of JJ Alaire and Yihui Xie `rmarkdown` and `knitr` packages, along with John MacFarlane `pandoc`, made it easy to automatically incorporate R code and output in HTML documents.

Unfortunately ANSI CSI SGR sequences are not recognized by web browsers and end up rendering weirdly1:

    sgr.string <- c(
      "\033[43;34mday > night\033[0m",
      "\033[44;33mdawn < dusk\033[0m"
    )
    writeLines(sgr.string)

    ## �[43;34mday > night�[0m
    ## �[44;33mdawn < dusk�[0m

### Automatically Convert ANSI CSI SGR to HTML

`fansi` provides the `to_html` function which converts the ANSI CSI SGR sequences and OSC hyperlinks into HTML markup. When we combine it with `knitr::knit_hooks` we can modify the rendering of the `rmarkdown` document such that ANSI CSI SGR encoding is shown in the equivalent HTML.

`fansi::set_knit_hooks` is a convenience function that does just this. You should call it in an `rmarkdown` document with the:

- Chunk option `results` set to “asis”.
- Chunk option `comments` set to “” (empty string).
- The `knitr::knit_hooks` object as an argument.

The corresponding `rmarkdown` hunk should look as follows:

    ```{r, comment="", results="asis"}
    old.hooks <- fansi::set_knit_hooks(knitr::knit_hooks)
    ```

We run this function for its side effects, which cause the output to be displayed as intended:

    writeLines(sgr.string)

    ## day > night
    ## dawn < dusk

If you are seeing extra line breaks in your output you may need to use:

    ```{r, comment="", results="asis"}
    old.hooks <- fansi::set_knit_hooks(knitr::knit_hooks, split.nl=TRUE)
    ```

If you use `crayon` to generate your ANSI CSI SGR style strings you may need to set `options(crayon.enabled=TRUE)`, as in some cases `crayon` suppresses the SGR markup if it thinks it is not outputting to a terminal.

We can also set hooks for the other types of outputs, and add some additional CSS styles.

    ```{r, comment="", results="asis"}
    styles <- c(
      getOption("fansi.style", dflt_css()),  # default style
      "PRE.fansi CODE {background-color: transparent;}",
      "PRE.fansi-error {background-color: #DDAAAA;}",
      "PRE.fansi-warning {background-color: #DDDDAA;}",
      "PRE.fansi-message {background-color: #AAAADD;}"
    )
    old.hooks <- c(
      old.hooks,
      fansi::set_knit_hooks(
        knitr::knit_hooks,
        which=c("warning", "error", "message"),
        style=styles
    ) )
    ```

    message(paste0(sgr.string, collapse="\n"))

    ## day > night
    ## dawn < dusk

    warning(paste0(c("", sgr.string), collapse="\n"))

    ## Warning:
    ## day > night
    ## dawn < dusk

    stop(paste0(c("", sgr.string), collapse="\n"))

    ## Error:
    ## day > night
    ## dawn < dusk

You can restore the old hooks at any time in your document with:

    do.call(knitr::knit_hooks$set, old.hooks)
    writeLines(sgr.string)

    ## �[43;34mday > night�[0m
    ## �[44;33mdawn < dusk�[0m

See `?fansi::set_knit_hooks` for details.

1For illustrative purposes we output raw ANSI CSI SGR sequences in this document. However, because the ESC control character causes problems with some HTML rendering services we replace it with the � symbol. Depending on the browser and process it would normally not be visible at all, or substituted with some other symbol.