blogdown: Creating Websites with R Markdown
Yihui Xie & Amber Thomas
WARNING: this book is still under development. It will be updated from day to day. The blogdown package is still a beta version, so please use both the package and this book with caution until this warning is removed. We will try not to introduce breaking changes in blogdown from now on, but there is no guarantee.
In the summer of 2012, I did my internship at the AT&T Labs Research,1 where I attended a talk given by Carlos Scheidegger (https://cscheid.net), and Carlos said something along the lines “if you don’t have a website nowadays, you don’t exist.” Later I paraphrased it as:
“I web, therefore I am
Carlos’s words resonated very well with me, although they were a little exaggerative. A well designed and maintained website can be extremely helpful for other people to know you, and you do not need to wait for suitable chances at conferences or other occasions to introduce yourself in person to other people. On the other hand, a website is also highly useful for yourself to keep track of what you have done and thought. Sometimes you may go back to a certain old post of yours to relearn the tricks or methods you once mastered in the past but have forgotten.
We introduce an R package, blogdown, in this short book, to teach you how to create websites using R Markdown and Hugo. If you have experience with creating websites, you may naturally ask what the benefits of using R Markdown are, and how blogdown is different with existing popular website platforms, such as WordPress. There are two major highlights of blogdown:
The website is generated from R Markdown documents (R is optional, i.e., you can use plain Markdown documents without R code chunks). This brings a huge amount of benefits, especially if your website is related to data analysis or (R) programming. Being able to use Markdown implies simplicity and more importantly, portability (e.g., you are giving yourself the chance to convert your blog posts to PDF and publish to journals or even books in the future). R Markdown gives you the benefits of dynamic documents — all your results, such as tables, graphics, and inline values, can be computed and rendered dynamically from R code, hence the results you present on your website are more likely to be reproducible. An additional yet important benefit of using R Markdown is that you will be able to write technical documents easily, due to the fact that blogdown inherits the HTML output format from bookdown (Xie 2016). For example, it is possible to write LaTeX math equations, BibTeX citations, and even theorems and proofs if you want.
Please do not be misled by the word “blog” in the package name: blogdown is for general-purpose websites, and not only for blogs. For example, both authors of this book have their personal websites, where you can find information about their projects, blogs, package documentations, and so on.2 All their pages are built from blogdown and Hugo.
If you do not prefer using Hugo, there are other options, too. Chapter 4 has shown possibilities of using other site generators, such as Jekyll and rmarkdown’s default site generator.
The online version of this book is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
Xie, Yihui. 2016. Bookdown: Authoring Books and Technical Documents with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://github.com/rstudio/bookdown.
In this book, “I” and “my” refer to Yihui unless otherwise noted.↩
Yihui’s homepage is at https://yihui.name. He writes blog posts in both Chinese (https://yihui.name/cn/) and English (https://yihui.name/en/), and documents his software packages such as knitr (https://yihui.name/knitr/) and animation (https://yihui.name/animation/). Occasionally he also writes articles like https://yihui.name/rlp/ when he finds interesting topics but does not bother a formal journal submission. Amber’s homepage is at https://proquestionasker.github.io. Similarly, you can find her blog and project pages.↩