Broadside

Broadside executes R code chunks in files and captures their output. Unlike rmarkdown or Quarto, it focuses solely on processing code chunks in-place rather than generating complete documents. This makes it an ideal component in larger document processing workflows, particularly when combined with pandoc.

Examples

The following example demonstrates broadside's minimal transformation approach:

Input file:

# A Simple Simulation
First, generate some data:
```{r}
x <- rnorm(500, 4, 3)
```
What's the mean?
```{r echo = FALSE}
mean(x)
```

Process with broadside:

broadside --chunk-class=R --output-class="R R_output" -o small.md small.Rmd

Output:

# A Simple Simulation
First, generate some data:
``` {.R}
x <- rnorm(500, 4, 3)
```
What's the mean?
``` {.R .R_output}
[1] 4.041494
```

The output can be further processed with pandoc:

pandoc -f markdown -t html --no-highlight -o small.html small.md

Resulting HTML:

<h1 id="a-simple-simulation">A Simple Simulation</h1>
<p>First, generate some data:</p>
<pre class="R"><code>x &lt;- rnorm(500, 4, 3)</code></pre>
<p>What's the mean?</p>
<pre class="R R_output"><code>[1] 4.201148</code></pre>

Alternatively, you can place a R Markdown chunk directly in an HTML file, and use the same workflow:

<h1 id="a-simple-simulation">A Simple Simulation</h1>
<p>First, generate some data:</p>
```{r}
x <- rnorm(500, 4, 3)
```
<p>What's the mean?</p>
```{r echo = FALSE}
mean(x)
```

Processing with broadside and pandoc:

broadside --chunk-class=R --output-class="R R_output" -o simple-intermediate.html simple.html
pandoc -f markdown -t html --no-highlight -o examples/simple-out.html examples/simple-intermediate.html

would yield the same HTML as above. Note the continued use of -f markdown - pandoc will only process the markdown, leaving the HTML as-is.

Usage

Basic usage:

broadside <input> # Send output to terminal
broadside -o <output> <input> # Send output to output file

Code chunks in your input file should use R Markdown syntax:

```{r echo=TRUE, eval=TRUE}
print("Hello from R!")
```

Modes

By default, broadside uses "interweave mode", which is similar to how rmarkdown and Quarto process chunks: Code chunks are processed line-by-line, and an output chunk is created whenever the input produces output.

```{r}
x <- 5
x + 3
x - 2
```

broadside --chunk-class=R --output-class="R R_output" input.md -i

``` {.R}
x <- 5
x + 3
```
``` {.R .R_output}
## [1] 8
```
``` {.R}
x - 2
```
``` {.R .R_output}
## [1] 3
```

Interweave mode can requested explicitly with the flag -i or --interweave.

In addition, broadside supports batch mode, with flags -b or --batch, in which all input is processed in a batch, and all output appears in a single chunk following it.

```{r}
x <- 5
x + 3
x - 2
```

broadside --chunk-class=R --output-class="R R_output" input.md -b

``` {.R}
x <- 5
x + 3
x - 2
```
``` {.R .R_output}
## [1] 8
## [1] 3
```

Currently support chunk options

Amongst the 50+ chunk options, broadside currently supports:

• eval, only logical.
• echo, only logical.
• error
• include
• comment, defaults to "## " as rmarkdown does.
• strip.white

These are supported in individual chunks,

```{r error = TRUE}

or set globally,

knitr::opts_chunk$set(error = TRUE)

No chunks related to images will be supported, see FAQ for handling graphs.

Outstanding missing features or bugs

• BUG: Using ~ in --working-dir will not work.

Missing features that won't be addressed

Here's a non-comprehensive list of features that, if you need them, you really need rmarkdown or Quarto instead of broadside:

• yaml headers
• Automated image inclusion, or any plot-related chunk options (see FAQ)
• R chunks with just "r" (as opposed to "{r}") are just regular markdown, and thus not touched.
• Child documents
• Chunk options related to:
  • plots & figures
  • tables
  • caching
  • animation
  • code/file, which replace the code in the chunk with other code.
  • option templating

Additionally, additional language engines are not supported. While in theory, there's nothing stopping broadside from working with other languages, I'd have to have the motivation to implement it.

FAQ

How do I get plots included?

These should be included manually. Save the results from R (perhaps in a chunk with include=FALSE, using pdf() or png() or similar), then include them directly in the markdown/HTML.

What about syntax highlighting?

Syntax highlighting is added by default using pandoc; you can use --no-highlight to disable it.

Why "Broadside"?

A broadside is a simpler pamphlet then a quarto.