Make a Personal Website with blogdown

Useful Resources

Before going through the instructions, I’ve included some resources that I found really useful.

• A similar blog post with instructions on getting started
• A bookdown about blogdown
  • Chapter 1, section 2.4, and chapter 3 are especially useful for starting from scratch
  • Chapter 4 is useful if you want to migrate a website from Jekyll, WordPress, and other systems
• A youtube video by John Muschelli
• The GitHub repository for blogdown
• Hugo theme site
• Netlify
• My website created using blogdown
• My GitHub

Pearls of Wisdom

I found creating a website cumbersome for two reasons:

1. You have to generate and format content (lots of humble bragging and writing involved here)
2. You have to code and customize the actual website layout

Though 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.

1. Create the content
   1. Find a few examples of websites you really like and make a note of what you like about them. Content? Layout? Etc.
   2. Write some of the basic content that you will be including. Doing this in R Markdown will help you save some time later. For example, I knew I wanted an about me page so I wrote some material and considered what kind of layout I would need.
   3. Finalize all the content you will be including and pay attention to what characteristics you will need in a Hugo template. For example, do you need a picture on the home page? Do you want more of a blog style website or a personal website?
2. Deploy the template and customize your website a. After figuring out what you like and generating some content find a Hugo theme that matches what you want and need. The less you have to change about the template the easier the process. Customizing the template may require a basic knowledge of html, css, and java so choose your template wisely. b. Deploy the theme using Netlify. For this step, don’t change anything about the theme template simply get the website direcotry locally, on GitHub, and deployed using Netlify. c. At this point, you are ready to start making some changes. Start by making your large obvious changes. These may include adding some of your content, changing some images, adapting some of the layout. If this proves difficult you should consider another theme. I personally went through about 5 themes before settling in on my current theme. d. After playing with, pick your favorite and begin moving your content over from 1.
3. Finalize content and go live!

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.

Basics of blogdown

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.

blogdown::serve_site()

blogdown::build_site()

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!

1. Create a GitHub Repositories

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.

2. Clone your Repository

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.

3. Create a New Project in R

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 setwd().

4. Generate a Theme

Now we are ready to build a site using blogdown.

blogdown::new_site()

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:

blogdown::serve_site()

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.

4. Adapting Content

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.

Some ideas:

• Change the pages titles
• Move over some of the content you drafted
• Add pictures
• Add files, like a CV, for download
• Add blog posts or mini projects you’ve been working on

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.

5. Push Changes to Git

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.

1. R Studio

Go to 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 Commit and 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.

2. Terminal

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.

6. Deploy Using Netlify

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.

Let’s deploy!

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.

7. Set Up a Custom Domain

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.