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.
$ npm install kerouac
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;
}
});
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.
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.
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.
The following sites are built with Kerouac, and have public code repositories that illustrate how to develop using Kerouac's API.
- Locomotive — (source)
- Passport — (source)
Copyright (c) 2012-2017 Jared Hanson <http://jaredhanson.net/>
