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!
— Yihui, Amber, & Alison
If your website does not contain any Rmd files, it is very straightforward to render it — just a system call to the
hugo command. When your website contains Rmd files, blogdown has provided two rendering methods to compile these Rmd files. A website can be built using the function
build_site(local = FALSE, run_hugo = TRUE, build_rmd = FALSE, ...)
As mentioned in Section 1.5, the default value of the
method argument is determined by the global option
blogdown.method, and you can set this option in
method = 'html',
*.markdown, and keeps the
*.markdown output files under the same directory as
An Rmd file may generate two directories for figures (
*_files/) and cache (
*_cache/), respectively, if you have plot output or HTML widgets (Vaidyanathan et al. 2021) in your R code chunks, or enabled the chunk option
cache = TRUE for caching. In the figure directory, there will be a subdirectory
figure-html/ that contains your plot output files, and possibly other subdirectories containing HTML dependencies from HTML widgets (e.g.,
jquery/). The figure directory is moved to
/static/, and the cache directory is moved to
After you run
build_site(), your website is ready to be compiled by Hugo. This gives you the freedom to use deploying services like Netlify (Chapter 3), where neither R nor blogdown is available, but Hugo is.
method = 'custom',
build_site() will not process any R Markdown files, nor will it call Hugo to build the site. No matter which method you choose to use,
build_site() will always look for an R script
/R/build.R and execute it if it exists. This gives you the complete freedom to do anything you want for the website. For example, you can call
knitr::knit() to compile Rmd to Markdown (
*.md) in this R script instead of using
rmarkdown::render(). This feature is designed for advanced users who are really familiar with the knitr package42 and Hugo or other static website generators (see Chapter 5).
R/build.R exists and
method = 'html', the R Markdown files are knitted first, then the script
R/build.R is executed, and lastly Hugo is called to build the website.
Honestly, it was originally designed for Yihui himself to build his own website, but he realized this feature could actually free users from Hugo. For example, it is possible to use Jekyll (another popular static site generator) with blogdown, too.↩︎