Jekyll Website with Github, Github Pages and R Markdown

Details

• Why Jekyll not Wordpress?
  There are 3 main reasons why I chose Jekyll not Wordpress.
  
  Firstly, Wordpress does not work well with R Markdown.
  I am a big fan to R and I write every analysis report (ex: my master thesis - PDF, R Sweave code) and slides (ex: my master thesis - ioslides, R Markdown code) using RStudio products. So, I wish that all my web posts and pages can be generated from R Markdwon which is crucial to me. Although I found that I can use the package RWordPress to generate posts on Wordpress, it just did not work really well on transforming formats and syntax. The posts on Wordpress can be really different from the HTML files you compile in R Markdown. On the contrary, by using knitr-jekyll in my Jekyll website, the formats and contents of posts are almost exactly the same as what I compile in R Markdown and it always work smoothly when transforming files. So, writing posts in Jekyll is definitely more fun than in Wordpress.
  Secondly, the website structure behind Wordpress is far more complicated than Jekyll.
  The website structure behind Wordpress includes MySQL, PHP and Apache which are gigantic and may be too technical for me for now. And, because of its complicated structure, whenever errors happen, all I get is just a white page without any error codes on the user screen. It is just so hard for me to debug. On the other hand, a Jekyll website is a directory folder consists of many .html, .scss, .json, .xml files which I can easily open the files, inspect each code line and modify them if you want. And, every error will be shown in the terminal window in details, so I can just Google for solutions. Hence, from my expereince, Jekyll is much more controllable than Wordpress for its simplicity.
  Finally, many prominent data scientist also choose Jekyll for their personal website or for project website.
  For example, Yihui Xie (the author of knitr-jekyll), Brenda Rocks, Simply Statistics, The caret Package, R for Data Science…etc.

• Part I : Get started! Combine Jekyll, Github and Github Pages
  

  • Basic ideas
    Before setting up a Jekyll website and hosting it on Github with Github Pages, I think I should have a rough idea about what they are and what they can do. So, the following is the resources that I have browsed.

    • Resources for starting
      1. Github Guides
      2. Github Pages
      3. Jekyll

  • Steps for connecting all of them
    Then, it’s time for us to make those three work together on my own computers. The following are the steps to do it with some helpful resources.

    1. Install Jekyll on my computer.
       Jekyll Tips - Install Jekyll on Mac OS X

    2. Find a desired Jekyll template.
       Jekyll Theme and Start Bootstrap Templates

    3. Deploy the theme website on Github and Github Desktop.
       How to Deploy a Website Using GitHub Desktop by Deep Datta and Github Pages and Jekyll Tutorial by WebJeda

    4. Run Jekyll locally.
       Building a static website with Jekyll and GitHub Pages

       1. Change your directory to the website directory. $ cd /path/for/website/dir

       2. Install Jekyll bundler using gem. $ gem install jekyll bundler Install the contents in bundler. $ bundle install Update the bundler.

          $ bundle update

       3. Run the website locally.

          $ bundle exec jekyll serve

• Part II: Change appearances, Add features and R Markdown
  Afer finishing all the deployment, I started to cutomize my website by modifying some .html and .scss files in the template. The text editor I used for all the modifications is Atom. The following are the features I added in my website and some relevant resources.

  • Appearance:
    1. Make my own logo and replace the logo form template. logomakr
       
    2. Change the color of font, background and hover. W3School
       Modify codes in _variables.scss and _typography.
  • Features:

    1. Use R Makdown to publish posts: knitr-jekyll.
       Download all the related files from the Github repo and put them in the website directory folder.

    2. Add math syntax by using LaTeX notations in R Markdown: Mathjax.
       Mathjax is a javascript library, you can import it from online source or from the local directory after downloading it to the website directory folder. What I did here is import it from online source, which means that the features will not be able to show up when internet is not connected.
       Copy the following codes in header.html file.
       

        <!-- MathJax -->
        <script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
        <script type="text/x-mathjax-config">
           MathJax.Hub.Config({
           tex2jax: {inlineMath: [['$','$'], ['\[','\]']]}
           });</script>

       
       

    3. Add a page with search bar.
       How to Make lunr.js and Jekyll Work Together (with Gotchas)

    4. Add comment feature by using Disqus.
       How to add Disqus comments to Jekyll Blog - Tutorial 9

    5. Highlight syntax and codes: Highlight.js
       Luckily I have this feature in my template, so I do not need to add this again. But if your website template do not have this feature and you want to add it, here is how you may want to do. Copy the following codes into your header.html and change the default.min.css to the style name you want. Here are all the styles. Or, you can download all the Highlight.js library to your website directory folder and import the library by following How to use highlight.js.

       <link rel="stylesheet"  href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.9.0/styles/default.min.css">
       <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.9.0/highlight.min.js"></script>

• Part III : Connect the Jekyll Github website to your Personal Domain
  My domain name, www.yintingchou.com, is registered on Google Domain which costs me $12 only a year. Here is the tutorial post teaching you how to point a domain on Google Domains to GitHub pages. I followed this post and everything just works perfectly to me. If your domain provider is Bluehost rather than Google Domain, check out this post, Setting up Bluehost DNS for a GitHub Jekyll blog.