Site Redesign Using Middleman

date2013-11-10
tags

I finally redesigned my site and moved it over to a static site generated using Middleman and hosted using Github pages. I thought I would share a little bit about my process in case it helps anyone else going through the same thing.

You can find the repository for my project on Github. Feel free to use it as a detailed reference for what I did, but don't judge too harshly for the code quality. This was something I slapped together during some spare time, and it is not a good example of best practices.

Background

Previously, my site lived on a locally hosted server with WordPress and a poorly hacked up custom theme. This was annoying to maintain, so I rarely made changes to the design or page layouts. My server got very sad (my ultra-technical way of saying it couldn't handle the load) any time I wrote a remotely interesting blog post that got some traffic. This was probably due to my lack of a decent server, my configuration of WordPress, or some combination thereof.

I admit to being a WordPress novice, so this is probably on me. The thing is, I didn't really need WordPress for what I was doing. It didn't seem worthwhile to spend a lot of time learning how to configure it correctly and create a complex theme, when what I really wanted to do was quickly manage my design and focus on writing. Enter static site generators.

Picking a static site generator

A static site generator is pretty much exactly what it sounds like. It's a tool that assists you with creating a static site. The appeal of a static site for me was keeping things very simple. No databases. No complex framework I needed to learn. I just wanted to do some simple design work, write a little front-end code, and then focus on my writing. Another appeal of a static site was that it simplified hosting requirements.

There are approximately a bazillion different static site generators out there. Below is a rough prioritized list of what I was looking for.

  • Support for blogging functionality
  • Easy setup
  • Configuration in a language I am familiar with or can pick up quickly
  • Support for my favorite front-end tools, particularly SASS and Compass
  • Decent documentation
  • Actively maintained
  • Easy to deploy to Github Pages

Both Jekyll and Octopress (a framework on top of Jekyll) are pretty popular and incredibly easy to to deploy on Github Pages because Jekyll support is built-in. I played with Octopress briefly in the past and found myself fighting the built-in theming way too much. I had ok experiences with Jekyll in the past, but I vaguely recall being annoyed with some parts of the configuration, including setting it up to use SASS and Compass. Jekyll was a reasonable option, and my plan was to use it unless I found something more compelling.

I found Middleman to be that something compelling. It met all my guidelines (see notes below), and I had pleasant memories of working with it in the past for some rapid prototyping work.

Setting up Middleman

You need to set up a recent version of Ruby before you get started. I used Ruby 2.0.0.

###Install Middleman

gem install middleman

Create your project

I generated my project using the HTML5 Boilerplate project template, which sets up a bunch of basic things you will need using HTML5 Boilerplate. There are several other template options for you to choose from, if HTML5 Boilerplate doesn't strike your fancy.

middleman init my_project --template=html5

The majority of the code you will work with is in the source directory.

Configuration

The configuration for your middleman project lives in config.rb in the root directory. They do not have full documentation on all the things you can set in there. You can explore the settings in their code and take a look at my configuration on Github.

Start the server

cd my_project
middleman

Go to http://localhost:4567 (or whatever port it specifies). If it works, you've got the basics set up now!

Generate a static site

You can try building a static version of your site.

middleman build

The built static code goes into the build directory.

Switch to SASS

I modified the CSS files I planned on working with from .css to .scss, so that I could use SASS for my stylesheets.

Use pretty urls

Add the following to config.rb to use pretty urls.

activate :directory_indexes

I initially had some annoyances getting links to pages and assets working properly both locally and up on Github Pages because the directory structure was a little different. I was able to get it working with the configuration below and sticking with using the helpers for internal links and assets.

I set the following in config.rb:

set :relative_links, true

# Build-specific configuration
configure :build do
  activate :relative_assets
end

The default HTML5 Boilerplate code did not use the helpers for some of the asset links, so I changed that in this commit.

Add blogging

You can add blogging functionality to Middleman using the middleman-blog gem. I recommend reading and following the instructions in the Middleman documentation.

Once you get things set up, you can generate new articles with middleman article.

middleman article "The Name of My Article"

This will generate the file source/blog/2013-11-11-the-name-of-my-article.html.markdown (or some other path if you configured things differently). You can then add tags, modify the title, and write the content of your post.

---
title: The Name of My Article
date: 2013-11-12T03:31:00.000Z
tags: middleman, blogging
---

The body of my blog post.

Add syntax highlighting

I added syntax highlighting using the middleman-syntax gem. This allowed me to add the code blocks to this post.

Deploying to Github pages

If you want to use Github Pages for hosting, you need to put your project on Github. Github Pages will host static site files (e.g. html, css, js) placed in a branch named gh-pages.

Set up Middleman Github Pages

I use Middleman Github Pages to handle deploying Middleman changes to my gh-pages branch. Follow the instructions in the readme and you should be good to go.

It gives you some simple rake tasks to take care of everything for you.

rake build    # Compile all files into the build directory
rake publish  # Build and publish to Github Pages

Setup up custom domain name

Create a file named CNAME in the source directory and put the domain (or subdomain) into the file.

juliepagano.com

You will need to configure your DNS to point to Github. As of the time I wrote this, you should set up an A record pointing to 204.232.175.78.

Designing the site

Disclaimer: I am not a designer by trade, so I kind of have no idea what I'm doing.

The only major element I carried over from the previous design of the site is the logo (designed using Adobe Illustrator). I like it as a visual representation that breaks me down to two basic characteristics: hair and glasses.

In this iteration of the site, I modified the logo to be sharper. I also created a 2x version of the logo that is used on retina devices. Below is a quick snippet of the code.

$logo-img: 'logo.png';
$logo-img-2x: 'logo-2x.png';

header {
  h1 {
    background: image-url($logo-img) no-repeat;
    background-size: image-width($logo-img) image-height($logo-img);
    height: image-height($logo-img);

    @media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
      background-image: image-url($logo-img-2x);
    }
  }
}

Basic design

My design process was pretty basic. I wanted something flat and simple. I redesigned the site to focus on my writing, so it was important that my design made it easy to read longform text.

I worked with Kuler and Color Scheme Designer to select the basic color palette for the site. The starting color I worked from was the red shade of the hair in the logo.

Responsive design

A lot of people get links to blog posts on their phones and other devices, so it was important to me that my writing was readable on a variety of screen sizes. I used some very basic responsive design techniques to make this happen.

You can see some examples of what I did by looking for the @media queries in the primary stylesheet.

Fonts

I used Typekit to provide my text fonts. The site is currently using Proxima Nova for regular text and Source Code Pro for code snippets.

I used Font Awesome for the icons on the site. It is an icon font that is super-easy to set up and use. I set up Font Awesome using the Pro: Custom SASS option.

  1. Download Font Awesome
  2. Extract and copy the font-awesome directory to source/css
  3. Set the $fa-font-path variable in font-awesome/scss/_variables.scss to point to your font directory where you put the Font Awesome font files.
  4. Import Font Awesome in your stylesheet: @import "font-awesome/font-awesome";
  5. Use the icon-fonts via custom classes. There are a bunch of helpful examples for how to do this in their documentation.

Conclusion

It was a lot of fun to play around with a little design and a somewhat new framework. I was able to get things up and running fairly quickly once I actually sat down and worked at it. It is easy to update and work with, so I feel validated in the choices that I made based on my original goals. Hopefully, you will see a lot more writing from me now.

I shared a somewhat random smattering of my process above. I might try to write up some additional pieces later, but I wanted to get something out now. Feel free to contact me or file an issue if you have any questions or want me to cover additional topics.