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
D.3 Building a website for local preview
blogdown::build_site() has an argument
local that defaults to
FALSE, which means building the website for publishing instead of local previewing. The mode
local = TRUE is primarily for
blogdown::serve_site() to serve the website locally. There are three major differences between
local = FALSE and
local = TRUE:
config.tomlis temporarily overridden by
"/"even if you have set it to a full URL like
"http://www.example.com/".41 This is because when a website is to be previewed locally, links should refer to local files. For example,
/about/index.htmlshould be used instead of the full link
http://www.example.com/about/index.html; the function
/about/index.htmlmeans the file under the
public/directory, and can fetch it and display the content to you, otherwise your browser will take you to the website
http://www.example.cominstead of displaying a local file.
Draft and future posts are always rendered when
local = TRUE, but not when
local = FALSE. This is for you to preview draft and future posts locally. If you know the Hugo command line, it means the
hugocommand is called with the flags
-D -F, or equivalently,
There is a caching mechanism to speed up building your website: an Rmd file will not be recompiled when its
*.htmloutput file is newer (in terms of file modification time). If you want to force
build_site(local = TRUE)to recompile the Rmd file even if it is older than the HTML output, you need to delete the HTML output, or edit the Rmd file so that its modification time will be newer, or click the RStudio addin “Touch File.” This caching mechanism does not apply to
local = FALSE, i.e.,
build_site(local = FALSE)will always recompile all Rmd files, because when you want to publish a site, you may need to recompile everything to make sure the site is fully regenerated. If you have time-consuming code chunks in any Rmd files, you have to use either of these methods to save time:
Turn on knitr’s caching for time-consuming code chunks, i.e., the chunk option
cache = TRUE.
Do not call
blogdown::hugo_build()instead. The latter does not compile any Rmd files, but simply runs the
hugocommand to build the site. Please use this method only if you are sure that your Rmd files do not need to be recompiled.
You do not need to worry about these details if your website is automatically generated from source via a service like Netlify, which will make use of
baseurl and not use
-D -F by default. If you manually publish the
public/ folder, you need to be more careful:
If your website does not work without the full
baseurl, or you do not want the draft or future posts to be published, you should not publish the
public/directory generated by
serve_site(). Always run
blogdown::hugo_build()before you upload this directory to a web server.
If your drafts and future posts contain (time-)sensitive information, you are strongly recommended to delete the
/public/directory before you rebuild the site for publishing every time, because Hugo never deletes it, and your sensitive information may be rendered by a certain
build_site(local = TRUE)call last time and left in the directory. If the website is really important, and you need to make sure you absolutely will not screw up anything every time you publish it, put the
/public/directory under version control, so you have a chance to see which files were changed before you publish the new site.
baseurlcontains a subdirectory, it will be overridden by the subdirectory name. For example, for
baseurl = "http://www.example.com/project/",
build_site(local = TRUE)will temporarily remove the domain name and only use the value