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

• 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):

  cd /Git/talesofr # your path may be different
  git init # initiates repo in the directory
  git remote add origin https://github.com/[USERNAME]/talesofr # connects git local repo to remote Github repo
  git pull origin master # in case you have LICENSE and Readme.md files in the GitHub repo, they're downloaded to your machine

• 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:

  install.packages("blogdown")

  • 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

Selecting Hugo Blogdown format

Selecting Hugo Blogdown theme

A config.toml file appears

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):

baseURL = "https://aurora-mareviv.github.io/talesofr/"
publishDir = "docs"

• Other useful global settings:

draft: false # if set to true, changes will not be published
ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]
enableEmoji = true
...

picture = "logo.png" # the path to the logo

coverImage = "myimage.jpg"

  # Custom CSS. Put here your custom CSS files. They are loaded after the theme CSS;
  # they have to be referred from static root. Example
   [[params.customCSS]]
     href = "css/my-style.css"

  # Custom JS. Put here your custom JS files. They are loaded after the theme JS;
  # they have to be referred from static root. Example
   [[params.customJS]]
     src = "js/myjs.js"

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:

/* @import url('https://maxcdn.bootstrapcdn.com/bootswatch/3.3.7/cosmo/bootstrap.min.css'); may conflict with default theme!*/
@import url('https://fonts.googleapis.com/icon?family=Material+Icons'); /*google icons*/
@import url('https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css'); /*font awesome icons*/

.input-lg {
  font-size: 30px;
}
.input {
  font-size: 20px;
}
.font-sm {
    font-size: 0.7em;
}
.texttt {
  font-family: monospace;
}
.alert {
padding: 15px;
margin-bottom: 20px;
border: 1px solid transparent;
border-radius: 4px;
}
.alert-success {
color: #3c763d;
background-color: #dff0d8;
border-color: #d6e9c6;
}
.alert-danger,
.alert-error {
  color: #b94a48;
  background-color: #f2dede;
  border-color: #eed3d7;
}
.alert-info {
  color: #3a87ad;
  background-color: #d9edf7;
  border-color: #bce8f1;
}
.alert-gray {
  background-color: #f2f3f2;
  border-color: #f2f3f2;
}

/*style for printing*/
@media print {
    .noPrint {
       display:none;
   }
    }

/*link formatting*/
a:link {
    color: #478ca7;
    text-decoration: none;
} 
a:visited {
    color: #478ca7;
    text-decoration: none;
}
a:hover {
    color: #82b5c9;
    text-decoration: none;
}

An example of the alert-danger class:

class="well alert alert-danger text-center">
   alert-danger

Also, we have font-awesome icons!

htmltools::HTML("{{< hl-text danger >}}
              this is a highlighted danger text
              {{< /hl-text >}}")

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:

class="button well alert alert-danger text-center" id="myButton" onclick="alertColor()">
   alert-danger 

And here is the javascript function that you can copy into /static/js/myjs.js:

function alertColor() {
  var result = "<span class='fa fa-info-circle'></span> alert-info";
  document.getElementById("toInfo").innerHTML = result; 
  document.getElementById("myButton").style.backgroundColor = "#d9edf7";
  document.getElementById("myButton").style.color = "#3a87ad";
  document.getElementById("myButton").style.borderColor = "#bce8f1";
}

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:

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

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

Updating the local git repository

This can be done with simple git commands:

cd /Git/[REPO_NAME] # your path to the repo may be different
git add . # indexes all files that wil be added to the local repo
git commit -m "Starting my Hugo blog" # adds all files to the local repo, with a commit message

Pushing to GitHub

git push origin master # we push the changes from the local git repo to the remote repo (GitHub repo)

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

Deploying the site with the new post

cd /Git/[USERNAME].github.io # your path to the repo may be different
git add . # indexes all files that wil be added to the local repo
git commit -m "Adding a new post" # adds all files to the local repo, with a commit message

git push origin master # we push the changes from the local git repo to the remote repo (GitHub repo)