Building a website (part 1)

Nikita Gusarov

The idea to write this post (or rather a sequence of posts) appeared when I was attempting to deploy this website, mostly because of the difficulties I’ve encountered. So, today’s question is: how to deploy a simple static website with R?

First of all, we should start with distinguishing two main steps in website production:

  1. Building website
  2. Deploying the results on the web

These two topics may be rather long to explain, that’s why I’d rather prefer to separate this post into several parts.

Build strategies

In R there are many ways to create a website without any need to work with html or css. All you need is to know how R functions, as well as some basics of markdown or Rmarkdown syntax. This way we avoid the need to write entire pages in plain html and our software does everything in our place.

The main options that I’ve considering during the web-page construction were:

  • Personalized script compiling .Rmd files into a website
  • Simple rmarkdown site generator proposed as part of basic rmarkdown package
  • Advanced blogdown package, which uses Hugo to build web-pages
  • The bookdown package’s functionality to build web-books^[For more you may look here: https://bookdown.org/yihui/bookdown/rstudio-ide.html]

But how to choose among all these options? Here are some of my thoughts about all of them, considering I’ve personally tried every option.

Manual compilation

The first option seems rather simple: just make a bunch of .Rmd files and compile them. However, nothing ever is as simple as it seems. Even using relative path definition, it becomes nearly impossible to manage all the dependencies and internal references within the website. Last year, we have attempted to implement this approach while building a website for a course of Statistics at Grenoble-INP, but by the middle of spring semester it became too difficult to maintain and update the site.

Some quick example of an automatic compilation script:

# Libraries
library(foreach)

# Get list of files
lfiles = list.files(
    path = ".",
    pattern = "*.Rmd",
    full.names = TRUE
)

# Compile files
foreach(ff = lfiles) %do% {
    rmarkdown::render(ff, encoding = "UTF-8")
}

This script will generate the documents on the same path the originals are. This leads to a situation where an entire folder with source files ill be used for deployment, which may be undesired behaviour.

Conclusion: It’s the best solution for one-page website, but may be unnecessary complex for something more.

Site generator of rmarkdown

This static website generator is a rather unsophisticated wrapper, which allows to render all the .Rmd document found in a given folder and save the output for later deployment. Although it’s much simple to automate the binding of several pages into a complete website, there are some disadvantages.

The main disadvantage is that rmarkdown::render_site() command is a simple wrapper to render several documents. The solution is agnostic of the file-structure inside the folder and renders only the files it encounters at root position, which makes it impossible to produce something like personal blog (the more there will be activity, the more incomprehensible the root directory will become). As you can see, the result is nearly identical to the manual compilation, except probably for the possibility to automatically have identical site-wide options in the YML file.

For some reference command one may name:

# Render site
rmarkdown::render_site()

This command requires existence of at least two files: (1) _site.yml and (2) index.Rmd. For a more complete example one may look here.

Conclusion: This option may be the best for some simple websites with several pages, but which do not require any complex structure.

Site generation with blogdown

The blogdown was initially created to replace the rmarkdown inbuilt website producing functionality. Having Hugo as back-end, this package does miracles when building rather complex static websites. What’s more, it makes available all the themes there exist over Internet.

Nevertheless, there are some drawbacks as usual. The main complications start when you realise that Hugo, Hugo-themes and blogdown are under active development. Consequently, there is always the possibility that something will change among releases, which will render your web-page non-operational. Luckily, this danger can be mitigated by a careful setup and deployment procedure configuration, but about this I’ll talk later.

Conclusion: After many tries and fails I’ve decided this solution suited the best for my personal blog. It might be somewhat complex and even unstable, but it offers good degree of flexibility. Because, this is the chosen solution, I will skip the examples here and provide them in the second part of this sequence.

Web-books and bookdown

The final known to me option is represented by the bookdown package. This package was created to address one simple need: authoring books. It allows to manage many independent chapters, maintaining a simple and comprehensive file-structure at the same time. Nevertheless, the web-book format is definitely not suitable for all purposes and might be limiting for someone.

Conclusion: Even though it’s the best solution for the given task, it is absolutely not fit for authoring blogs.