Build a website

Build the site through Hugo, and optionally (re)build R Markdown files.

Usage

build_site(local = FALSE, run_hugo = TRUE, build_rmd = FALSE, ...)

Arguments

local

Whether to build the website locally. This argument is passed to hugo_build(), and local = TRUE is mainly for serving the site locally via serve_site().

run_hugo

Whether to run hugo_build() after R Markdown files are compiled.

build_rmd

Whether to (re)build R Markdown files. By default, they are not built. See ‘Details’ for how build_rmd = TRUE works. Alternatively, it can take a vector of file paths, which means these files are to be (re)built. Or you can provide a function that takes a vector of paths of all R Markdown files under the content/ directory, and returns a vector of paths of files to be built, e.g., build_rmd = blogdown::filter_timestamp. A few aliases are currently provided for such functions: build_rmd = 'newfile' is equivalent to build_rmd = blogdown::filter_newfile, build_rmd = 'timestamp' is equivalent to build_rmd = blogdown::filter_timestamp, and build_rmd = 'md5sum' is equivalent to build_rmd = blogdown::filter_md5sum.

...

Other arguments to be passed to hugo_build().

Details

You can use serve_site() to preview your website locally, and build_site() to build the site for publishing. However, if you use a web publishing service like Netlify, you do not need to build the site locally, but can build it on the cloud. See Section 1.7 of the blogdown book for more information: https://bookdown.org/yihui/blogdown/workflow.html.

For R Markdown posts, there are a few possible rendering methods: html (the default), markdown, and custom. The method can be set in the global option blogdown.method (usually in the .Rprofile file), e.g., options(blogdown.method = "custom").

For the html method, .Rmd posts are rendered to .html via rmarkdown::render(), which means Markdown is processed through Pandoc. For the markdown method, .Rmd is rendered to .md, which will typically be rendered to HTML later by the site generator such as Hugo.

For all rendering methods, a custom R script R/build.R will be executed if you have provided it under the root directory of the website (e.g. you can compile Rmd to Markdown through knitr::knit() and build the site via hugo_cmd()). The custom method means it is entirely up to this R script how a website is rendered. The script is executed via command line Rscript "R/build.R", which means it is executed in a separate R session. The value of the argument local is passed to the command line (you can retrieve the command-line arguments via commandArgs(TRUE)). For other rendering methods, the R script R/build2.R (if exists) will be executed after Hugo has built the site. This can be useful if you want to post-process the site.

When build_rmd = TRUE, all Rmd files will be (re)built. You can set the global option blogdown.files_filter to a function to determine which Rmd files to build when build_rmd = TRUE. This function takes a vector of Rmd file paths, and should return a subset of these paths to be built. By default, options(blogdown.files_filter = identity. You can use blogdown::filter_newfile, which means to build new Rmd files that have not been built before, or blogdown::filter_timestamp to build Rmd files if their time stamps (modification time) are newer than their output files, or blogdown::filter_md5sum, which is more robust in determining if an Rmd file has been modified (hence needs to be rebuilt).