D.9 Different building methods

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 blogdown::build_site():

build_site(local = FALSE, method = c("html", "custom"),
  run_hugo = TRUE, build_rmd = FALSE)

As mentioned in Section 1.4, the default value of the method argument is determined by the global option blogdown.method, and you can set this option in .Rprofile.

For method = 'html', build_site() renders *.Rmd to *.html, and *.Rmarkdown to *.markdown, and keeps the *.html/*.markdown output files under the same directory as *.Rmd/*.Rmarkdown files.

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. 2020) 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 /blogdown/.

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.

For 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 package⁴⁸ and Hugo or other static website generators (see Chapter 5).

When 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.

References

Vaidyanathan, Ramnath, Yihui Xie, JJ Allaire, Joe Cheng, Carson Sievert, and Kenton Russell. 2020. Htmlwidgets: HTML Widgets for R. https://github.com/ramnathv/htmlwidgets.

---

48. 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.↩︎