Git & GitHub repos

• Setting a GitHub repo with the name [USERNAME].github.io (in my case aurora-mareviv.github.io). See this and this.
  
• Create a git repo in your machine:
  • Create manually a new directory called [USERNAME].github.io.
  • Run in the terminal (Windows users have to install git first):

  cd /Git/[USERNAME].github.io # your path may be different
  git init # initiates repo in the directory
  git remote add origin https://github.com/[USERNAME]/[USERNAME].github.io # 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

• 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

• We will open RStudio (v 1.1.336, development version as of today).

  • 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 may not be yet available in your RStudio version (not for much longer probably).

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/ in this case). We use the dot instead of “/” to allow tag URLs to link properly.
  
• By default, the web page is published in the “public” folder. We need it to be published in the root of the repository, to match the structure of the GitHub master branch:

baseurl = "/./"
publishDir = "./"

• 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
customCSS = ["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
customJS = ["js/myjs.js"]

Custom css

We can add arbitrary classes to our css file (see above).

Since I started writing in Bootstrap, I miss 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 my custom css file to date:

/* @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:

<div class="well alert alert-danger text-center">
  <span class="fa fa-minus-circle"></span> alert-danger
</div>

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. Click in the red button below!:

Here is the code of the button:

<div class="button well alert alert-danger text-center" id="myButton" onclick="alertColor()">
  <span id="toInfo"> <span class="fa fa-minus-circle"></span>alert-danger </span>
</div>

And here is the javascript function to add to /static/js/:

function alertColor() {
  var result = "<span class='fa fa-info-circle'></span>&nbsp;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";
}

MathJax

To correctly display LaTeX formulas, we must follow Yihui Xie’s advice.
We will simply add the following code at the bottom of our /themes/hugo-tranquilpeak-theme/layouts/partials/script.html file:

<script src="//yihui.name/js/math-code.js"></script>
<script async
src="//cdn.bootcss.com/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML">
</script>

\[\lim_{x \to \infty} \exp(-x) = 0\]

Updating the local git repository

This can be done with simple git commands:

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