1.2 A quick example
From our experience, Hugo’s documentation may be a little daunting to read and digest for beginners.3 For example, its “Quickstart” guide used to have 12 steps, and you can easily get lost if you have not used a static website generator before. For blogdown, we hope users of all levels can at least get started as quickly as possible. There are many things you may want to tweak for the website later, but the first step is actually fairly simple: create a new project under a new directory in the RStudio IDE (
File -> New Project), and call the function in the R console of the new project:
Then wait for this function to create a new site, download the default theme, add some sample posts, open them, build the site, and launch it in the RStudio Viewer, so you can immediately preview it. If you do not use the RStudio IDE, you need to make sure you are currently under an empty directory,4 in which case
new_site() will do the same thing, but the website will be launched in your web browser instead of the RStudio Viewer.
Now you should see a bunch of directories and files under the RStudio project or your current working directory. Before we explain these new directories and files, let’s introduce an important and helpful technology first: LiveReload. This means your website5 will be automatically rebuilt and reloaded in your web browser6 when you modify any source file of your website and save it. Basically, once you launch the website in a web browser, you do not need to rebuild it explicitly any more. All you need to do is to edit the source files, such as R Markdown documents, and save them. There is no need to click any buttons or run any commands. LiveReload is implemented via
blogdown::serve_site(), which is based on the R package servr (Xie 2017d) by default.7
new_site() function has several arguments, and you may check out its R help page (
?blogdown::new_site) for details. A minimal default theme named “hugo-lithium-theme” is provided as the default theme of the new site,8 and you can see what it looks like in Figure 1.1.
You have to know three most basic concepts for a Hugo-based website:
The configuration file
config.toml, in which you can specify some global settings for your site. Even if you do not know what TOML is at this point (it will be introduced in Chapter 2), you may still be able to change some obvious settings. For example, you may see configurations like these in
baseurl = "/" languageCode = "en-us" title = "A Hugo website" theme = "hugo-lithium-theme" [[menu.main]] name = "About" url = "/about/" [[menu.main]] name = "GitHub" url = "https://github.com/rstudio/blogdown" [[menu.main]] name = "Twitter" url = "https://twitter.com/rstudio"
You can change the website title, e.g.,
title = "My own cool website", and update the GitHub and Twitter URLs.
The content directory (by default,
content/). This is where you write the R Markdown or Markdown source files for your posts and pages. Under
content/of the default site, you can see
post/directory containing a few posts. The organization of the content directory is up to you. You can have arbitrary files and directories there, depending on the website structure you want.
The publishing directory (by default,
public/). Your website will be generated to this directory, meaning that you do not need to manually add any files to this directory9. Typically it contains a lot of
*.htmlfiles and dependencies like
*.js, and images. You can upload everything under
public/to any web server that can serve static websites, and your website will be up and running. There are many options for publishing static websites, and we will talk more about them in Chapter 3 if you are not familiar with deploying websites.
Xie, Yihui. 2017d. Servr: A Simple Http Server to Serve Static Files or Dynamic Documents. https://CRAN.R-project.org/package=servr.
One day I was almost ready to kill myself when I was trying to figure out how
_index.mdworks by reading the documentation over and over again, and desperately searching on the Hugo forum.↩
Check the output of
list.files('.')in R, and make sure it does not include files other than
LICENSE, the RStudio project file (
Until you set up your website to be deployed, LiveReload only updates the local version of your website. This version is only visible to you. In order to make your website searchable, discoverable, and live on the internet you will need to upload your website’s files to a site builder. See Chapter 3 for details.↩
You can also think of the RStudio Viewer as a web browser.↩
By running either
build_site(), files will be generated and published in your publishing directory automatically.↩