An updated tutorial to set up a blogdown blog

You can also check this post, written in #blogdown, here: r-blogdown-setup-in-github-2.

This is an updated blog post from the previous version: R Blogdown Setup in GiHub.

Inspired by this great blog, by Elio Campitelli: eliocamp.github.io/codigo-r and his settings on the hugo-tranquilpeak theme, by Louis Barranqueiro & Thibaud Leprêtre.

As the changes I made imply many modifications in paths, directories (some very subtle), they invalidate much of my previous tutorial. The changes I basically made are:

  • I still use Github pages for hosting. However, I changed the rendering folder from  master to  docs.
  • Made some other fixes to the  config.toml file.

The steps I followed are detailed here:

Git & GitHub repos

  •  Set up a GitHub account, following for example this.
  •  Set up a new GitHub repo with a name of your choice (in my case talesofr). See this  and this.
  •  Activate GitHub pages. For this, you must go to the /settings section of your repo and find the epigraph “GitHub Pages”. In the dropdown menu, select:   master branch /docs folder and save.

Activating GitHub pages

Activating GitHub pages

  • Create a  git local repo in your machine:
    • Create manually a new directory called like your repository, e.g. talesofr.
    • Run in the terminal (Windows users have to install  git first):

  • You can add a .gitignore text file to the root directory of your repo. This tells  git what files not to add to the repo, even if they are into the folder. One example of .gitignore file is this.
  • For now, your repo is ready. We will now focus in creating & customising our Blogdown.

RStudio and blogdown setup

  • We will open RStudio (my Version is 1.1.419).
    • First, you may need to install Blogdown in R:

    • In RStudio, select the Menu > File > New Project following the lower half of these instructions. The wizard for setting up a Hugo Blogdown project should be available in your RStudio version.

Creating new Project

Creating new Project

Selecting Hugo Blogdown format

Selecting Hugo Blogdown format

Selecting Hugo Blogdown theme

Selecting Hugo Blogdown theme

A config.toml file appears

config.toml file appears


Customising paths and styles

Before we build and serve our site, we need to tweak a couple of things in advance, if we want to smoothly deploy our blog into GitHub pages.

Modify config.toml file

To integrate with GiHub pages, there are the essential modifications at the top of our config.toml file:

  • We need to set up the base URL to the “root” of the web page (https://[USERNAME].github.io/[REPO_NAME] in this case).
  • By default, the web page is published in the  /public folder. We need it to be published in the  /docs folder of the repository (we must create it if it doesn’t exist yet), to match the structure of the GitHub docs branch (we’ll see what that means):

  • Other useful global settings:

Images & styling paths

We can revisit the config.toml file to make changes to the default settings.

The file for the logo that appears in the corner must be placed in the  /docs/logo.png path. To modify it in the config.toml:

The cover (background) image must be located in  /themes/hugo-tranquilpeak-theme/static/images. To modify it in the config.toml:

We want some custom css and js. We need to locate them in  /static/css/my-style.css and in  /static/js/myjs.js respectively.

Custom css

Now, we can add arbitrary classes to our css file! (see above).

Since I started writing in Bootstrap, I love it a lot. Since this theme already has bootstrap classes, I brought some others I didn’t find in the theme (they’re available for .md files, but currently not for .Rmd)

Here is an example of a custom css file that can be copied to the file  /static/css/my-style.css:

Also, we have font-awesome icons!

Update! Hugo shortcodes in .Rmd !

Searching through blogdown/issues in GitHub, I found this good trick by Yihui:
You can add Hugo shortcodes if you wrap them with the function  htmltools:HTML

Custom javascript

We can also add really cool functions to enhance our post! (see the blogdown version of this post).

Here is the code of the button:

And here is the javascript function that you can copy into 

/static/js/myjs.js

:

Site build with blogdown

Once we have ready our theme, we can add some content, modifying or deleting the various examples we will find in  /content/post.

We need to make use of Blogdown & Hugo to compile our .Rmd file and create our html post:

In the viewer, at the right side of the IDE you can examine the resulting html and see if something didn’t go OK.

Deploying the site

Updating the local git repository

This can be done with simple git commands:

Pushing to GitHub

Just go to the page https://[USERNAME].github.io/[REPO_NAME] and enjoy your blog!


Add R code

Works just the same as in Rmarkdown. R code is compiled into an html and published as static web content in few steps. Welcome to the era of reproducible blogging!

The figure 1 uses the  ggplot2 library:

diamonds plot with ggplot2.

Figure 1: diamonds plot with ggplot2.


A new post in blogdown

I know there is a procedure to create a new post using the interface in RStudio (via the “Addins” button in RStudio IDE) but this one will also work:

I copied a blank .Rmd file into the folder  /content/post. I gave it a different name than the other post, with the date and some explanatory text (I called it “2017-08-22-new-post.Rmd”).

Then, I added an appropriate YAML heading (similar to the one in the previous post, but changing dates and times). Beware, as the YAML header indent-sensitive:

Finally I added some content to the Rmarkdown and saved the changes.

We need to make use of Blogdown & Hugo to compile our .Rmd file and create our html post:

In the viewer, at the right side of the IDE you can examine the resulting html and see if something didn’t go OK.

DEPLOYING THE SITE WITH THE NEW POST

Updating the local git repository

This can be done with simple git commands:

Pushing to GitHub

You can rinse and repeat this procedure for the rest of the posts.


This .Rmd source code

You can download it from here

 

출처: R Blogdown Setup in GitHub (2) | Tales of R