Jekyll website with Hugo blog with blogdown

What I like about having a Jekyll based site

Jekyll has been around for a long time now and thus has extensive documentation and support online. I also like the Jekyll-based al-folio theme because:

1. It automatically generates publications from a BibTeX file using jekyll-scholar.
   
2. Information can be spread across multiple pages (e.g. papers, software, talks), which makes for a short landing page.
3. Support for news announcements.

The problem

My main issue with the Jekyll based site, is that there isn’t an efficient way of writing blog posts using R Markdown. I want this functionality so that I can:

1. Blog about my experiences with certain R packages.
   
2. Remind myself of certain tips and tricks, i.e., a help page for my future self.

blogdown is a popular R package that makes it easy to integrate R Markdown posts in Hugo based websites. This framework came out after I had already spent lots of time on my Jekyll based website. There also wasn’t a Hugo theme I liked enough to make the switch.

The Solution

I decided to do a hybrid Jekyll-based website with a Hugo-based blog. My main academic site at sahirbhatnagar.com remains within the Jekyll framework and hosted on GitHub with GitHub User Pages, and my blogdown blog is also hosted on GitHub on the gh-pages branch with GitHub Project Pages at sahirbhatnagar.com/blog.

In this post I try to outline the steps I took to achieve this. This post assumes some familiarity with the git command line and that you already have a User Pages site on Github at http(s)://<username>.github.io.

It goes something like this:

1. Go to your online Github account and create a new repository called blog. Do not initiate with a README.md. Do not initiate with a license.
   
2. On your local machine, install the blogdown R package.
   
3. On your local machine, create a new folder called blog. This will contain the source files of your blog. Make sure its empty (if its not empty, the command in Step 4 will return an error).
   
4. In R enter the following command to create a skeleton of the blogdown site

blogdown::new_site(dir = "blog/")

5. If all worked well, you should see a preview of the hugo lithium theme (modified by Yihui Xie) in the RStudio viewer pane.
   
6. The static files for the website are in the public folder, while the source files are in the top level directory (in this case, the blog folder). Initialize a git repository from the root of your blog folder and create a link with the remote repo created in Step 1 using:

   git init
   git remote add origin https://github.com/username/blog.git
   

7. To create a new blog post run this command from the root of the blog directory (and on the master branch):

blogdown::new_post(title = "Name of new post", ext = ".Rmd")

8. Create a deploy.sh script in the root of your blog folder so that you can automate the publication process everytime you add to your blog. The script I use will automatically build the blogdown blog and push to the gh-pages branch. Note that you first need to push the source code to the master branch (the script first checks for any uncommitted changes). This script assumes that blogdown::build_site() will create the static files in a folder called public. This is what my deploy.sh script looks like (it makes use of git worktrees):

#!/bin/sh

# Check if there are any uncommitted changes
if ! git diff-index --quiet HEAD --; then
    echo "Changes to the following files are uncommitted:"
    git diff-index --name-only HEAD --
    echo "Please commit the changes to master branch (which contains the source files of this blog) before proceeding."
    echo "Aborting."
    [[ "$0" = "$BASH_SOURCE" ]] && exit 1 || return 1
fi

echo "Deleting old publication"
rm -rf .git/worktrees/public/

echo "Make worktree"
git worktree add public gh-pages

echo "Generating site"
Rscript -e "blogdown::build_site()"

echo "Adding and committing to gh-pages branch"
cd public && git add --all && git commit -m "$1"

echo "Pushing to gh-pages branch"
git push origin gh-pages

echo "Cleaning up files"
cd ..
git worktree prune

rm -rf public

9. After running chmod +x deploy.sh, you can then call the script using

./deploy.sh "commit message of your choice"

Discussion

That’s all I have for now. I hope this framework will work for me and meet my needs to maintain my academic website, as well as a blogdown blog.