Creating an Academic Website with Blogdown, GitHub, and Netlify

This tutorial will walk you through the steps for creating a free academic portfolio website with Blogdown, GitHub and Netlify. We will be using the popular Academic theme. Before getting started, you will need to set up a few things:

The R programming language installed on your computer
The RStudio Desktop installed on your computer
The Git version control system installed on your computer

I recommend GitHub Desktop for new users of Git
A free GitHub account for managing your source files

Setting Up Your GitHub Repository

GitHub is a hosting service for code, built around the Git distributed version-control system. We will be using GitHub as a content management system for our website files.

Git and GitHub: When you use Git and GitHub, you are maintaining two copies of your code files: a local git repository (on your computer) and a remote git repository (on GitHub). These two repositories are intended to be in sync with each other.

Log in to your GitHub account
Visit the Academic theme code repository: https://github.com/sourcethemes/academic-kickstart
Click on the Fork button. This will create a copy of the Academic Kickstart code repository on your GitHub account.
On your forked repository's homepage, click on the Clipboard icon next to the reposity's URL. We will need this URL for the next step.

Setting Up Your RStudio Project

RStudio is a desktop application that includes a full-featured development environment for programming in R.

Open RStudio and create a new project: File -> New Project -> Version Control
Select Git
Paste the URL for your GitHub fork: https://github.com/YOUR_USER_NAME/academic-kickstart.git
Enter in a project directory name (e.g "personal-website")
Choose a directory on your computer where this project will be created

Note: if you get an error that RStudio can't create a project with Version Control, it means that either you don't have Git installed or RStudio can't find git. Consult these instructions for help troubleshooting.

Open up the Terminal tab in RStudio
Change directories to your website folder: cd personal-website
Finish installing the Academic theme: git submodule update --init --recursive
If you've never pushed to a GitHub repository, add your GitHub credentials:

  git config --global user.email "[email protected]"
  git config --global user.name "Your GitHub User Name"

Installing Blogdown

Blogdown is an open source R package that produces static HTML websites from Markdown and R Markdown files. It was developed by Yihui Xie to help statisticians and data scientists create websites using tools for R programming contexts.

In RStudio, open the R Console
Install the Blogdown package: install.packages("blogdown")
Install the Hugo static site generator: blogdown::install_hugo(force = TRUE)
In the Files tab, click on the personal-website directory
In the Files tab, open up the config/_default directory and move config.toml file to the root of the personal-website directory

Click on the "More" button, then select "Move..." to be prompted to select a target directory
Let's make sure everything's installed correctly. In RStudio, click on Addins in the menu bar and select Serve Site. This will start a preview server on your computer to view the current state of your website.
Open up a web browser and go to: http://localhost:4321

Editing Your Website

Now that Blogdown and Hugo are installed on your computer and your source files are connected to your GitHub account, you are ready to use RStudio to edit and add your information to personalize your website. Visit the Academic theme's documentation website to learn about the theme's features.

The starter website includes a widget that appears at the top of the home page. You can remove this by deleting demo.md file in the /content/home/ folder.

Personal Settings

You edit the personal settings for your website by editing the params.toml file located in the /config/_default/ folder. These include:

Visual Settings: Academic provides several color themes and font options.
Contact Information: This file also includes options for adding your email and social media information.

Biographical Information

The biographical information displayed on the homepage can be edited in the _index.md file located in the /content/authors/admin folder.

Site Settings

You edit the personal settings for your website by editing the config.toml file located in the root of the /personal-website/ folder. This is where you can control the title of your site, add Google Analytics tracking, and enable comments.

Saving Changes by Pushing Edits to GitHub

Work that happens in a git repository is logged in a commit. A commit can have any number of changes on any number of files. Generally, it is best practice to keep commits small. When you make a commit in your local repository, it only exists locally. You also need to push your commits to GitHub.

In RStudio, click on the Git tab. This will show a list of files you have changed.

If you're seeing files you don't recognize, such as files in a /resources/ directory, you can add resources/ in a new line in your .gitignore file.

Click on the box for ever file you want to push to GitHub.
Click on Commit
Add a Commit message. This is required for good reason. Every commit is a snapshot of your codebase's history. Each message should give some rationale for why the change is being made.
When you're ready to push your commits to GitHub (say, at the end of a work session), click on the Push button in the Git tab.

Publishing Your Website

Because Blogdown produces static HTML, CSS, and JavaScript files, you can host your website on just about any web server. Netlify is a recommended free hosting option for websites built with static site generators, like Bookdown. GitHub Pages is another popular option for free hosting, but it's trickier to set up.

Sign up for a free account with Netlify. I recommend signing up with your GitHub credentials.
Click on New Site from Git
Select GitHub
Click on Configure Netlify on GitHub
Select the repository containing your website files
Use the default build settings
You website will be deployed to a random URL (like https://gallant-kilby-488611.netlify.com/). You can use the Netlify admin interface to use a custom domain and enable HTTPS.

Now, whenever you push new commits from your local repository to your GitHub repository, Netlify will rebuild and deploy your website. Enjoy!

chrisdaaz/blogdown-workshop.md