Building PIXLS.US

A journey of enlightenment...

This is just a log of reference material for actually building this site. It’s mostly for my own reference and edification. If you’re reading this, good luck making sense of my notes…

Static Website with Node.js and Metalsmith

I decided to build this site as a static website. This means that I’m generating all of the material on my local machines, and then compiling them into static webpages that are then uploaded to the server for serving. While this does sound like a pain in the ass, there are static site generators that make this job much easier.

So I looked around a bit more and found that apparently static site generators are the hip new thing.

I originally started with http://nanoc.ws/. While this was pretty interesting looking, I am just not a Ruby guy. So I had the double-whammy of learning the static build system along with Ruby occasionally. Plus, after a host of problems getting the correct ruby and gems installed on my OSX machine I just decided it wasn’t worth the hassle. (I have to switch between win at work, and OSX/Linux at home - so I needed a consistent environment).

I expanded my search and finally remembered Node.js. Looking around a bit more and I also found a static site generator for Node.js called Metalsmith. This was good, as I was already reasonably familiar with javascript.

Metalsmith basically just takes a directory of files, and passes them into a javascript environment for processing and output to a new directory, ready to be uploaded to a server. This is how this page is being generated right now as well.

Installing the Build Tools

The first thing to do is to get Node.js for your platform. Once installed, you’ll have access to the commands node as well as npm (node package manager?). Installing Metalsmith from there is as simple as:

node install metalsmith

Basically, Metalsmith just passes each of the directory contents through a stack of functions that you can use to process the files. Many of these are available as plug-ins for Metalsmith. For this site so far, I’ve been using these plug-ins:

• metalsmith-collections npm install metalsmith-collections
• metalsmith-permalinks npm install metalsmith-permalinks
• metalsmith-templates metalsmith-templates
• metalsmith-markdown metalsmith-markdown

For the templating option, I’m also using Handlebars.

There is a great tutorial on getting started with Metalsmith at Robin Thrift’s website.

Project Structure

The structure of this site is still in flux. By default metalsmith will look for a folder in the project root called “src”, and will output to a folder called “build”. The site structure I have setup for this site is:

|-pixlsus/
    |-src/
        |-articles/
        |-images/
        |-js/
        |-pages/
        |-scripts/
        |_styles/
    |-templates/
    |-index.js
    |_package.json

index.js

The main processing file for building the site is index.js.

var Metalsmith    = require('metalsmith'),
    collections    = require('metalsmith-collections'),
    permalinks    = require('metalsmith-permalinks'),
    templates    = require('metalsmith-templates'),
    markdown    = require('metalsmith-markdown'),
    metadata    = require('./config.json'),
    Handlebars    = require('handlebars');

Metalsmith(__dirname)
    .use(markdown({
        smartypants: true,
        gfm: true,
        tables: true
    }))
    .use(hyphenate_urls)
    .use(collections())
    .use(permalinks({
        pattern: ':collection/:title'
    }))
    .use(templates('handlebars'))
    .destination('./build')
    .build();

There are a couple of other things I am doing for the templating, and one custom function I wrote to automatically hyphenate url’s. To avoid something like:

articles/a%20new%20article/

I think this looks nicer:

articles/a-new-article/

Honestly, if I was just testing things out, the bare minimum I could use to get by would be:

var Metalsmith    = require('metalsmith'),
    templates     = require('metalsmith-templates'),
    Handlebars    = require('handlebars');

Metalsmith(__dirname)
    .use(templates('handlebars'))
    .destination('./build')
    .build();

If you have a base skeleton of a site, this would be all you need to run.

Building the Site

The site can be built by entering the site directory, and issuing the command node index.js.

Wait a few moments, and you should find a build/ directory full of your files ready to go.

Uploading

My host doesn’t have rsync access directly, but I can use rsync over ssh:

rsync -PSauve ssh --exclude=EXCLUDE_FILES build/ USER@pixls.us:/home4/pixlsus/public_html/

Which works just fine.

TODO

List of stuff I still need to get to:

• Test porting one of the ‘Getting Around in GIMP’ articles
  • Working on it.
• Port a few other test articles
• Use collections in Metalsmith to collect articles of a type
  • Generate a page of those.
• Probably a new index.html/front page.
• Work on “About” page
• Finish styling article pages.
  • Particularly the links (Mobile is done? - Tablet is needed).

This list will grow, of course, as it needs to until we launch!

Blog

I’ve started an article to represent blog posts on the site. I intend for them to live at the path: pixls.us/blog/YYYY/MM/title-of-post

The problem is that I can’t easily use metalsmith-permalinks for them. There doesn’t appear to be a way to easily process a sub-folder of documents with a different path. I don’t want the articles content to contain YYYY/MM in the path, but I do for blog posts.

So I think I’ll just have to write a plugin to handle that myself real quick. Shouldn’t be too hard, just need to do something similar to what I already wrote for hyphenating urls.

Basically, grab all blog posts, update their paths to the hyphenated version and change the source file to index.html in the directory. IF the file is not already in a sub-directory.

On Building PIXLS.US

Some notes from the back end

For the curious, and to serve as an introduction, I thought I’d make a few notes about how this site is built and what I’m currently obsessing over. Hopefully this can help define what I’m up to in case anyone wants to jump in and help out.

The Purpose

The entire point of this site, its “mission statement” if you will, is:

To provide tutorials, workflows and a showcase for high-quality photography using Free/Open Source Software.

Subject to revisions, of course, but mostly sums up what I’d like to accomplish here. I also think it’s good to have this documented somewhere to remind me. :)

The Technical

I had already started writing about this elsewhere, but I’m going to reiterate it here for posterity (when I wrote it earlier I hadn’t completed the blog portion of the site yet).

Static Pages

On the recommendation of darix on the #darktable irc channel, I looked into static site generators. I was originally going to use some sort of CMS and build things out from there, but I have to thank darix for causing me to pause and to think carefully about how to proceed.

I realized that I wanted to keep things simple. The main focus of the site is the articles themselves (a tutorial, workflow, or showcase). Really, this content is static by nature - so it made sense to approach it in that light.

The idea is to have all of the site content exist locally on my machine, then to pass it through some sort of processor to output all of the website pages ready to upload to my server. I was already familiar with the process as the GIMP website is built in a similar fashion.

I just had to find a static site generator that I could use and extend as needed.

Enter Metalsmith

There is a plethora of static site generators out there (apparently it’s the hip new thing?), so I just had to find one that I was comfortable with using and extending. I needed it to do what I wanted and get the hell out of the way so I could focus on content.

Oh, and I had to be able to extend it as needed myself. I’m already pretty comfortable writing for the web, so I decided to go with the Node.js-based Metalsmith. Mostly because I’m already comfortable making a mess in javascript.

Metalsmith basically takes a directory full of data, and passes those objects through any series of functions I want, munges them somehow, and then spits out my website. It’s the munging part that’s fun, and at least I can extend/modify things as needed quickly and easily.

tl;dr: I use javascript to process the files and output the website ready to upload.

Responsiveness

I also wanted the site to work well across different screen sizes and devices. So I’m trying to incorporate some responsiveness in the design. You can actually see it working right now by resizing your browser width. The page should reflow and elements change size to adapt to the new viewport.

This lets me focus on the content while knowing that it should adapt as needed to the viewer. As a great starting point, I used Adam Kaplans Grid.

Easy Reading

Taking a cue from the past, I’m also trying to maintain legibility and readability in the pages. This means paying attention to simple things like characters per line, font choices, and spacing. I’m not a designer, so this topic has been fun to learn about as I go.

The lines on this post, for instance, should settle in around 60-75 characters per line (I’m aiming for about 65). The Baymard Institute has a nice summary of the idea behind this.

Attractive

This goes without saying, I think, but who wants to look at an ugly layout/site? I can’t say this site is beautiful, but at least I’m conciously trying to make it a pleasant experience…

If not for everyone, at least for me…

Ease of Use

All the pretty in the world won’t fix something that’s hard to use. So I’m trying to put thought into user interaction. I try to get cruft out of the way so the focus is on the articles, while also providing easy navigation or interaction (that should get the hell out of the way when it’s not needed).

In Summary

That’s the short version. There’s a million things going on right now in my head as I build the site out. I’ve got most of the pieces sorted out, and just need to finish assembling them in a way that I like.

So we should be ready to get things kicked off before too long!