Ryan Aghdam

A Rookie Mistake: ryanaghdam.com Re-written

Frustrated with building my website with Jekyll and Liquid Templates, I decided that I could write myself something to take its place. I ignored the many available solutions and started thinking of waht I wanted in a blogging platform.

  1. I wanted to store posts as plain markdown files. A web interface was not only unnecessary but unwanted.

  2. Since I was writing it myself, I wanted to use node.js and try out some modules: Ramda, proxyquire, and tape.

  3. I wanted the content to be completely separate from the presentation layer and easily portable, for when I inevitably want to spent a weekend re-writing code rather than content.

  4. I wanted to continue to use the Lightbox plugin. I was unhappy that I was using a Liquid template include to insert images. I wanted to be able to just include an image using the traditional Markdown syntax.

  5. I also wanted to run the site with very minimal cost.

Half a Saturday and most of a Sunday later, let’s see what I have.

Content Package

A package, ryanaghdam-content, provides an API to read all posts, read one post (matching by slug), or all posts from a given category.

A script runs during install time to resize the source images using ImageMagick.

The images are surfaced on the presentation layer, using Express’s static file middleware.

Most functions are memoized so that filesystem access is cached. For the most part, this package adheres to basic functional programming practices; most functions are pure.

The Presentation layer

The front end is a simple Express application, ryanaghdam-homepage.

Controllers access the API exposed by the ryanaghdam-content package and render Jade templates.

A content service is used to slightly transform data before it’s sent off to Jade. This could have – and possibly should have – been done in the content package. I chose to do the transformation here, because I want to use it as an example for how something at work can be done.

Unlike ryanaghdam-content, the Express application is not covered by tests. I plan on using Nightwatch or Nemo.

The Aftermath

I mentioned a few goals that I wanted to accomplish.

  1. Store content in plain markdown files – success. All content is plain markdown with YAML front matter. It’s easily portable for when I next change my mind.

  2. Use Ramda, proxyquire, and tape – success.

  3. Separate the content from the presentation layer – success. The content is a separate, published npm package. A completely different presentation layer can use the same content. There is, however, a problem with this approach. To make a content change, I must: update and publish the content package, update ryanaghdam-homepage to use the latest version of the content package, and then deploy to Heroku. Previously, with my Jekyll-based setup, I just had to push my content to GitHub. Travis-CI would automatically run to build and deploy (to GitHub Pages).

  4. Use Lightbox with plain Markdown – success. I am using markdown-it to render Markdown. It features a plugin interface, which enabled me to write a custom plugin that changed the way images are rendered. It’s pretty poorly written.

  5. Minimal runnings costs – TBD. I am currently using a free-tier Heroku instance. Time will tell if that’s a viable solution.

Not too bad when looking at just the goals. But is it any better? I have a more complex deployment process, a more complex hosting environment, and a website that, to the user, hasn’t changed a bit.

I got to spend some time working on a project that uses some modules and architecture that I wanted to try. Is the product – my website – noticeably improved, or even different?

I think this is a common rookie-mistake – rewriting something just to use new technology and certainly something I should have been more cognizant of. If it were a professional project, rather than a rainy weekend project, it would have been an tremendous waste of time and effort.

It’s a good thing that I enjoy writing things that nobody reads – these blog posts and software – otherwise this weekend would have been a waste.