If you have read my first blog post you will already know that I create my website using blogdown, an R package that generates a static webpage from R markdown documents. A major source of information and inspiration for the direction of my website comes from data scientist, behavioral scientist, and award-winning educator: Alison Hill. To get you started with a website using her beautiful Hugo Apero theme, I suggest that you watch her workshop on YouTube which guides you through the process of creating and deploying your website step-by-step.
The main area where my workflow differs from that I have found on the internet is in deployment. Most places you look, you may find the suggestion to deploy your website through
Netlify. Given that I am provider a server by the University, I thought it most natural to house my website there. This presented a very slight hiccup since the most recent version of blogdown ([v1.0] (
https://blog.rstudio.com/2021/01/18/blogdown-v1.0/) at the time of writing this blog post) no longer generates a
public/ directory. A workaround is to use
blogdown::build_site() in place of
The directory system created by blogdown can be a bit confusing at first glance but here is the basic structure as I understand it. Here’s what my file system approximately looks like:
root ├── config.toml ├── index.Rmd # <---------------------- do not touch ├── ... ├── content │ ├── about │ ├── courses │ ├── _index.md # <------------- don't change the name of this! │ ├── data311 │ | ├── featured.png # <------ don't change the name of this! │ └── stat230 │ └── blog │ ├── _index.md # <------------- don't change the name of this! │ ├── 2020-06-09-my-first-blog-post │ | ├── featured.png # <------- don't change the name of this! │ └── 2020-07-09-blogdown-cheatsheet ├── data ├── layouts ├── public ├── R └── build.R # <------------------- one line of code ├── resources ├── static └── themes # <--------- do not touch
Depending on which theme you are using (I’m using Hugo-apero) your directory may be structured slightly different. I restrict discussion to what I consider to be the main folders/files of interest, but you can read more about the directory structure here.
At the root of each new page (aka Hugo
page bundle), you’ll find a
_index.md file. This needs to be here with that exact name. In this file you can configure how that section of your website looks. For example, in
/blog/_index.md you can change
list-grid to change how the summary of your blog posts are displayed.
There are two different types of page bundles will encounter:
Leaf bundles: a directory at any hierarchy within
content/that contains an
Branch bundles any directory at any hierarchy within
content/that contains at least an
As the name suggests, a leaf bundle will have no children (i.e. not sub-directories1 containing more pages for your website). Within a leaf bundle, you will have both page and non-page items (eg images, pdf, .csv files). This is a summary of how I understand it.
content/ ├── about # <------------------------------------ branch bundle │ ├── _index.md │ ├── header # <------- leaf bundle │ ├── main # <------- leaf bundle │ └── about # <------- leaf bundle ├── blog # <------------------------------------ branch bundle │ ├── _index.md │ ├── 2021-06-09-my-first-blog-post # <------- leaf bundle │ | ├── index.md │ | └── featured.jpg │ └── 2021-07-09-how-to-create-a-website # <-- leaf bundle │ ├── index.Rmarkdown | ├── images # <------------------------ (not a bundle) │ │ ├── image1.jpg │ │ └── image2.png │ └── data.csv │ └── courses # <-------------------------------- branch bundle ├── _index.md ├── stat230 # <---------------------------- leaf bundle | ├── index.md | └── featured.jpg └── data311 # <---------------------------- leaf bundle ├── index.md └── featured.jpg
Each page contains a markdown file which begins with a YAML (Yet Another Markup Language).
This file contains a bunch of meta-data for you site including some configuration options. I mainly focus on the self-explanatory content in this file and defer to Hugo-docs for a more thorough explanation.
baseURLshould be changed to the base URL of the webpage for your served website.
authorChanging this won’t change anything visibly on your webpage, but it will appear when you share the site and used in google search engines (so change it!)
[params]variables is Hugo-apero specific details.
faviconis the little icon that appears in your browser tab (I changed mine to a little roman numerals 4, or IV)
themebuilt-in colour theme options
[[params.social]]is where you add/delete social icon/handles. You can read up about how to change those here. In a nutshell you can basically make clickable Font Awesome and Academicons icons (e.g. ) to link to your social/academic media (eg. Youtube channel, github, google scholar). For the Hugo-apero theme, this populates in the landing page as well as the “About” sidebar.
content directory is where the majority of your R markdown documents will live. I have seen some examples which store their markdown files in
static and I’m not exactly privy on when and why you should choose one over the other.
From the Hugo docs
All content for your website will live inside this directory. Each top-level folder in Hugo is considered a
content section. For example, if your site has three main sections—
tutorials—you will have three directories at
content/tutorials. Hugo uses sections to assign default content types.
This is where all (non R-generated) images should go? Everything in static gets copied into
public so be careful about what you place in this folder. I have read in several places that you should put images and data that your R markdown files depends on in the
static/ folder. (
2). Furthermore, you can store R markdown that produce non-html documents (eg presentation slides) in
Here Yihui says
another important application of the
static/directory is to build Rmd documents with custom output formats… For example, you can generate a PDF or presentations from Rmd documents under this directory, so that Hugo will not post-process them but simply copies them to
public/for publishing. To build these Rmd files, you must provide a custom build script
R/build.R(see Section D.9) … [with] a single line of code in this script:
Read more about it on the minimal blogdown demo site
I have also read, however, that by leveraging Hugo’s page bundles, you can put resource files such a images directly in directory in which your post lives 3. Come back to this
This folder contains all the files that need to be copy and pasted to your hosting server. This folder is not created when you build your website using
blogdown::serve_site() but it is generated when you use
Don’t touch this folder. This contains all the guts of the theme and should be treated as Read Only!
- Open your website project (
- Run the Serve site addin (located in the Addins drop-down menu) (or type
blogdown::serve_site()into your Console)
- Preview it “live” in the viewer in RStudio or press the “Show in New Window” (button located beside the broom in the Viewer pane) to see it in your default browser.
- Create new content
- See your changes populate ever time you save your R markdown file.
- When you are ready to publish your new content, use
blogdown::build_site()(remember to use this instead of
serve_siteso that it generates a
publicfolder) and upload any new files created to your server.
Step 2. in the above Workflow launches LiveReload which rebuilds you site upon saving and previews it locally. Consequently, any changes you make to this site will not automatically be altering your site that lives on your hosting server. While it will preview by default in the Viewer Pane, please open it in your default browser since the Viewer may not preview everything properly (the browser in RStudio is out of date). As you create and save changes, you will see these populate in your local preview in your browser.
When you are happy with the changes you have made to your site:
- Build the site through Hugo using
- Securely copy the new/modified files to the server hosting your website. I use Cyberduck (using the SFTP protocol) to do this. For set-up all you need is the host name, user name and password.
To create a new blog post go to click the Addins drop-down menu from the toolbar and select “New Post” and fill in the appropriate information in the pop-up window. You can update this information at a later date by using the “Update Metadata” (found in the same Addin drop-down menu).
You can either choose a regular Markdown (
.md), R Markdown (
.Rmd), or R Markdown (
.Rmarkdown) file. While I don’t fully understand the reasoning of this one quite yet, it seems that
.Rmarkdown files are generally preferred over
.Rmd files (
2). The top of your file will contain the
As mentioned to earlier, you can use the
static/ folder to house R markdown documents used to create non-html outputs. Here we will discuss how to store and knit source files for creating Xaringan slides (for more on these you can check out
this blog post). Click
here for a live demo of Alison Hill doing this for the R-Ladies Tunis workshop. The steps are as follows:
- Create a
static/(it doesn’t have to be called
- Create (or copy) a xaringan presentation, let’s call it
- Knit it2
- Link to it in your site via
For example, a simple link
[slides](/slides/ninja.html) will link to the ninja template slides that I have created and saved within the
Below you will find a number of resources that I have found useful in the creation of my own cite (in order of relevance):
- Up and Running with blogdown
- blogdown book
- A minimial blogdown demo site
- Introduce yourself online using blogdown and Hugo Apèro
note that a leaf bundle can have sub-directories of resource files. For instance, the leaf bundle
2021-07-09-how-to-create-a-website/has the sub-directory
images/for storing image files, but this folder does not contain any pages (i.e. .md files that get converted to a page on your website). ↩︎
I think there is a way to avoid having to knit here but let’s just follow what Alison does for the time being. ↩︎
note the leader forward slash and that we do not need to specify