02: Create your site

By Alison Hill

May 26, 2021

New site, GitHub first

This is my recommended workflow for most users.

Create repo

To do ✔️

Create a new repository on GitHub from https://github.com/new:

  • Check to initialize with a README

  • Don’t add .gitignore- this will be taken care of later.

Screenshot 📷

Screenshot: Creating a new repository in GitHub

To do ✔️

From the main page of your new repository, and under the repository name:

  • Click the green Code button.

  • Choose either HTTPS or SSH (if you don’t know which, choose HTTPS). Choose by clicking on the clipboard icon to copy the remote URL for your new repository. You’ll paste this text into RStudio in the next section.

Screenshot 📷

Screenshot: Clone a repository from GitHub

Create project

We just created the remote repository on GitHub. To make a local copy on our computer that we can actually work in, we’ll clone that repository into a new RStudio project. This will allow us to sync between the two locations: your remote (the one you see on github.com) and your local desktop.

To do ✔️

Open up RStudio to create a new project where your website’s files will live.

  1. Click File > New Project > Version Control > Git.

  2. Paste the copied URL from the previous step.

  3. Be intentional about where you tell RStudio to create this new Project on your workstation.

  4. Click Create Project.

Screenshot 📷

Screenshot: Clone a Git repository in RStudio

Create site

To do ✔️

Use blogdown to create the Hugo Apéro example website:

> library(blogdown)
> new_site(theme = "hugo-apero/hugo-apero", 
           format = "toml",
           sample = FALSE,
           empty_dirs = TRUE)

Take a moment to read through the message that prints your console (shown right) - importantly, it tells you how to start and stop the server so you can preview your site.

Message 💬

― Creating your new site
| Installing the theme hugo-apero/hugo-apero from github.com
trying URL 'https://github.com/hugo-apero/hugo-apero/archive/main.tar.gz'
downloaded 21.3 MB

| Adding the sample post to content/blog/2020-12-01-r-rmarkdown/index.Rmd
| Converting all metadata to the YAML format
| Adding netlify.toml in case you want to deploy the site to Netlify
| Adding .Rprofile to set options() for blogdown
― The new site is ready
○ To start a local preview: use blogdown::serve_site(), or the RStudio add-in "Serve Site"
○ To stop a local preview: use blogdown::stop_server(), or restart your R session
► Want to serve and preview the site now? (y/n)

Screenshot 📷

Screenshot: New site in RStudio

To do ✔️

We are asked:

► Want to serve and preview the site now? (y/n)

Select y to let blogdown start a server for us.

Now, don’t trap your site in the RStudio Viewer pane. Let it out!

Click the icon to Show in new window (to the right of the 🧹 icon) to preview it in a normal browser window. When you do that, you’ll be re-directed to the site’s main homepage.

Screenshot 📷

Screenshot: Serving your site in RStudio

If you followed these steps successfully and are looking at a Hugo Apéro site in your local browser, you are all set to start configuring your site 🚀

New site, GitHub last

To do ✔️

Use the RStudio New Project Wizard to create a new blogdown project:

File -> New Project -> New Directory -> Website using blogdown

Screenshot 📷

Create a new website project in RStudio.

Figure 1: Create a new website project in RStudio.

To do ✔️

Fill out the fields as shown.

Click Create Project.

The project wizard then runs a function that creates a new site for you by doing the following steps:

  1. Creates and opens a new RStudio Project for the website;
  2. Downloads and installs the Hugo Apéro theme ( https://github.com/hugo-apero/) with an example site;
  3. Adds a sample .Rmd post;
  4. Creates a netlify.toml file to help you deploy your site to Netlify, and
  5. Creates an .Rprofile file to set your blogdown options (some have been set up for you).

Screenshot 📷

Create a website project based on blogdown.

Figure 2: Create a website project based on blogdown.

To preview the site locally, run blogdown::serve_site() from the console or equivalently, click on the RStudio addin “Serve Site” (see Figure 3).

Use the blogdown addin to serve the site.

Figure 3: Use the blogdown addin to serve the site.

If you are not using RStudio, you can create a new empty directory, and call the new_site() function in the directory in the R console to create a new site project:

blogdown::new_site(theme = "hugo-apero/hugo-apero",
                   format = "toml")

This will generate the theme’s example site. To preview it locally, run:

blogdown::serve_site()

Then you can edit or discard the pages under content, and change things in the site configuration (config.toml) file.

To use Git/GitHub now with this existing site that you can serve locally, the easiest way is to use the usethis package:

# install.packages("usethis")
usethis::use_git()
usethis::use_github() # requires a GitHub PAT

If this doesn’t work for you, revisit our section on how to set up GitHub.

Update theme

To update your theme, inside your website project, use:

blogdown::install_theme(theme = "hugo-apero/hugo-apero",
                        update_config = FALSE, 
                        force = TRUE)

Existing site

To convert an existing Hugo site from another theme, there are quite a few steps, and it may not be a smooth process. I recommend doing this in a branch on GitHub.

First, to install this theme alongside one you’d like to convert from, use the same code as above for updating the theme files:

blogdown::install_theme(theme = "hugo-apero/hugo-apero",
                        update_config = FALSE, 
                        force = TRUE)

Next, use blogdown::hugo_version() to check your local Hugo version:

> blogdown::hugo_version()
[1] ‘0.80.0

Make sure you have at least version 0.80.0 installed. If not, try blogdown::install_hugo(). To pin this Hugo version to your website project, use:

> blogdown::config_Rprofile()

And add this line (make sure there is an empty line at the end of this file, and restart your R session to make these changes go into effect):

options(blogdown.hugo.version = "0.80.0")

Now, the next steps are trial-and-error, depending on your theme. Here is one user’s steps followed to convert from the Academic/Wowchemy theme, with corresponding commits in their repo:

  1. Install theme alongside Academic commit

  2. Change theme to hugo-apero in config.toml commit

  3. Copy all Academic shortcodes to layouts/ in root commit

  4. Remove all assets in website root commit

  5. Remove all custom layouts in website root commit

  6. Copy over Apéro example site config.toml file commit

  7. Remove Academic config/ directory commit