Contrast

Privacy 

Imprint and
Privacy Policy
Toggle high contrast
for better accessibility
made  
with

CONTENT

Welcome to my website! This is my first blog post here. I am writing these lines in an attempt to explain how this website was created. While I hope this will also be interesting to you, the main motivation for making this website was to learn something myself. Most importantly, I tried to challenge myself by not relying on a premade content management system. Instead, I used basic R Markdown (Allaire et al., 2020; Xie et al., 2018, 2020) pages that are rendered using the knitr package (Xie, 2014).

R Markdown allows to connect several documents to a very basic website, using R Markdown’s site generator (see section 10.5 in Xie et al., 2018). The blogdown (Xie et al., 2017) package extends the functionality of these simple reports and is often used to create personal websites and blogs using R (R Core Team, 2020). While this package makes it very easy to create visually appealing websites, I found blogdown‘s functionality to overshoot my needs and intentions. The idea of a basic R Markdown site seemed to better fit my plan to easily hack together a website according to my preferences, and without modifying a thousand files. In fact, most of the changes I made are simple customizations and code overrides of the pages’ (bootstrap) CSS. Additionally, I made a few changes to the default HTML template.1 Also, I added a dark-/light-mode switch, which requires some Java Script. All changes and additions are documented in this post and publicly available trough my GitHub account.2

In case you want to find out more, I discuss all of this in more detail in the following sections. I start by explaining and documenting the special features of R Markdown sites: These include markdown formatting, the presentation and execution of code (e.g., R- and Python-Code), creating tables and figures, \(\LaTeX\) math equations as well as easy \(B\kern-0.1em\raise-0.03em\small{I}\kern-0.15em\small{B}\kern-0.15em\normalsize{T}\kern-0.35em\raise-0.2emE \kern-0.2emX\)-Citations. In the second part of this post I highlight some of the changes and additions I developed, which extend the functionality and look of basic R Markdown documents and make it more accessible.

1 Functionality

This website was built entirely with R and R Markdown. This means that, in theory, everything that is required to create a new page (e.g., writing a new blog post) is a new Rmd file with text formatted in markup language. All work to create the HTML page which renders in your browser is done by the knitr package (Xie, 2014) behind the scenes and styled using the customized CSS file (see below). To further customize a specific page, simple instructions can be given in the YAML header of the Rmd file. The header for this post is documented below. It sets a custom title, subtitle and author information for the page. Furthermore, it adds a floating table of contents to the left — if it fits your screen width — and includes bibliographic information.

---
title: "Building a Website with R"
subtitle: "Why use R Markdown to build a website?"
author: "Felix Dietrich"
date: "3/17/2021"
bibliography: bib/this_website.bib
csl: bib/apa.csl
link-citations: yes
output: 
  html_document:
    toc: TRUE
    toc_float:
      collapsed: false
    toc_depth: 2
    number_sections: true
---

1.1 Code

The most important feature of R Markdown pages is their ability to not only display and format code, but to run it while rendering. This makes it really easy to create transparent and reproducible data reports. For example, the code block below creates a data object called delays with data filtered from the nycflights13 dataset.

# code from: https://r4ds.had.co.nz/transform.html
delays <- nycflights13::flights %>% 
  group_by(dest) %>% 
  summarise(
    count = n(),
    dist = mean(distance, na.rm = TRUE),
    delay = mean(arr_delay, na.rm = TRUE)
  ) %>% 
  filter(count > 20, dest != "HNL")

1.2 Tables

The following code extracts five random rows of data from the object that was created above and displays them in a neat and responsive table.

delays %>% 
  sample_n(5) %>% 
  kable(caption = "A sample table of the data filtered above",
        digits = 2) %>% 
  t_styling()
A sample table of the data filtered above
dest count dist delay
SMF 284 2521.00 12.11
HOU 2115 1420.16 7.18
CHO 52 305.00 9.50
EGE 213 1735.71 6.30
ALB 439 143.00 14.40

1.3 Figures

Furthermore, the data can easily be plotted. To visualize the association of flight delays and flight distance, only a few lines of code are needed.

# code adapted from: https://r4ds.had.co.nz/transform.html
ggplot(data = delays,
       mapping = aes(x = dist, y = delay)) +
  geom_point(aes(size = count), alpha = 1/3) +
  geom_smooth(color = "#000000", se = FALSE) +
  labs(x = "distance",
       caption = "Data: 336,776 flights in total") +
  styling

Average delay by distance for flights that departed from NYC to destinations in the United States Puerto Rico, and the American Virgin Islands in 2013

Average delay by distance for flights that departed from NYC to destinations in the United States Puerto Rico, and the American Virgin Islands in 2013

1.4 Mathjax

It is also very easy to include math equations in \(\LaTeX\) style like this:

s_N = \sqrt {\frac{1}{N}\sum\limits_{i = 1}^N {\left( {x_i - \bar x} \right)^2 } }

With the implementation of Mathjax,3 the formula is rendered like this:

\[ s_N = \sqrt {\frac{1}{N}\sum\limits_{i = 1}^N {\left( {x_i - \bar x} \right)^2 }} \]

1.5 Citations

R Markdown integrates and converts citations using Pandoc.4 For example, to cite the paper “Consequences of erudite vernacular utilized irrespective of necessity: Problems with using long words needlessly” by Daniel M. Oppenheimer, the necessary \(B\kern-0.1em\raise-0.03em\small{I}\kern-0.15em\small{B}\kern-0.15em\normalsize{T}\kern-0.35em\raise-0.2emE \kern-0.2emX\) information must be added to a separate file and referenced in the YAML above. To cite, the citation key (e.g., @oppenheimerProblemsUsingLongWords2006) must be added to the text. A complete reference list is automatically created at the end of the page and linked from the intext citation.

Fun fact (and reason to cite): The paper (Oppenheimer, 2006) won the 2006 IG-Nobel Prize in Literature.5

2 The Look

Now that I have introduced the functional aspects of R Markdown sites, for the second part of this post I move on to the less useful, but still very fun part of designing this page: the looks. While R Markdown reports look rather plain out of the box, it is not very difficult to pimp the look with CSS. The customized code is available from my Website’s GitHub Repository.6

In this post, I won’t be able to talk about all the changes I made to the look and feel of this page in detail, but your are free to take a look at the code and play around with it to find out more. For an overview, in the following sections I briefly present the fonts and the color scheme used on my page. Both are intended to increase accessibility.

2.1 Fonts

On this page, a combination of three fonts is used: Garbata Regular for headers, Reforma 2018 for text, and iA Writer Mono for code. Garbata is available from Zetafonts.7 A licence for the regular font can be acquired for free from their website. Reforma 2018 is one of three fonts published under the Creative Commons license CC BY-ND 4.0 by PampaType.8 The Reforma typeface used in this document was designed by Alejandro Lo Celso and programmed by Guido Ferreyra as part of a commission to the PampaType foundry by the Universidad Nacional de Córdoba, Argentina. iA Writer Mono was published by iA9 under the SIL Open Font License, Version 1.1 and is available for free on GitHub.10

2.2 Accessibility

As a special feature, I have implemented a dark mode and a light mode for this website. Modes can be switched using the toggle floating on the right side of the page. The customized CSS and Java Script required to achieve this is available from the website’s GitHub repo.11 Colors in both modes are inspired by the Gruvbox color scheme, which started as a color scheme for the Vim text editor but has been implemented in other software as well.12 While Gruvbox includes several colors, yellow is my favorite color, so this is the accent color I decided on for this website.

2.3 RStudio

I also made two RStudio-Themes which incorporate the Gruvbox color scheme. They will be introduced in a follow up blog post.

References

Allaire, J., Xie, Y., McPherson, J., Luraschi, J., Ushey, K., Atkins, A., Wickham, H., Cheng, J., Chang, W., & Iannone, R. (2020). Rmarkdown: Dynamic documents for r. https://github.com/rstudio/rmarkdown
Oppenheimer, D. M. (2006). Consequences of erudite vernacular utilized irrespective of necessity: Problems with using long words needlessly. Applied Cognitive Psychology, 20(2), 139–156. https://doi.org/https://doi.org/10.1002/acp.1178
R Core Team. (2020). R: A language and environment for statistical computing. R Foundation for Statistical Computing. https://www.R-project.org/
Xie, Y. (2014). Knitr: A comprehensive tool for reproducible research in R. In V. Stodden, F. Leisch, & R. D. Peng (Eds.), Implementing reproducible computational research. Chapman; Hall/CRC. http://www.crcpress.com/product/isbn/9781466561595
Xie, Y., Allaire, J. J., & Grolemund, G. (2018). R markdown: The definitive guide. Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown
Xie, Y., Dervieux, C., & Riederer, E. (2020). R markdown cookbook. Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown-cookbook
Xie, Y., Hill, A. P., & Thomas, A. (2017). Blogdown: Creating websites with R markdown. Chapman; Hall/CRC. https://github.com/rstudio/blogdown