kerouac

Poetic static site generator for Node.js.

jaredhanson
80
9
JavaScript

Kerouac

Version
Build
Quality
Coverage
Dependencies

I saw that my life was a vast glowing empty page and I could do anything I
wanted.

– Jack Kerouac

Kerouac is a static site generator written in Node.js. It
is the simplest possible tool for transforming content written using lightweight
markup, such as Markdown, into a
complete website.

For highly-customized sites, Kerouac is also a powerful framework inspired by Express.
Each page in the generated website is declared as a route, which can take
advantage of middleware purpose-built for static pages. Never before has
been building a hybrid static and dynamic site been so consistent.

Install

$ npm install kerouac

Usage

var kerouac = require('kerouac');
var site = kerouac();

site.set('base url', 'http://www.example.com/');
site.content('content');
site.assets('public');

site.generate(function(err) {
  if (err) {
    console.error(err.message);
    console.error(err.stack);
    return;
  }
});

Content, Layouts, and Assets

A typical static site consists of a content written in Markdown,
and layouts which structure the content into an HTML page.

Kerouac will render all content within a directory:

site.content('content');

Content contains a section known as “front matter” surrounded by three dashes
(---). Front matter specifies metadata about the content, including which
layout should be used when generating a web page.

---
layout: 'main'
title: 'Welcome'
---

# Hello

Welcome to my website!

Layouts are located in a layouts directory and are rendered using EJS.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title><%- title -%></title>
  </head>
  <body>
    <%- content -%>
  </body>
</html>

Most web sites also contain assets including images, stylesheets, and scripts
that don’t need preprocessing. Kerouac will copy all assets in a given
directory when generating the site:

site.assets('public');

Note that markup and layout rendering is fully customizable. Alternatives,
such as Textile
and Jade, can be used to suit your preferences.

Plugins

Many websites contain sections, such as a sitemap or blog, which conform to an
established set of conventions. Kerouac supports plugins, which can be used to
bundle up these sections into modules that can be reused accross multiple sites.

For example, to generate a sitemap for your site, simply add the kerouac-sitemap
plugin:

site.plug(require('kerouac-sitemap')());

A list of plugins
developed by the community is available on the wiki.

Middleware

Just like Express and Connect,
Kerouac allows pages to be generated using middleware at both the whole-site and
per-page level. This is the lowest-level API, and content, assets, and plugins
(as detailed above) are built upon this foundation.

The majority of sites will never need to operate at this level. If needed, the
API is simple.

// whole-site middleware
site.use(function(page, next) {
  console.log('generating ' + page.path);
  next();
});

// page-level middleware
site.page('/hello.txt', function(page, next) {
  page.write('Hello!');
  page.end();
});

A list of middleware
developed by the community is available on the wiki.

Examples

The following sites are built with Kerouac, and have public code repositories
that illustrate how to develop using Kerouac’s API.

License

The MIT License

Copyright © 2012-2017 Jared Hanson <http://jaredhanson.net/>

Sponsor