Inauguration

Published on

As fireworks have just begun exploding outside my window, I’ve finally reached a point where I’m able to write my inaugural post. For quite a while I’ve wanted to put a website together for myself to publish my ideas, projects, techniques, and things I’ve learned. I will share how my site came to be, how it’s built, as well as what can be expected to come out of it.

I’ve always found that building my own site is a difficult thing for me. While I can have such a clear and focused view when I’m working on another project for a client, everything gets fuzzy when it comes to my own personal projects. I suspect this is due to me pushing personal projects to the side and letting other things take precedence. I’ll start working on an idea and then, the next thing I know, it’s been a week since the last time I worked on it and I no longer know where I left off, nor do I have the motivation to figure it out. I’m through with the unfinished personal projects, and this is Exhibit A.

I’ve spent the last week or so researching blogging and CMS platforms trying to decide which would be right for me. I have lots of experience with Wordpress, but my issue with Wordpress is that it’s always been way too much for my needs as a small website. I wanted something that was simple, easy to use, and efficient. After weighing the options, I settled on a static site generator called Jekyll.

Jekyll

In case you’re not familiar, a static site generator is basically a content processor, rather than a CMS, that uses the filesystem to store content, instead of a database. Usually, they are “blog-aware” and allow you to write your posts/pages in HTML, Markdown, Textile, or any other number of formats. In order to update your website, there is a build process where all of the files are processed and output as static HTML files — hence the name static site generator, or SSG.

Jekyll is surprisingly easy to set up and use. It’s lightweight, efficient, and allows you to use variables and basic templating throughout your site with Liquid. I was able to build most of this site in a couple of days, plus about four or five more while I was tinkering with the details. Syntax highlighting, and the ability to choose which Markdown parser to use, both stood out to me, as well. I’m currently using Kramdown, which is way better than regular Markdown in my opinion.

One of the other cool things about Jekyll is that, if you choose, your site can be hosted for free on GitHub Pages. GitHub Pages is set up to automatically build your site from your gh-pages repo with Jekyll. Personally, I’m hosting this site on a VPS with DigitalOcean and using git to build and deploy, similar to GitHub Pages. Below is my git post-receive hook for building my site.

#!/bin/bash

unset GIT_DIR

REPO_ROOT=/path/to/repo.git
REPO_BRANCH=master
WWW_ROOT=/path/to/public/web/directory
GIT_TMP=/path/to/temporary/git/directory
TIMESTAMP=$(date +"%Y%m%d%H%M%S");
JEKYLL=/path/to/jekyll/gem

# clone and build
mkdir -p $GIT_TMP
cd $GIT_TMP
git clone -v $REPO_ROOT ./
git checkout master

$JEKYLL build

#deploy
mkdir -p $WWW_ROOT/releases/$TIMESTAMP
cp -ar $GIT_TMP/* $WWW_ROOT/releases/$TIMESTAMP
ln -f -s $WWW_ROOT/releases/$TIMESTAMP/_site $WWW_ROOT

echo "Cleaning house..."
rm -rf $GIT_TMP
cd $WWW_ROOT/releases
rm -rf `ls -t | tail -n +6`

echo "Done."

exit 0

Here is what’s happening:

  1. Create a temporary directory to clone the repo into and checkout the master branch (which is the branch that I want to build).
  2. Build the site inside the temporary directory with Jekyll.
  3. Create a new timestamped release directory inside the releases subdirectory of my root www folder.
  4. Copy all files from the temporary directory to the new release directory and create a symlink to the new release directory from my root www folder, which my web server points to.
  5. Remove the temporary git directory, and all but the 5 most recent release directories.

Downsides to Jekyll

I did enjoy building this site with Jekyll, but there were a few things that didn’t really sit right with me.

  • The Jekyll directory structure doesn’t separate source files from build files very well.
  • I feel that Liquid is only just adequate for templating. It has no support for template inheritance, and I found myself having to use multiple filters sometimes when I was trying to output something very simple. I would have preferred to have had a more powerful templating engine, such as Twig.
  • I’m using Rouge as my syntax highlighter. The reason for this is that Pygments, the default syntax highlighter, requires Python. This feels kind of hacky, and Rouge is pure ruby, so I went with it, instead.
  • For some reason, Jekyll currently requires either therubyracer gem (which didn’t work for me), or Node.js installed. I didn’t really want to install Node.js, but that’s the only way I was able to get it to work. There is currently an open issue about this on GitHub.

After hunkering down and working with Jekyll for a week straight, I’ve slightly convinced myself that I can put together an SSG of my own in PHP that’s a little more robust. I know there are other SSGs out there that are built in PHP (Sculpin, for one), so I’ll have to take a look at those, first. It may turn out to be my next project, at least for the fun of it.

The Future

Well, what’s in store for my little corner of the internet? Nothing spectacular, I assure you, but I will be writing articles about web design, web development, programming, and possibly electronics. They’re all some of my biggest interests, and I look forward to sharing about them as I continue to learn and grow.


Verify the signed markdown version of this article:

curl https://keybase.io/sethlopez/key.asc | gpg --import && \
curl https://sethlopez.me/article/inauguration/ | gpg