slides in htlm version

online link to these slides

link to the slides’ GitHub repository

link to the example GitHub repository

Definition of blog

A blog (shortening of weblog) is an online journal or informational website displaying information in the reverse chronological order, with latest posts appearing first.

It is a platform where a writer or even a group of writers share their views on an individual subject.

Famous blog platforms:

WordPress.org, Ghost, Drupal, Joomla, Wordpress.com, Medium, Squarespace, Weebly, Typepad, Blogger, Tumblr and Wix

_{source (2019)}

Out aim is to crate a simple blog by the following collection of tools:

• R + R Markdown

• RStudio + blogdown

• git + GitHub

• Jekyll + GitHub Pages

This will allow us to:

• do not need a personal web server

• easily include formulas and statistical plot
  in our blog posts.

R Markdown is a file format to make dynamic documents in R.

An R Markdown document is written in
markdown (an easy-to-write plain text format)
and contains chunks of embedded R code.

Example:

    # Plotting a simple Histogram 
    
    We generate a number `n=50` of 
    **Normal** disributed random variables 
    and plot them as an histogram
    
    ```{r}
     hist(rnorm(50))
    ```   

We generate a number n=50 of Normal disributed random variables and plot them as an histogram

blogdown is a package in R, developed by Yihui Xie (also author of knitr), that facilitates to build blogs with R Markdown in RStudio.

It is mainly tailored for the static generator Hugo, but following the author of the package, we tweak it to make it work with the static generator Jekyll.

Book published on 2017:

“blogdown: Creating Websites with R Markdown”
by Y. Xie, A. P. Hill, A. Thomas

it is also available on-line

• Create a repository, for example name it my_blog,
  and initialize it with a README.md

• Go to Settings -> GitHub Pages
  • set Source to master branch
  • select a Jekyll theme, for example to Minimal

• Edit your repository in the main page
  and set its website link

To manipulate locally repositories from your coputer, you need to download and istall git.

• Linux
  
• Mac
  
• Windows

• Then enable version control in RStudio by going to
  Tools -> Global Options... -> Git/SVN

• There write the location of the git executable

• Then Create RSA key... or select one if you already have them.

• Then open the Terminal by going to
  Tools -> Shell...

• and enter your details for your commits

  git config --global user.email "my.email@university.edu"
  git config --global user.name "my.username"

• File -> New Project... -> Version Control -> Git
• Type the url of your GitHub repository
• Select a name and a location for your RStudio project

Then

• assure to have the package blogdown installed

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

• Set the file content _config.yml as follows

  title: My first blog
  description: >- # this means to ignore newlines until "email:"
    "This blog has been creatged during the mini-course 
    'Blogging with R' by Bernardo D'Auria on Tue March 26th, 2019"
  email: my.email@university.edu
  
  # Build settings
  markdown: kramdown
  exclude: ['*.Rmd'] # this is important to use with RMarkdown
  theme: minima
  plugins:
    - jekyll-feed # to serve posts

• Create the folder _posts

• Create the file Gemfile

  source "https://rubygems.org"
  
  # To upgrade, run `bundle update github-pages`.
  gem "github-pages", group: :jekyll_plugins
  
  group :jekyll_plugins do
    gem "jekyll-feed"
  end

• Add to .gitignore

  _site/
  .sass-cache/
  .jekyll-cache/
  .jekyll-metadata

• Create the file index.Rmd

     ---
      layout: home
      title: "Welcome to my Blog"
     ---
  
      ```{r, echo=FALSE}
      library(ggplot2)
  
      ## Plot
      g <- ggplot(mpg, aes(cty))
      g + geom_density(aes(fill=factor(cyl)), alpha=0.8) + 
          labs(title="Density plot", caption="Source: mpg", 
               x="City Mileage", fill="# Cylinders")
      ```
  

• Run knitr::knit('index.Rmd')

• Create the file _posts/2019-03-01-HelloWorld.Rmd

      ---
      title: "Hello World!"
      author: "Bernardo D'Auria"
      date: "2019-03-01"
      ---
      Let us sum `1+1` by **R**.
  
      ```{r}
      1+1
      ```
  

• Run

    owd = setwd('_posts/'); 
    knitr::knit('2019-03-01-HelloWorld.Rmd'); setwd(owd);

• Commit and Push

Now going to the url of the GitHub Pages of our repository,

the blog WORKS!

To run it locally:

You need to have Jekyll installed

• run bundle install
  
• run bundle exec jekyll serve
• open in the browser the url http://127.0.0.1:4000/

Jekyll is a simple, blog-aware, static site generator perfect for personal, project, or organization sites.

Jekyll is the engine behind GitHub Pages, which you can use to host sites right from your GitHub repositories.

• find here the instructions to install for different platforms

• it may require to download and install a more recent version of Ruby language

• assure to have run the command

  bundle install

• Example in class:
  run jekyll new . --force in the project folder

• create the hidden file .Rprofile in the project directory

  options(
     blogdown.generator = 'jekyll', blogdown.method = 'custom',
     blogdown.subdir = '_posts', servr.daemon = TRUE,
     blogdown.base.dir = 'assets/figures/',
     blogdown.base.url = '{{ "assets/figures/" | absolute_url }}'
   )
   # IMPORTANT: please leave this comment line!

• create a new folder, name it R, containing two files:
  - build.R
  - build_one.R

  You can download them by clicking on them
  or you can look for them in the R directory in the brdauria/blogdown-jekyll repository

• make sw/hd link config.yaml to _config.yml

  ln -s _config.yml config.yaml # on MAC/Linux
  mklink config.yaml _config.yml # on Windows

• Select in the toolbar Addins -> New Post
  

• Type the following informations

  Title:    "Hello Jekyll!"
  Author:   "Bernardo D'Auria"
  Date:     2019-03-05
  Category: graphs
  Format:   R Markdown (.Rmd)

• Click on Done

A new file named 2019-03-05-hello-jekyll.Rmd
will be added in the _posts directory
and it will be opened for modifications.

• Modify the YAML header of the post as follows

  ---
  title: Hello Jekyll!
  author: "Bernardo D'Auria"
  date: '2019-03-05'
  slug: hello-jekyll
  categories:
    - graphs
  tags: []
  
  layout: post
  ---

• and the body as the following

  This is my first plot that cointains an R graph
  
  ```{r}
  library(ggplot2)
  ggplot(iris,aes(x=Sepal.Width,y=Sepal.Length)) + geom_point()
  ```
  
  and an external picture
  
  ![colored cats](https://raw.githubusercontent.com/brdauria/codingclubuc3m_talk/master/docs/images/cats.jpg)
  
  ```

you can download the file here 2019-03-05-hello-jekyll.Rmd

• build and serve your blog
  Addins -> Serve Site

  and in the Viewer Pane
  you should see your blog

  WORKING with PICTURES!

• commit and push

  and you should see your blog also in

  WORKING in INTERNET!

What we finally miss is to include in our posts some
nice formulas

• like this \(\sqrt{\frac{9}{4}} = \frac{3}{2}\)

• and this

  \[ \int_0^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2} \]

So let us prepare our blog and make our third post!

• run the command

  system2('bundle', 'show minima')

  to get the minima gem location.

• then

  list.files('/usr/local/lib/ruby/gems/2.5.0/gems/minima-2.5.0')

• in the folder _include create mathjax.html

  {% if layout.mathjax or page.mathjax %}
  <!-- https://docs.mathjax.org/en/
              latest/configuration.html#local-config-files -->
  <script type="text/javascript"
          src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/
               latest.js?config=TeX-AMS-MML_HTMLorMML,
               {{ 'assets/js/MathJaxLocal.js' | absolute_url }}">
  </script>
  {% endif %}

  It contains Liquid templating syntax! See here for more!

• in the folder assets/js create MathJaxLocal.js

  # TOO BIG to include here. Please click to download!

• in the folder _layout create mpost.html

  ---
  layout: post
  mathjax: true
  ---
  
  {% include mathjax.html %}
  
  {{ content }}

• Select in the toolbar Addins -> New Post
  

• Type the following informations

  Title:    "Hello Math!"
  Author:   "Bernardo D'Auria"
  Date:     2019-03-15
  Category: math
  Format:   R Markdown (.Rmd)

• Click on Done

A new file named 2019-03-15-hello-math.Rmd
will be added in the _posts directory
and it will be opened for modifications.

• Modify the YAML header of the post as follows

  ---
  title: Hello Math!
  author: "Bernardo D'Auria"
  date: '2019-03-15'
  slug: hello-math
  categories:
    - math
  tags: []
  
  layout: mpost
  ---

• and the body as the following

  This is my first plot that cointains  
  nice formulas
  
  - like this 
  \\( \sqrt{\frac{9}{4}} = \frac{3}{2} \\) 
  
  - and this
  
    $$ \int_0^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2} $$

you can download the file here 2019-03-15-hello-math.Rmd

• see immediatelt the preview in the Viewer Pane

• commit and push to check it in Internet

Jekyll is very powerful for

• its modularity

• its themes

However this has a cost:

• things may work slightly different from theme to theme

therefore there is some extra work to do!

We are going to work with: Minimal Mistakes theme

• remove index.md and write index.html as follows:

     ---
      layout: home
      author_profile: true
     ---

• add to Gemfile

     group :jekyll_plugins do
      ...
      gem "jekyll-include-cache"
    end

• add to _config.yml this

     github: [metadata] # important to use remote_theme
     minimal_mistakes_skin: dark
     remote_theme: "mmistakes/minimal-mistakes@4.15.2"
     paginate: 5
     plugins:
      ...
      - jekyll-include-cache
      - jekyll-paginate

• add to _config.yml and this

      # Front Matter Defaults:
      defaults:
        # _posts
        - scope:
            path: ""
            type: posts
          values:
            layout: single
            author_profile: true
            read_time: true
            comments: true
            share: true
            related: true

• then Commit and Push

Jekyll

• docs

• tutorials

• themes

online books

• R Mardown: The Definitive Guide

• blogdown: Creating Websites with R Markdown

Coding Club UC3M

tidyverse ecosystem

Slides created via R Mardown package and ioslides

Blog created with Jekyll

Hosted in GitHub

Using RStudio and blogdown package

plus some tweaks of the Yihui Xie`s blogdown-jekyll repository