Pop: A Static Site Builder

Pop (GitHub: alexyoung / pop, License: MIT, npm: pop) is my attempt at building something largely compatible with Jekyll that satisfies my own requirements.

Highlights:

  • Generates sites quickly
  • Extensible through CommonJS modules
  • Can regenerate a single post as I’m working on it (rather than the entire site)
  • Generates stub posts with sensible defaults
  • Comes complete with helpers for HTML5 articles, feeds, pagination
  • Post summaries

Installation

Installing Pop is easy with npm:

npm install -g pop

This makes a binary available called pop. Running pop -h displays usage:

pop is a static site builder.

Usage: pop [command] [options]
new    path           Generates a new site at path/
post   "Post Title"   Writes a new post file
server                Create a server on port 4000 for _site/

-v, --version         Display version and exit
-h, --help            Shows this message

Tutorial

Let’s generate a site:

$ pop new myblog
Site created: myblog

The results should look familiar to Jekyll users:

$ cd myblog/
$ ls
_config.json _includes    _layouts     _lib         _posts       index.jade   stylesheets

If you open the templates you’ll see where Pop starts to diverge from Jekyll. The index page uses helpers to generate paginated posts and pagination controls:

---
layout: default
title: My Site
paginate: true
---

!{paginatedPosts()}
!{paginate}

I’ve retained YAML front–matter. The primary motivation for this was to make posts compatible. Templates are not compatible, but writing templates with Jade and Stylus is extremely simple for those of us versed in JavaScript and CSS selectors.

The resulting HTML can be generated by either running pop or pop server. The server mode will regenerate files when they change, but it can’t currently track dependencies — if you change a post it’ll regenerate the post but not the index page. To use the server you’ll need to have Express installed (I might make this a dependency if this confuses people).

The end result is a nice little HTML5 blog:

Extending Pop

The _lib/ directory may contain two files: helpers.js and filters.js -- both should be CommonJS modules. Helpers are functions available to templates. They're bound to a SiteBuilder object, so site configuration values can be accessed using this.config.

Filters are used to pre–process entire files before they’re put through Textile, Markdown, or Jade. I’ve used this to support the syntax highlighting liquid tags used by Jekyll. I’m planning to use prettyprint with DailyJS instead of Pygments.

Post Stubs

Stub posts can be quickly generated like this:

$ pop post "Awesome Post"
Post created: _posts/2011-07-24-awesome-post.md

It includes example YAML front–matter, in case you don’t like typing it or forget the format.

HTML5

I want people to be able to get writing with Pop in no time at all, so I’ve been researching how to generate a flexible site that can be easily customised.

To this end, a default Pop site generates posts according to the hNews format, and the templates themselves use HTML5. The default stylesheet makes heavy use of CSS3 features, so you get a lot of bang–for–buck without using any images.

The blog at popjs.com uses the default templates and styles.

Tests

Pop includes Expresso tests; run them with make test.

Plans

Pop is optimised for my requirements, which means it might not have the broad appeal that Jekyll has. I’m working hard to make it friendly and extensible, with ideas inspired by popular Node projects like Express.

The biggest thing on the horizon is documentation — I’ve included detailed code comments and the dox output can be found here: Pop API documentation.

Why “Pop”?

I wanted a short, easy to type name that wasn’t taken by a package in npm. It probably isn’t the best name for SEO, but I’m going to be typing pop a lot in the near future!

blog comments powered by Disqus