Chapter 10 Websites

Most R Markdown applications are single documents. That is, you have a single R Markdown source document, and it generates a single output file. However, it is also possible to work with multiple Rmd documents in a project, and organize them in a meaningful way (e.g., pages can reference each other).

Currently there are two major ways to build multiple Rmd documents: blogdown (Xie, Hill, and Thomas 2017; Xie 2020a) for building websites, and bookdown (Xie 2016, 2020b) for authoring books. In this chapter, we briefly introduce the blogdown package. For the full reference, please read the official blogdown book by Xie, Hill, and Thomas (2017). In fact, the rmarkdown package also has a built-in site generator, which was not covered in detail by the blogdown book, so we will introduce it in Section 10.5.

With blogdown, you can write a blog post or a general page in an Rmd document, or a plain Markdown document. These source documents will be built into a static website, which is essentially a folder containing static HTML files and associated assets (such as images and CSS files). You can publish this folder to any web server as a website. Because it is only a single folder, it can be easy to maintain. For example, you do not need to worry about databases as you do if you use dynamic systems like WordPress.

Because the website is generated from R Markdown, the content is more likely to be reproducible, and also easier to maintain (no cut-and-paste of results). Using Markdown means your content could be more portable in the sense that you may convert your pages to PDF or other formats in the future, and you are not tied to the default HTML format. For example, you may be able to convert a blog post to a journal paper, or several posts to a book. One more benefit of using blogdown is that the Markdown syntax is based on bookdown’s extended syntax, which means it is highly suitable for technical writing. For example, you may write math equations, insert figures or tables with captions, cross-reference them with figure or table numbers, add citations, and present theorems or proofs.

References

Xie, Yihui. 2016. Bookdown: Authoring Books and Technical Documents with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://github.com/rstudio/bookdown.

Xie, Yihui. 2020a. Blogdown: Create Blogs and Websites with R Markdown. https://github.com/rstudio/blogdown.

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

Xie, Yihui, Alison Presmanes Hill, and Amber Thomas. 2017. Blogdown: Creating Websites with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://github.com/rstudio/blogdown.