HPSTR: An Octopress Theme

June 04, 2014

In case you didn’t notice, we’re rocking a new theme: HPSTR for Octopress! Ported from the theme of the same name for Jekyll, this theme has a bunch of cool new features that make the theme easier to use and more customizable.

Before I begin, I have to give a huge shout out to mmistakes for crafting such an impeccable set of stylesheets and Jekyll templates. I could talk this theme up all day, but I think that the results speak for themselves. Even more praiseworthy is that the entire source code is licensed under the GPL, enabling anyone to take the source and build upon it. And on that note, I’d like to unveil what I’ve built.

Ported to Octopress

The theme was originally implemented for a vanilla Jekyll blog. Personally, I find the automation tools provided by Octopress to be incredibly helpful, and I didn’t want to give these up to be able to deploy this theme. As a result, I had to tweak a few things in order to get it to work with a standard Octopress installation.

Less to Sass

The HPSTR theme was originally built using Less to compile its stylesheets. Octopress uses Sass under Compass instead–a decision which I love: the rich library of plugins that Compass provides is ridiculous. Thus, this was the first step of the port.

After a quick Google search I stumbled upon this question on Stack Overflow, which surprisingly took care of the vast majority of the conversion, leveraging mere text replacement. From there, it was mostly a matter of slugging through the Less docs to find out what a particular function did, jumping over to the Compass/Sass docs to find a corresponding mixin, and repeating.

Sass to Compass

I didn’t stop after I had the vanilla Sass working. One of Compass’s coolest features is that you don’t have to repeat yourself: there are mixins for seemingly everything, and when there aren’t, there are 3rd party plugins. Thus, the next phase of the port was to see how much of the code I could reduce to compass mixins.

For the most part, this stage affected CSS3 properties which need vendor prefixes, to include keyframe animations. The keyframe animations are particularly worthy of a mention because I found a handy plugin called compass-animation to take care of them. It works as easily as any other Compass mixin, from installation to use.

Octopress Mannerisms

There are a few things that Octopress users can expect to be reasonably similar from one deployment to the next, and I wanted to ensure that as many of the features dually implemented by mmistakes and Octopress used the syntax or conformed to the style set forth by Octopress. A small example of this: the page.link and page.external_url properties. Defined by the old and new themes respectively, both accomplish a similar purpose. Each specifies that the main purpose of the post is to link to a different page. Not wanting to break the service for current Octopress users, I tried to convert as many of these subtleties.

On top of this, I restructured a lot of the original code so that someone used to customizing an Octopress theme would feel more at home when checking out the source for this theme, even if some of the particulars were different. This applied mostly to the Sass directory structure, but also to the templates.

More Powerful Customization

One of the many ways Octopress adds value on top of Jekyll is the ease with which you can get a Jekyll blog up and running, and subsequently customize and tweak that theme. This was one area where I felt that the original Jekyll theme fell short. The original stylesheets had a somewhat decent set of variables (in less/variables.less) that would allow you to customize the colors and font faces, but the method for customizing the size of the font was wonky (larger values produced smaller fonts), and the various mixins employed to handle setting the sizes were confusing.

To solve this, I added loads of new variables handling the font sizes and line heights on a per-component basis, while also providing a master switch to easily resize everything. My theme also differs here from the original in that it’s default font size is slightly larger for normal paragraph text (the whole reason why I cared about customizing the font size in the first place!).

Like what you see?

This theme is in no way perfect, from the styles to the compatibility with the vast array of Octopress options. If my support for your favorite feature is lacking or absent altogether, patch it up and submit a pull request on GitHub!

I’d also love to hear about your installation process. If something didn’t quite work out right when installing the theme from GitHub or everything went super smoothly, tell me on GitHub in an issue, on Twitter, in the comments below, or in an email. Seriously!


Jake on the Web

If you cared enough to read that far, you should consider following me on GitHub or paying a visit to my homepage. If this post was about one of my open source projects, make sure to star it on GitHub! I love hearing what people think, so feel free to open an issue or send me an email.

Haskell Development with Neovim

After a year and a half of using Haskell on and off, I’ve finally settled on a set of high-quality development and editor tools, using Stack and Neovim. Continue reading

Reach for Markdown, not LaTeX

Published on February 26, 2017

Troubleshooting Haskell Stack Setup on OS X

Published on August 03, 2016