Creating a website

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

Site structure

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.

index files

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 layout: from list to list-grid to change how the summary of your blog posts are displayed.

Figure 1: Left: layout = list, Right: layout=list-grid

There are two different types of page bundles will encounter:

1. Leaf bundles: a directory at any hierarchy within content/ that contains an index markdown file.
2. Branch bundles any directory at any hierarchy within content/ that contains at least an _index.md file.

As the name suggests, a leaf bundle will have no children (i.e. not sub-directories¹ 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 

YAML

Each page contains a markdown file which begins with a YAML (Yet Another Markup Language).

config.toml

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.

• baseURL should be changed to the base URL of the webpage for your served website.
• title/author Changing 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.
  • favicon is the little icon that appears in your browser tab (I changed mine to a little roman numerals 4, or IV)
  • theme built-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

The 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—blog, articles, and tutorials—you will have three directories at content/blog, content/articles, and content/tutorials. Hugo uses sections to assign default content types.

static

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. ( 1, 2). Furthermore, you can store R markdown that produce non-html documents (eg presentation slides) in static/. 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:

blogdown::build_dir("static")

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

public

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

themes

Don’t touch this folder. This contains all the guts of the theme and should be treated as Read Only!

Workflow

1. Open your website project (.Proj file)
2. Run the Serve site addin (located in the Addins drop-down menu) (or type blogdown::serve_site() into your Console)
3. 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.
4. Create new content
5. See your changes populate ever time you save your R markdown file.
6. When you are ready to publish your new content, use blogdown::build_site() (remember to use this instead of serve_site so that it generates a public folder) 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.

Publishing New Content

When you are happy with the changes you have made to your site:

1. Build the site through Hugo using blogdown::build_site.
2. 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.

Creating new content

Blog posts

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 ( 1, 2). The top of your file will contain the YAML.

Embedding presentation slides

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:

1. Create a slides/ folder within static/ (it doesn’t have to be called slides)
2. Create (or copy) a xaringan presentation, let’s call it foo.Rmd file into static/slides/.
3. Knit it²
4. Link to it in your site via /slides/foo.html³)

For example, a simple link [slides](/slides/ninja.html) will link to the ninja template slides that I have created and saved within the slides/ folder. slides

References

Below you will find a number of resources that I have found useful in the creation of my own cite (in order of relevance):

1. Up and Running with blogdown
2. blogdown book
3. A minimial blogdown demo site
4. Introduce yourself online using blogdown and Hugo Apèro