The ability to create a blog composed of a collection of Radix articles.

Radix is based on the Distill web framework, which was originally created for use in the Distill Machine Learning Journal (Carter, Olah, and Satyanarayan 2016). Radix combines the technical authoring features of Distill with R Markdown, enabling a fully reproducible workflow based on literate programming (Knuth 1984).

Installation

To create an R Markdown document that uses the Radix format, first install the radix R package from CRAN:

install.packages("radix")

Using Radix requires Pandoc v2.0 or higher. If you are using RStudio then you should use RStudio v1.2.718 or higher (which comes bundled with Pandoc v2.0).

Author entries must have at least name and url specified (the affiliation fields are optional). The date field should be formatted as month, day, year (various notations are supported as long as the components appear in that order).

The article’s description and author bylines are automatically rendered as part of the title area of the document.

The bibliography field is used to provide a reference to the Bibtex file where all of the sources cited in your article are defined. The citations section describes how to include references to these sources in your article.

Figures

Radix provides a number of options for laying out figures within your article. By default figures span the width of the main article body:

However, some figures benefit from using additional horizontal space. In this cases the layout chunk option enables you to specify a wide variety of other layouts.

For example, if we wanted to display a figure a bit outside the bounds of the article text, we could specify the l-body-outset layout via the layout chunk option:

Note that when specifying an alternate layout you should also specify an appropriate fig.width and fig.height for that layout. These values don’t determine the absolute size of the figure (that’s dynamic based on the layout) but they do determine the aspect ratio of the figure.

See the documentation on figure layout for details on additional layout options.

Citations are then used in the article body with standard R Markdown notation, for example: [@xie2015] (which references an id provided in the bibliography). Note that multiple ids (separated by semicolons) can be provided.

The citation is presented inline like this: (Xie 2015) (a number that displays more information on hover). If you have an appendix, a bibliography is automatically created and populated in it.

See the article on citations for additional details on using citations, including how to provide the metadata required to make your article more easily citable for others.

Footnotes and asides

Footnotes use standard Pandoc markdown notation, for example ^[This will become a hover-able footnote]. The number of the footnote will be automatically generated.1

You can also optionally include notes in the gutter of the article (immediately to the right of the article text). To do this use the <aside> tag.

<aside>
This content will appear in the gutter of the article.
</aside>

This content will appear in the gutter of the article.

You can also include figures in the gutter. Just enclose the code chunk which generates the figure in an <aside> tag:

If the table of contents depth is not explicitly specified, it defaults to 3 (meaning that all level 1, 2, and 3 headers will be included in the table of contents).

Code blocks

Syntax highlighting is provided for knitr code chunks. Note that by default the Radix format does not display the code for chunks that are evaluated to produce output (knitr option echo = FALSE).

The echo = FALSE default reflects the fact that Radix articles are often used to present the results of analyses rather than the underlying code. To display the code that was evaluated to produce output you can set the echo chunk option to TRUE:

```{r, echo=TRUE}
1 + 1
```

To include code that is only displayed and not evaluated specify the eval=FALSE option:

```{r, eval=FALSE, echo=TRUE}
1 + 1
```

There are a number of default values that Radix establishes for knitr chunk options (these defaults also reflect the use case of presenting results/output rather than underlying code):

Option

Value

Comment

echo

FALSE

Don’t print code by default.

warning

FALSE

Don’t print warnings by default.

message

FALSE

Don’t print R messages by default.

comment

NA

Don’t preface R output with a comment.

R.options

list(width = 70)

70 character wide console output.

Keeping R code and output at 70 characters wide (or less) is recommended for readability on a variety of devices and screen sizes.

As illustrated above, all of these defaults can be overridden on a chunk-by-chunk basis by specifying chunk options.

You can also change the global defaults using a setup chunk. For example:

Appendices

Appendices can be added after your article by adding the .appendix class to any level 1 or level 2 header. For example:

## Acknowledgments {.appendix}
This is a place to recognize people and institutions. It may also be a good place
to acknowledge and cite software that makes your work possible.
## Author Contributions {.appendix}
We strongly encourage you to include an author contributions statement briefly
describing what each author did.

Footnotes and references will be included in the same section, immediately beneath any custom appendices.

Why Radix?

Why the name Radix? The most common definition of radix in the English language comes from Mathematics, where it is used to describe the base of a system of numeration. It is also used to describe the source or origin of something. Both of these usages derive from the Latin meaning of radix, which is literally root.

The purpose of scientific communication is to help get to the root of things! Radix provides a set of tools to facilitate clear scientific communication that links richly with other sources of knowledge and insight.

Acknowledgments

Radix builds on the work of many individuals and projects. Shan Carter, Ludwig Schubert, and Christopher Olah created the Distill web framework. John MacFarlane created the Pandoc universal markup converter. Davide Cervone and Volker Sorge created the MathJax library for rendering mathematical notation on the web. Mike Bostock created the D3 library for producing dynamic, interactive data visualizations for the web. We are grateful for the spirit of generosity that moved these individuals to create high-quality open source software for the benefit of all.

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Reuse

Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/rstudio/radix, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".