carver

Features

carver is a static site generator with loads of features.

We know, there are loads of static site generators out there in the node world. But for our use case we needed something highly modularizable and adaptable. this static site generator can:

• render plain content files with additional use of middleware processors (such as our pebbles concept)

• render (db-)objects with a customizable property (here: 'content')

• render (db-)objects iterating through an array of objects containing the content attribute (here: 'translations')

• plug in any engine that returns something (jade, swig, ejs, you name em)

• plug in any writer defining the destination where the result should go to (works without writer as callback result)

• ... many more

  var carver = require('carver');

Simple example rendering markdown content

carver()
  .includeMarkdownEngine()
  .render( '# Heading\nFloating text' )
  .then( function( html ){
    // do something with the html
  });

Advanced example parsing the given cwd (working directory) for templatefiles and executes them. Default is index.<engine>, here index.jade. To change this, use .set('template','mytemplate').

carver()
  .includeFileWriter()
  .registerEngine('jade', require('jade'))
  .set('cwd', __dirname+'/layouts')
  .write()
  .then( function( compiler ){
    console.log('Your webpage has been written to', compiler.finalFilename);
  });

Even more advanced example with a before.render-hook enabled, precompiling markdown content of given doc object. If doc.content is available, it will interpreted as markdown and the result will be provided as markdownContent to the template..

carver()
  .includeFileWriter()
  .registerEngine('jade', require('jade'))
  .set('cwd', __dirname+'/layouts')
  .set('doc', webpage)
  .registerHook('before.render', require('carver/plugins').markdownCompiler)
  .write()
  .then( function( compiler ){
    console.log('Your webpage has been written to', compiler.finalFilename);
  });

Examples

For a working example and to clarify a lot of things, it might be useful to have a look at

https://github.com/caminio/carver-example.git

Installation

npm install carver

Introduction

carver is chainable. You just add settings and methods one after other (as demonstrated in the example above).

carver provides 2 different mechanism of rendering:

• low-level with .render('any string') returning the rendered string
• high-level through .write() which requires a set('cwd','/path/to/my/cwd') to be set and makes use of templates and settings found there. Read more about the workdir (cwd) in the section below

Engines

An engine is responsible for compiling the given content into whatever (usually html). By default, no engine is available and carver would just pass back the same content as entered.

Register an engine

carver()
  .registerEngine('ejs', require('ejs'));

As you can see, you simple require the official ejs module and it's native .render method will work. You can do this with any module supporting that express like behavior.

Writers

A writer is - compared to an engine - a little bit more work of customization.

• It will only be applied if a cwd (a working directory containing template files) has been set (it will read it's config/env.js file and use it as it's working directory)
• It is registered with a protocol name, so in the config/env.js a 'destination' property can be set telling carver where to store the file

If the config/env.js looks like this:

...
destination: 'file:///my/path/to/public'
...

carver looks up in it's writers registry for a file handler and triggers that one when write() is called.

Register a writer

carver()
  .registerWriter('webdav', myWebdavWriter);

Luckily, carver provides the most common writer, the filesystem writer. Enable it with:

carver()
  .includeFileWriter();

changing the filename according to runtime options

You can change your final filename within a before hook by setting options.filename to whatever is required. The final absolute path is computed by considering options.destinations as well as options.filename.

You can request a copy of the current computed file to be stored under a different filename. This is quite handy, if you are rendering calendar programmes where the current month is listed as the index.htm or somewhere different wheras the ordinary programme files are located under /programme/02-2014. This can be achieved with the

options.copyFilenames - Array

This options allows you to save copies of the current render result. just fill options.copyFilenames with relative paths (relative to the destinations directories).

compiler.options.copyFilenames = ['index'];

## Hooks

Hooks plug in at different stages of the compile process, execute a code and resolve to the next hook. Currently the following hooks are available in the following order

• before.render
• after.render
• before.write (only in case of cwd)
• after.write

Example:

carver()
  .registerHook('before.render', function( compiler, resolve){ 
    // do something and e.g.: 
    compiler.options.locals.myVar = 123;
    resolve();
  });

## Working with cwd (working directories)

The default use-case probably is, that you will work with objects somehow created (db?), passed on to carver along with a working directory and letting carver do the rest:

• resolve the cwd and process it's file system structure
  • load all