In this post, I am going to cover the basics to creating a website using
blogdown and Hugo. We will create and deploy a template website as well as cover some basics about changing content. You should be extremely comfortable coding in R, writing in R Markdown, and have a working knowledge of GitHub. You should have R, R Studio, R Markdown all installed on your computer and an account on GitHub before we start.
Before going through the instructions, I’ve included some resources that I found really useful.
I found creating a website cumbersome for two reasons:
blogdown and Hugo simplify creating the site, there is still a learning curve. In the end, you are left with a single product but breaking down the process into these separate tasks will streamline the workload and isolate debugging.
If some of this doesn’t make sense now, come back to this list after reading the blog post. Some of this can be done in parallel. What you really want to avoid is coding something new while adding new content since de-bugging involves two events to back track here. For example, if you are adding an image to a content page while playing with some of the parameters you won’t know which is to blame if the website doesn’t configure properly. It took me about 1 day to create the content I wanted on my site and about 3 days to create and customize the physical site using
blogdown and some light html coding.
In a nutshell,
blogdown is an effort to integrate R Markdown with static website generators, so that you can generate web pages dynamically. You can use R code chunks, or any languages that knitr supports, to generate tables and graphics automatically on any web page. Formatting pages uses R Markdown syntax so you don’t need to know html or java to render beautiful pages.
To get started let’s install the package and load it into memory.
## From CRAN install.packages('blogdown') ## From GitHub library(devtools) devtools::install_github('rstudio/blogdown') # Load into memory library(blogdown)
blogdown has a variety of functions to help in making and changing your website but I found that I only used 3.
blogdown::new_site(dir = ".", install_hugo = TRUE, format = "toml", sample = TRUE, theme = "yihui/hugo-lithium-theme", hostname = "github.com", theme_example = TRUE, serve = interactive())
This function is used primarily to create a new site. Once you settle on a theme, you won’t need this function anymore.
These functions do almost the same thing.
blogdown::serve_site() will build and show your website dynamically in the R Studio viewer. The website in the viewer is dynamic in that you can click on the material and be re-directed.
blogdown::build_site() builds the site but doesn’t put it into the viewer.
blogdown uses LiveReload technology. This means your website automatically builds and reloads in your viewer when you modify any source file when saving. Because of this, you won’t need the two previous functions very often.
Without further ado, let’s make a website!
I am going to assume you already have a GitHub account and have a basic understanding of GitHub. You don’t need to know much and I’ll cover all the material you will need to know for building the website.
We will create a new repository (repo). To do this, log in to GitHub and in the right corner click the
+ > New repository.
This will bring up a dialogue box. In this dialogue box, be sure to check to initialize with a README but don’t add .gitignore. We are going to use Netlify to host so name the repository whatever you want. If you want to use another hosting site, the name of the repository might matter.
Open the terminal then change the directory to where you would like to clone the repository. Use
cd and type the path where you are putting your repository. The path syntax is different for PC versus Mac users. Below I have included the Mac version. You will change the second line by putting your GitHub user name instead of avalcarcel9 and the repository you named your website instead of Sample_Website.
cd /Users/alval/Box/Teaching/blogdown git clone https://github.com/avalcarcel9/Sample_Website.git
Here is what should print if you did it correctly.
Cloning into 'Sample_Website'... remote: Counting objects: 3, done. remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 Unpacking objects: 100% (3/3), done.
When you go to your home page in GitHub you should now see this new repository.
In R go to
File > New Project > Existing Directory.
Now click on
Browse and select the directory where you just cloned the git repository and finish by clicking
Create. This will restart R.
When working on your website you should open the project or just be sure to set the working directory to the local GitHub hosted folder using
Now we are ready to build a site using
This will automatically start copying the default theme into your website directory. A .Rmd file typically opens up in R but you can exit out of it. If you need to force view the website type the following:
If you don’t like the theme you picked, it is best to completely delete all the files inside of the Sample_Website directory except the .Rproj and then type
blogdown::new_site(theme = 'new_theme'). This is why you want to play with the website and be very careful editing content before finalizing a theme. Without thinking you could lose lots of your hard work.
Delete all the files in your repository except the .Rproj and let’s create a new website with the “calintat/minimal” theme. You can browse all the themes on https://themes.gohugo.io/.
blogdown::new_site(theme = 'calintat/minimal')
Notice we did not have to follow the instructions in the README.md on https://github.com/calintat/minimal by going through
blogdown. That being said, sometimes there is useful information about customizing content in the README.md so I still suggest you look through it.
I am going to reiterate that the less you want to change about a theme the easier your job. Spend a lot of time picking a theme you think is beautiful and simple to adapt. I’ll note, it can be very challenging to switch themes and move content once you have gone live since not all themes are built the same way. If for some reason you want to change themes later do so with caution. I suggest saving your material in another folder on your computer and then starting fresh and just manually moving content over with your new template.
There are two main areas to adapt content. The config.toml inside the website directory and the material in the content folder. The content folder across different themes can be as simple as a single index.md that you can change or include many file types for a blog style page.
We will start by changing the main configurations for the website. Open the config.toml in R Studio. You should read thoroughly through the blogdown documentation to understand fully what is going on with this page and how to change it. There also may be some extra information on the template’s GitHub so check that out as well. The config.toml is where you can personalize most of the home content and some background material.
To change the pages or content on the site refer to content. The pages in here are typically in a Markdown format and easy to customize.
Playing with some of these items will give you an idea about how easy the template is to manipulate. There is more you can do to adapt the website and customize the template but you have to do more digging into the css files and html layouts so for this tutorial I’ve skipped this more complicated stuff.
Once you have begun using your site, there are
blogdown commands to easily create new posts. You can find more info here. Personally, I find it easier to just create a new folder in content and copy over a previous draft from another page.
There are two approaches to sending your changes to GitHub. The first is for beginners that aren’t familiar with GitHub. The second is for users that feel more comfortable with GitHub. For any issues related to GitHub www.google.com is your best friend.
Tools > Version Control > Commit. This will bring up this window
The “Commit message” is blank by default and you should type in your message. Try to actually track the changes you have made. Click
Commit. Then click
Push. You must push both
Push! Make sure messages returned don’t indicate any error then your changes should be visible on GitHub.
For this to work, you have to be working in the project. So if you exit out of R Studio and return to work on the website you have to
File > Open Project and select the project you created.
You can also go through the terminal.
cd /Users/alval/Box/Teaching/blogdown/Sample_Website git add -A git commit -m "message goes here" git push
The message returned varies depending on what you did but you should read it to be sure you successfully pushed your changes. GitHub will report an error if something did go wrong.
I personally prefer to go through terminal but if you are not comfortable with that then use R Studio.
At this point, we haven’t actually gone live with our website. We are going to use Netlify to host our website. There are other options but I’m not going to discuss them since I find Netlify to be the easiest to work with. See this page for more info on Netlify and other hosting possibilities.
Go to https://www.netlify.com/ and “Sign Up”. Use your GitHub info to create an account.
Just agree to what you need to (if you are comfortable with the agreements) and you now have a Netlify account. Click on “New site from Git > Continuous Deployment: GitHub”.
Netlify allows you to select from your existing GitHub repositories. Choose the repository you’ve been working from. This should bring you to this page:
The “Publish directory” is blank by default. Change it to public then “Deploy Site”. The page that follows will give you information about your site such as the domain. Copy the domain into your URL window and notice it will take you to your new website. The website you see here should be the same as when you used
blogdown::serve_site(). The content on the site updates automatically when you push changes to GitHub. That is, all you need to do is push your changes to GitHub and the website will automatically update. After this initial setup, you shouldn’t need to visit Netlify.
Netlify generated a URL or domain for your website. You can adapt this slightly through their website options but the URL will still need to have the .netlify base. If you want a custom domain, which you should so people can find you, then we can buy one from GoogleDomains. It is only 12$ per year, which is very cheap, and it is really easy to configure with Netlify.
Log in or create an account and purchase a domain. For the domain of interest, go to “Configure DNS” and scroll down to the “Custom resource records”.
Be sure that your settings match those listed here except alessandravalcarcel.netlify.com should be your Netlify generated domain. Now to connect it to Netlify, go to your Netlify home page. Click on the domain you would like to customize, then click on “Settings” and scroll down to “Domains”.
Add your custom domain here. The new domain can take up to 24 hours to work.