5.3 Default site generator in rmarkdown

Before blogdown was invented, there was actually a relatively simple way to render websites using rmarkdown. The structure of the website has to be a flat directory of Rmd files (no subdirectories for Rmd files) and a configuration file in which you can specify a navigation bar for all your pages and output format options.

You can find more information about this site generator in its documentation at https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html, and we are not going to repeat the documentation here, but just want to highlight the major differences between the default site generator in rmarkdown and other specialized site generators like Hugo:

  • The rmarkdown site generator requires all Rmd files to be under the root directory. Hugo has no constraints on the site structure, and you can create arbitrary directories and files under /content/.

  • Hugo is a general-purpose site generator that is highly customizable, and there are a lot of things that rmarkdown’s default site generator does not support, e.g., RSS feeds, metadata especially common in blogs such as categories and tags, and customizing permanent links for certain pages.

There are still legitimate reasons to choose the rmarkdown default site generator, even though it does not appear to be as powerful as Hugo, including:

  • You are familiar with generating single-page HTML output from R Markdown, and all you want is to extend this to generating multiple pages from multiple Rmd files.

  • It suffices to use a flat directory of Rmd files. You do not write a blog or need RSS feeds.

  • You prefer the Bootstrap styles. In theory, you can also apply Bootstrap styles to Hugo websites, but it will require you to learn more about Hugo. Bootstrap is well supported in rmarkdown, and you can spend more time on the configurations instead of learning the technical details about how it works.

  • There are certain features in rmarkdown HTML output that are missing in blogdown. For example, currently you cannot easily print data frames as paged tables, add a floating table of contents, or fold/unfold code blocks dynamically in the output of blogdown. All these could be implemented via JavaScript and CSS, but it is certainly not as simple as specifying a few options in rmarkdown like toc_float: true.

Please note that the rmarkdown site generator is extensible, too. For example, the bookdown package (Xie 2020a) is essentially a custom site generator to generate books as websites.

References

Xie, Yihui. 2020a. Bookdown: Authoring Books and Technical Documents with R Markdown. https://github.com/rstudio/bookdown.