Learn by making presents: A Static Site Generator (WIP)
JavaScript HTML
Latest commit b8418fb Jan 20, 2016 Jessica Lord Jessica Lord Merge pull request #34 from hfiguiere/case-sensitive
Issue #33 - It is config.JSON. (uppercase)
Failed to load latest commit information.
bin Issue #33 - It is config.JSON. (uppercase) Jan 20, 2016
lib parse latest post blurb better Apr 27, 2015
test-bin/templates Add test-bin files Oct 25, 2013
test cleanup Jan 13, 2014
.gitignore edit package.json Jan 20, 2014
LICENSE.md add extension Jan 11, 2014
README.md Fixed the logo in the readme file. May 24, 2015
balrog.png add back, update link to img Jan 13, 2014
config.JSON post urls Mar 24, 2014
old-readme.md Issue #33 - It is config.JSON. (uppercase) Jan 20, 2016



Disclaimer: One, this documentation is out of date, two, I've made this for my own purposes so it's very suited to that, it likely won't work, out of the box, just like you want it to, or be very adaptable. But! Have a look if ya want, fork and change it all up!


A static site generator with these goals:

  • Written in the pure, classic and elegant language JavaScript, using Node.js.
  • Use Handlebars for templating.
  • Includes paginated post feed!
  • RSS
  • Less mattery front-matter. Meta data extracted from post headings allowing markdown files to be free from traditional front-matter.

File Structure

  |_partials (optional)
    -pagination.html (optional)
  |_content (required)
    |_assets (optional)


opts = {
  source: "./content",
  output: "./site",
  templateDir: "./templates",
  partialsDir: "./partials",
  pagination: 4,
  templates: {
    blog: 'blog/*',
    about: 'about.md',
    feed: 'page/*'
  feed: {
    postsDir: './content/blog',
    urlPrefix: 'blog',
    site: {
      url: 'http://example.org',
      title: 'My Site',
      description: 'A site for stuff, ya know?',
      imageUrl: 'http://example.org/image.png',
      author: 'meauthor',
  • source, output, templateDir are the locations for the starting content, templates and your build.
  • partialsDir is optional and is for Handlebars template partials
  • templates is an object designating what templates to use on what pages. You can list directories or individual files in an array.
  • pagination is how many posts per page to show on post feed pages. If you don't include this, it defaults to 5.
  • feed is not optional, you must provide this information for generating the RSS

To Build

  1. Requires Node.js and NPM (which comes with .pkg and .msi downloads of Node.js)
  2. You'll install the balrog module globally, then run it from the command line within a directory set up in the style diagramed above.

Install Balrog

npm install -g balrog

Build Your Content

  1. Set up file structure as described above
  1. Create config.JSON
  2. Make sure you include and use the following as described:

Blog Feed Template

When creating a blog feed page template (the one that shows x (pagination number) of posts per page), your template must look like this:

{{> pagination}}

Pagination Template

The "Previous/Next" links are added to the bottom of blog feeds via a Handlebars Partial template:

<div class="turn-page">
  <a class="turn-previous" href="{{previous}}">Previous</a>
  <a class="turn-next" href="{{next}}">Next</a>

Additionally, the class end-of-pages is applied when there is not a previous or next page. If you do not include a partials directory, it will default to generating 1 blog post feed page with all posts.

Posts, Meta Data

Meta data is generated through the first 4 lines of each blog post. It doesn't matter how you style them, so long as your first 4 lines are in this order:

# Title
### Author
#### Date
##### Tags, tags, tags

Hi this is a post. So pancake.


From within your soon-to-be Balrog'd directory, run:

  • balrog

Build & Serve Locally & Watch

Serve up the site locally on a random port and watch for changes:

  • balrog --serve -w

Host on GitHub Pages

Create a new repository on GitHub and place all the contents of your Balrog generated /site directory on a branch named gh-pages. Bam, website! You can find it at: yourgithubname.github.io/reponame