It took a few weeks, but the RICELab site has been redone, this time with Jekyll. After a few “hacks” on the shared server (via either PmWiki or WordPress holes – I’m often too lazy to update the installations), I finally bit the bullet and began to look into a static site generator. Given that this site is still hosted off a shared server, I’m still obviously vulnerable to others getting hacked, but at least now it won’t be my fault. ;-) A quick run down of what I’m excited about with the Jekyll installation, and what I had difficulty with.
My Needs
As an academic, I don’t have particularly unique needs, but I generally don’t want to fight against the tool too much. The site should serve two purposes: (1) it is my (lab’s) identity; (2) it is used to disseminate academic papers; (3) it is a repository for teaching material. For the most part then, the site itself is fairly static – things don’t change much. Adding content for (2) and (3) happens, but infrequently, and the volume of content being added is minimal.
- Easy to add content. There are three things that I update/add: (a) publications list; (b) student listing; (c) random blog posts. The pub list is added to maybe about once every four to eight months, student listing – about once a year, and random blog posts are infrequent.
- Easy to modify content. One thing is that when I add stuff, I often make mistakes (e.g. for this blog post, there will be typos, etc.). I want an easy way to modify the site to repair content if necessary.
- Reuse of stuff where possible. Ideally, update in one place, and everything propogates. For me, I’ve settled on the use of a large BibTeX file to retain a record of all my publications. While this is kind of old-school, there is usually a (set of) tool(s) that can be used to snarf this out for various purposes (e.g. website, CV, etc.).
Previous Solution
I’d been using PmWiki for around 10 years (since my PhD days). Things that I really liked: (1) easy markup wiki markup language; (2) nice integration with BibTeX (took a while for me to tweak it to my liking, but I only update the BibTeX file, and pmwiki does the rest); (3) can update things easily because you can edit via a web browser.
But the thing is that the tool is a bit unweildy for sites that are bigger than a few dozen pages. Moving content was difficult, and I found myself wishing for something that was easier to manage with more powerful tools than HTML forms. The markup language (wiki) was not being used as much any more. Upgrading the site was also tricky, as I was never sure if the upgrade would break things. Oh, and a random upgrade of PHP broke my whole pmwiki installation as it was using a theme that hadn’t been updated since early 2010. Yowza.
Current Solution
I’m using Jekyll as a static site generator for the RICELab website. I modified a theme I pulled down from http://jekyllthemes.org/, and added the jekyll-scholar plugin for BibTeX and citation fun.
The blog is handled through Jekyll via a bunch of Markdown files that have a few lines of YAML metadata at the top of each (these lines of code specify which template to render the page with). I think this is absolutely brilliant, and I’m super happy about the use of Markdown.
Things I’m pumped about
- Static generation. I like the idea of a static set of webpages for my academic website. This is not a situation where I have a backend database full of thousands of products that I’m selling. If I’m prolific in my career, there might be 500 things that I’ve written, and if I’m lucky, about 10 things that people will actually want to read. ;-) The larger blogging and CMS tools like Drupal and WordPress were frankly overkill for what I was looking for.
- Templates. Holy crap. “Separation of content and presentation,” has been a mantra for so long on the web, but it is only now that I see how brilliant the execution can be. After mucking around with the template for a while, I was able to figure out how to use Jekyll’s “includes” and “page layout” stuff and boom!, hopefully I never have to worry about that stuff ever again (well, until I change the site design template altogether).
- Markdown for awesomeness. Although I really enjoy writing academic papers right in the template (WYSIWYG-style), I’ve become accustomed to writing many passages and stretches of text using a straight up text editor. It could be my LaTeX years calling out to me, but I hated debugging LaTeX code when I used to write it. Markdown solves a lot of my problems, though: I get the benefit of writing in text editors, and it is actually readable and easy to edit the bugs out of. ;-)
- Simple content structure. The site structure is very straightforward, and reflected in the directory structure that the “website source” is in (that Jekyll uses to generate the real site). There’s a nice little override feature (“permalink”) that can be used in a straightforward way. So, it is easy to understand what’s going on.
Things that I’m not so pumped about
- Static generation. One thing that I don’t like is that I need to actually press the “publish” button to actually refresh/update the website (and this can take a minute long to do). Although in principle jekyll can do this in place, right now, my webserver cannot run a new enough version of ruby to execute jekyll. This means that I need to generate the site from my laptop, and then push the content up to the server. Highly lame. With the wiki, publishing was a page at a time, and very much edit-on-the-fly. Another nice approach was embodied by http://www.mdwiki.info/, where you could just put markdown files in the directory, and things would be published automagically. The problem with this was that the site it generates isn’t indexed properly by search engines, and there wasn’t an obvious BibTeX integration story.
- Figuring out all this shizz from scratch. After throwing up my hands a few years ago, I really hadn’t followed the HTML/CSS/Javascript stuff for a while. To be frank, I still haven’t – in part because the number of tools and things that “make everything easier” has exploded. Liquid, SASS, Responsive Design/CSS/media selectors, blah blah blah. The vocabulary that is required to put things together (and understand how it is working) has exploded. This was a huge pain in the neck. I wasn’t very excited about having to figure this out (well, I was happy to figure it out, but not happy about having to struggle with it).
- Can’t edit on the fly. I think this is my main gripe at this point. Wikis allowed editing in place, which I really liked. With this, I get to edit markdown files, but unfortunately, I don’t get to edit them in place if I see a mistake (which I usually only catch after publishing).
tl;dr
I’m using Jekyll now. I think I’m in love, but we’ll see.