Developing this Blog = #openscience?

Here’s a wrench in the works - let’s talk about web development and how I made (hacked) this blog :)

For the more chemistry-inclined readers who might not have coding experience, this might seem too “out there”.

This is not my domain - I’m a chemist, not a web developer!

If you’re one of these folks, perhaps web development seems intimidating, or is simply irrelevant to your daily work and unnecessary to learn. (I certainly thought these things.) But if you’ll bear with, I’ll try to show how my experience making this blog changed my own mind.

For starters, let me say I don’t claim to be a web developer by any means. I studied Chemistry and Environmental Science at university, and never took any courses - online nor at university - in web development. In fact, one of my biggest regrets is not taking any Computer Science courses during my studies. All I have learned has been through trawling through resources from the open source community, tips from colleagues, and simply hours of hacking.

All this to say: I am not an expert, and you don’t have to be either, but everyone has to start somewhere.

_{(It just so happens that I started about 24 hours ago >.<)}

So why now?

Quite simply, I wanted to start a blog to share some thoughts and hacks. I’ve relied so heavily on the blogs of others for tips and tricks for my research, and figured it would be nice to share whatever I figure out too.

Previous reincarnations of blogs using Blogger and Wordpress were somehow never sustainable for me - I didn’t like having to manage yet another user account on top of all the others I already have, plus I was looking for something with intuitive version control.

Enter static blogging using Jekyll/GitHub pages. After setting up my own GitHub.io page (excellent step-by-step documentation by GitHub), I bought and configured my custom domain, but the real zinger came when I wanted to include a Comments section at the end of every post.

Most people with Github pages seemed to recommend utterances, but the need for commenters to have a GitHub account seemed to me a potential deterrent for some prospective commenters. Another popular tool, Disqus, apparently has several drawbacks and many bloggers seemed to be shifting away from it, so after more digging, I eventually stumbled upon Michael Rose’s Minimal Mistakes theme.

What I liked was that Minimal Mistakes seemed to have many options built-in for Comments, including what looked the most promising - Staticman by Eduardo Bouças - not to mention excellent documentation which was parseable even by n00bs like me…so…ONWARD!

At first, I tried following the Quick-Start Guide and got my hands dirty using Ruby Gems (no clue what they were before). Installed Bundler and ran bundle, added stuff to my Gemfile etc..

However, after a while, it felt like I was going round in circles as I didn’t really know what I was doing beyond just following a recipe. (Perhaps one thing which could be improved in the docs would be to incorporate some operators like AND and OR between each set of instructions - even though they are split into sections, it was not clear to total beginners like me what needed to be done and what didn’t.)

Eventually, I tried what seemed like the path of least activation energy that didn’t require in-depth knowledge of Gems and Ruby: simply forking the theme on GitHub (this instruction is not an explicit section, but is in-line somewhere on that Quick-Start page). To customise it for this blog, I simply added the relevant details to the _config.yml as instructed, taking care to make sure I didn’t fudge too much with the JSON formatting using this tool thanks to illepic (who knew you couldn’t trust the reported line numbers in the error messages?)

Several bundle exec jekyll serve iterations later (run this in the command line from your blog’s local directory to prototype it - copy and paste the server address into a browser to see), my blog was up and running. I just needed to include a Comments section.

Staticman seemed to be the best option as comments would be handled as Pull Requests within GitHub, and one can use reCAPTCHA to guard against spam. Travis Downs’s tutorial was indispensable and easy to follow.

Still, it was quite a long process, involving setting up a Bot account on GitHub, deploying an app on Heroku (for the ‘bridge’), configuring reCAPTCHA and adding the necessary changes to our favourite _config.yml as well as staticman.yml.

By this point, I had been hacking at this for about 9 hours and started to get so tired that I’d forgotten some obvious steps (not written in Travis’s tutorial, assumed as ‘common knowledge’):

1. Make sure to add the public key generated as part of the RSA keypair to your Bot’s Github account. _{(cue Homer Simpson)}
2. Add the entire RSA private key to the Heroku app config, including the -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- parts.

I also ran into some POST problems (see here for debugging) while configuring the staticman url in the _config.yml (in Travis’s tutorial it is called staticman_url, but in the theme’s _config.yml it is called endpoint), solved by this workaround. Open Source community rocks!

When I finally got Staticman to work, I was able to submit a comment and approve it by accepting the relevant Pull Request on my Bot Github account BUT it was not appearing as a comment on my post.

Googled “Staticman comments don’t appear” many, many times. (Did I mention many?)

I ended up trying a bunch of things, including going through the _includes dir contents as instructed. Ultimately, I did not use any of these steps, and what I think made it work in the end was changing the path in the staticman.yml from "docs/_data/comments/{options.slug}" to "_data/comments/{options.slug}".

After this, the accepted PRs started showing up in the _data dir and the comments started appearing on the webpage correctly :)

One last tip: if you are going through this process using Minimal Mistakes & Staticman but are having problems, it could help to compare your _config.yml and staticman.yml with versions of others whose blogs have the properly functioning features you are trying to debug, mine for example.

If you’re still with me, dear reader,

thanks for hanging in there. But at this point, you might be wondering - why all the fuss? Why didn’t you just set up a Blogger or Wordpress and avoid all these extra steps?

Honestly, I started asking myself this question several times (especially the later it got and the longer I hacked into the night).

The answer, besides what I already mentioned about sustainability and version control, is that I wanted to try to build something from the ground up myself using as much open software as possible. (Also, like with most projects, there came a point where I just wanted to see it through.)

Overall, it was quite a fulfilling experience - I learned a lot. I also see why web development can be quite fun - the development-prototype cycle can be quite fast and you see results immediately (just bundle exec jekyll serve, or if you want to see the web version, push changes to GitHub and refresh your page).

But what does this have to do with #openscience?

Everything and Nothing at the same time:

Everything because I now have a properly functioning Open blog project where I can write my posts :D

Nothing because I could have just used Blogger or Wordpress D:

What I hope you take away from this post is that:

1. Everyone has to start somewhere. I did, and you are seeing the result right now. (Also, the best way to learn is by doing. Try skipping those MOOCs for a change and just hack away!)
2. You don’t have to be a web developer to achieve what a n00b like me did setting up this blog. As I said, I have zero formal training in web development. Just takes some patience, hacking, lots of Googling, and lots of coffee :)
3. I’ll say it again - the Open Source community rocks! Big thanks especially to M. Rose, E. Bouças, and T. Downs for their hard work.

And of course, feel free to leave a comment!