zoopinator

Static site generator with a command line app and library interface.

IMPORTANT NOTE - this app is currently being rewritten. This new README does NOT match the current code.

Quick overview

Zoopinator uses a combination of Javascript and JSON files to tranform a source directory into a dest directory. The source directory is made up of a combination of templates and meta files that are used by zoopinator and asset files which are are copied over to the dest directory if the version in the source directory is newer. Using a simple comment-enabled JSON configuration zoopinator merges data from the JSON and Javascript meta files with the templates and renders the result into the dest directory.

Zoopinator supports 24 templating engines via the consolidate library. To minimize the amount of install bloat the engines are not bundled with zoopinator but can be manually installed via the zoopinator command line app or automatically installed when you specify one of the supported engines in a configuration.

How zoopinator works

Walking the source directory

Zoopinator starts at the top of the source directory and reads in the list of files and subdirectories. Once the file and subdirectory list is generated the files are first processed followed by all the subdirectories (a breadth-first walk).

Files starting with . (period), ~ (tilde) or _ (underscore) are ignored, meaning they are not processed as templates or copied as assets to the dest directory. As shown below Zoopinator uses _.js and _.json internally but you are free and encouraged to use underscore prefixed files as parent or partial templates or data files in your Javascript hooks. You can also provide a hook to filter out any other file you don't want processed.

Hooks, hooks and more hooks

Loading JSON and Javascript files

As zoopinator walks the source tree it looks for JSON and Javascript files using the following filename conventions:

• _.json - a comment-enabled JSON file that is re-loaded for each file processed. The entire contents of the file are available to the Javascript hooks and the "vars" property is automatically inserted into the context for the template engines. Zoopinator loads these files in a top down manner from the source directory down to the current directory being walked and combines the contents into a single object. This allows you to create default values in the top level JSON and then add or update values in subdirectories.
• _.js - a common.js file that is loaded once when zoopinator walks into the directory. The file can export hooks that zoopinator will use during its various processing stages. As with _.json files the hooks in these files are called in a top down manner in the preprocessing stage but change to a bottom up manner in the postprocessing stage.
• .json (example: index.html.json) - if this file exists it is loaded when the template it references is processed after the _.json files are loaded allowing you to customize or provide JSON data for a particular page.
• .js (example: index.html.js) - like the template json file this is loaded once when the template it references is processed. It is a common.js file whose hooks are called at the end of the preprocessing stages and the start of the postprocessing stages.

Merging templates

Adding hooks

Using zoopinator

Comand Line Configuration

Zoopinator is driven from a comment-enabled JSON configuration file that can be created from the command line.

$ zoopinator --create-config example.com.config

This command creates a configuration file that you must then edit to set the source and dest folders and optionally change the template engine from the default swig engine or change the file extension used by the templates in your source directory.

{
  "source: "",   // source folder or file
  "dest: "",
  "engines": ["swig"],
  
  // if true any file that isn't a template is copied to dest if it doesn't exist or is newer
  "copyNonTemplates": true,
  
  "verbose": false,
  "encoding": "utf8",
  "sourceRoot": "",

  "engineOptions": {
  
    "swig": {
      "extensions": {
        "html": {
          // set to empty string the remove extension when writing out the template to dest
          "destExtension": "html",
          
          // overide swig templating options for this extension
          "options": {
          }
        }
      },
      // swig templating options
      "options": {
        "autoescape": true,
        "allowErrors": true,
        "encoding": "utf8",
        "tags": {},
        "extensions": {},
        "tzOffset": 0
      }
    },
    
    ... 23 more template engines here ...
  }
}

Supported template engines

Zoopinator supports the following 24 templating engines via the consolidate library:

• atpl
• dot
• dust
• eco
• ect
• ejs
• haml
• haml-coffee
• handlebars
• hogan
• jade
• jazz
• jqtpl
• just
• liquor
• mote
• mustache
• qejs
• swig
• templayed
• toffee
• underscore
• walrus
• whiskers

Stages

all args:
  js
  scratchpad
  log
  readOnly.sourceInfo.ext
  readOnly.sourceInfo.basename
  readOnly.sourceInfo.isIgnoredFile
  readOnly.sourceInfo.isMultiHTMLFile


Bake -> BakeFolder || BakeFile
  args: 
    source
    dest
    options
  additional post args: 
    post.sourceExists
    post.sourceDestSame
    post.destExists
    post.sourceDestNotSameType
    
  BakeFolder
    args:
      source
      dest
    additional post args:
      files
      filters
    FilterFiles
      args:
        source
        dest
        files
        filters
    BakeFiles -> BakeFolder || BakeFile
      args:
        source
        dest
        files

  BakeFile
    args:
      source
      dest
      fromWatcher
      watch
    RenderHTML
      LoadJSON
      RenderMultiDestHTML
        GetMultiDestMap
        RenderFile*
      RenderFile
        LoadTemplate
        CompileTemplate
        RenderTemplate
        WriteRenderedTemplate
    CopyFile
    RerenderFolder
    RerenderFile

Getting Started

zoopinator is a node.js module that has both a command line component and a library that you can use in your own node.js projects. You don't have to be a node.js programmer to use the command line interface but you do need to have node.js installed.

Once you install node.js install the module with: npm install -g zoopinator

Command Line Interface

Library Interfaces

Contributing

Please maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using the existing Gruntfile.

Release History

• 0.1.0 Initial Release.

Roadmap

License

Copyright (c) 2013 by Doug Martin, Zoopdoop, LLC.
Licensed under the MIT license.