Intro to R Blogdown

Picking a Theme

• Navigate to http://themes.gohugo.io
• Look at the demo site provided by the theme creator (unless you are a html/css wizard, don’t expect to change it too much)
• Once you’ve chosen a theme, find the link to its GitHub repository (e.g. https://github.com/user/repo)

Where to host your page

Yihui (blogdown creator) suggests Netlify for deployment. However, I didn’t want to sign up for another site, so I stuck with GitHub and GitLab to demonstrate. A larger list of deployment options and instructions can be found in the deployment section of the Blogdown book.

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  only:
    - master

RStudio Setup

If you haven’t already, you need to install the blogdown package.

## Install from CRAN
install.packages("blogdown")
## Or, install from GitHub
if (!requireNamespace("devtools")) install.packages("devtools")
devtools::install_github("rstudio/blogdown")

Since blogdown is based on Hugo, you also need to install Hugo.

blogdown::install_hugo()

Configuration

The config.toml file is your first stop to get the site working. TOML is sort of a meta language that tells your project files how to interact. While most themes just use the config.toml, the Academic theme uses the config files located here: config/_default (not super intuitive unless you read their docs). Note that you can comment (inactivate) items in TOML using #.

There is a lot of useful info on it in the config section of the Blogdown book. It is the key to getting things launched.

Some updates you will want to make right away (if not already present):

ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]
baseURL = "https://username.github.io/"
relativeURLs= true

Additionally, if you use Github for publishing your site:

publishDir = "../username.github.io"

Okay, let’s try it. Use the following commands in the console.

blogdown::serve_site()
blogdown::build_site()

This should create a bunch of new files and updates to our files. Let’s commit and push to our git repo and check out our published page. Note that the intial push might have some issues you need to fix. It’s all part of the fun!

Your page will be https://username.github.io/ or https://username.gitlab.io/ depending on the host you chose above.

Creating and Modifying Your Content

First, you need to know where to create your content. The structure generated by your template will include several folders. However, you shouldn’t make changes to the majority of these. The ones you will mainly be working with are:

• Content (most important)
• Static/Images (add your image files here)
• Styles (more advanced)
• Themes/Layouts (more advanced)

Let’s make a blog post using Rmarkdown. Most templates includes a blog post to use as your baseline (we made sure of this above by setting the argument sample = TRUE in our download of the theme). You should only modify files found in the Content folder, i.e. Content/Blog, Content/Post, etc. Note that you should not hit Knit or files will be produced that confuse things.

Advanced Topics

Inevitably, you will want to customize some things on your site. These should be avoided if you don’t want to delve into the more technical aspects of building a site. Here are some of things I’ve done in the past.

CSS: For advanced customization of the style, you can link custom CSS. These should go in the Static/CSS folder. In the Academic theme (and others), this may require additional configuration in the TOML file(s). In Academic, within config/_default/params.toml , set the parameter using custom_css = ["custom.css"]. For example, let’s override some of Academic’s default styles. First, define custom_css = ["override.css"] in config/_default/params.toml. Then we can create the file static/css/override.css. To see some things we might want to customize, we can look at the current CSS located here: themes/ThemeName/layouts/partials/css.

Modifying Layouts: Another thing you might want to do is add or delete items in the site. Sometimes the only way to do this is to modify the theme layout. By navigating to themes/ThemeName/layouts/partials, you can see the html structure of the site and modify if needed.