How I created this site?

My requirements for the site and the tools I used to create it.

By Vamshi Jandhyala in website

June 29, 2021

High level requirements

  1. A fast static site without much Javascript.
  2. Good selection of themes which are easy to configure to enable fast experimentation. The themes should also be flexible and extensible.
  3. Everything should be open source, free and well maintained/supported.
  4. The site generation should be very fast.
  5. All the content should be stored in text files for maximum portability and experimentation.
  6. The markup language should be as lightweight as possible but should also be able to accommodate Mathematics heavy posts and code highlighting.
  7. The blogging process should be as frictionless as possible.
  8. It should be straightforward to create documents in multiple formats using the same marked up content.
  9. Last but not the least, hosting the site should be simple.

Setups that I tried previously and abandoned

Before settling down on the current setup, I tried a few other approaches which didn’t really work well for me.

Jekyll + Docker + VSCode + Github pages

Though I knew Jekyll was not as fast as Hugo, the fact that it was supported by Github and that it had tons of extensions made me give it go. I found some very good free thems for Jekyll and it was fairly straightforward to configure them. Jekyll is not natively supported on Windows so instead of spending lots of time trying to install it on Windows, I used it through Docker. Using it through Docker was fairly straightforward but it was too slow for my needs so I abandonded this approach.

Jekyll + WSL2 + VSCode + Github pages

I really liked the simplicity of Jekyll and wanted to make it work. I am also a big fan of the Linux and its command line utilities but could not give up on all the benefits offered by Windows. I even briefly had a dual boot setup but it was too painful switching between Windows and Linux. I heard good things about WSL and decided to give it a go. With WSL I had the best of Windows and Linux at my fingertips. I could use the Linux command line as well as the GUI based software from Windows. All my hardware peripherals are connected to Windows where drivers are readily available. I used VSCode consistently for both programming/data science as well as creating content from my blog. All the windows folders are already mounted in WSL so transferring content across linux and windows was a breeze. The only thing which bothered me with the setup was that I couldn’t find a Jekyll theme which had all the features I wanted.

Hugo + Emacs + Github pages

I used the lightning fast static generator Hugo and the venerable Org mode to write posts for my blog as well as capture ideas that might turn into blog posts in the future. I used the CDLatex minor mode to help with latex markup for some of the math heavy posts. I used the awesome ox-hugo package with one-post-per-subtree flow with two .org files, one for all the maths related posts and the other one for programming posts. Though Hugo is extremely fast when it comes to generating the site, I was not comfortable with Emacs and I was also spending most of my time in VSCode, so I gave up on this setup.

R + Hugo + Github + Netlify

After numerous attempts, I arrived at the current setup which is working quite well for me.

Authoring content in Markdown using VSCode

RMarkdown is a very flexible Markdown variant that can be used to generate documents in multiple output formats e.g. html, epub, pdf etc with the same input using a literate programming approach. With the help of R packages like distill, blogdown and bookdown the same input markdown can be used to generate articles, websites or books. This flexibility is what got me interested in the R/RStudio ecosystem.

VSCode with its numerous Markdown extensions is great for authoring Markdown and I use that to create most of the Markdown input files. In some cases, where I need more flexibility in terms of the output formats, I edit RMarkdown in RStudio.

Site generation using Hugo via blogdown

Hugo is a very fast static generator for which hundreds of themes are available and it can be conveniently used through the blogdown package. The update and preview cycle in Hugo is very fast that makes the process of creating sites and experimenting with themes pretty enjoyable.

Hugo Apero theme

I stumbled on the fantastic site of Alison Hill which is based on the wonderful Hugo Apero theme. The theme provides a lot of flexibility when it comes to creating and organizing content. Infact, Apero also supports the creation of collections - a set of posts related to a common theme/topic which not many themes provide and this is what sealed the deal for me.

Version control using Github and hosting in Netlify

The seamless integration of Netlify with Github makes deploying any changes to the website a breeze.