A note from the authors: Some of the information and instructions in this book are now out of date because of changes to Hugo and the blogdown package. If you have suggestions for improving this book, please file an issue in our GitHub repository. Thanks for your patience while we work to update the book, and please stay tuned for the revised version!

In the meantime, you can find an introduction to the changes and new features in the v1.0 release blog post and this "Up & running with blogdown in 2021" blog post.

— Yihui, Amber, & Alison

Preface

In the summer of 2012, I did my internship at AT&T Labs Research,1 where I attended a talk given by Carlos Scheidegger (https://cscheid.net), and Carlos said something along the lines of “if you don’t have a website nowadays, you don’t exist.” Later I paraphrased it as:

“I web, therefore I am a spiderman.”

Carlos’s words resonated very well with me, although they were a little exaggerated. 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 from existing popular website platforms, such as WordPress. There are two major highlights of blogdown:

  1. It produces a static website, meaning the website only consists of static files such as HTML, CSS, JavaScript, and images, etc. You can host the website on any web server (see Chapter 3 for details). The website does not require server-side scripts such as PHP or databases like WordPress does. It is just one folder of static files. We will explain more benefits of static websites in Chapter 2, when we introduce the static website generator Hugo.

  2. 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, 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, all 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 5 presents possibilities of using other site generators, such as Jekyll and rmarkdown’s default site generator.

This book has been published by Chapman & Hall/CRC. The online version of this book is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

References

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

  1. In this book, “I” and “my” refer to Yihui unless otherwise noted.↩︎

  2. Yihui’s homepage is at https://yihui.org. He writes blog posts in both Chinese (https://yihui.org/cn/) and English (https://yihui.org/en/), and documents his software packages such as knitr (https://yihui.org/knitr/) and animation (https://yihui.org/animation/). Occasionally he also writes articles like https://yihui.org/rlp/ when he finds interesting topics but does not bother with a formal journal submission. Amber’s homepage is at https://amber.rbind.io, where you can find her blog and project pages. Alison’s website is at https://alison.rbind.io, which uses an academic theme at the moment.↩︎