statix

Statix

Statix is a one-of-a-kind static website generator. Why? Because it is completely template engine agnostic.

How?

Thanks to TJ's awesome work on consolidate.js, we can use a multitude of templating engines with the apparently same API.

Requirements:

• node.js (0.8+)
• npm

Installation

$ npm install -g statix

Getting Started

$ statix new testProject
$ cd testProject
$ statix server

Statix has a local webserver, for convenience. This means that you can view your project without having to rebuild everytime. Statix watches your project directory and restarts the server automatically if any files change. You can test the server by going to http://localhost:8000 and editing one of the files in testProject/source/templates/, then refreshing your browser.

Once you are ready to deploy, you can run:

$ statix build

This will output your static site into testProject/deploy (the output dir is configurable).

Now, all you have to do is upload your site somewhere. It's that easy.

Commands:

server
Run the statix web server. Use this during development so you don't have to keep building when making changes

build
Build your project. Use this when you are ready to deploy.

new <folder>
Start a new project. This will output a barebones starting point to the folder of your choosing.

Options:

-h, --help                    output usage information
-V, --version                 output the version number
-p, --port [8000]             Specify a port to run on when running the server.
-d, --dir [.]                 Specify a dir to watch when running the server.
-s, --settings [./statix.js]  Specify a settings file.

Configuration:

Statix projects only need a statix.js file at the root of the project directory. After you're familiar with Statix, you'll probably want to create a template folder that has a more tailored statix.js file and other boilerplate type stuff and instead of using statix new you'll just use that folder as a base for your projects.

The statix command checks for a statix.js file at the current directory, then traverses the parent dirs. This means you can run any statix command from any sub-folder of your project.

Sample config file (with comments):

module.exports = {

  source_dir : "source", // `source_dir` is the directory where all your source files are.
  output_dir: "deploy", // `output_dir` is the directory you want to compile your static site to.

  template_engine : "swig", // the npm package name of the template engine, only engines supported by consolidate.js will work
  template_dir : "source/templates", // Only relevant if using swig : The directory where all your templates are.

  /*
    Literal regexes here. Statix won't include anything, unless it matches an `include_pattern` and also does
    not match an `exclude_pattern`. Checks against the full path, i.e. /Users/your.name/some/dir/site/blah.html
  */

  include_patterns : [
    /^(.*)$/
  ],

  exclude_patterns : [
    /^(.*)(base\.html{1})$/,
    /^(.*)(\/templates{1})(.*)$/
  ],

  /*
    An array of the pages to be rendered with the template engine.

    `output` is where your page will eventually live, in the static version of the site. I.e. "{output_dir}/{page.output}"

    `source` is where your template lives. I.e. "{source_dir}{page.source}"

    `data` is an object of variables you want to pass through to the template when it gets rendered.
  */

  pages : [
    {
      output : "index.html",
      source : "templates/index.html",
      data : {}
    },

    {
      output : "example.html",
      source : "templates/example.html",
      data : {}
    }
  ],

  /*
    `global_data` is an object that gets passed to all pages. Note, if you set `global_data.someProp` to something
    and also have `page.data.someProp`, the latter will take precedence.
  */

  global_data: {

  },

  /*
    Like `global_data`, but `build_data` only gets passed to the renderer when you build, not when viewing locally through the webserver.
    `build_data` properties take precedence over `global_data` properties.
  */

  build_data : {

  },

  /*
    If you need to process some things before you're ready to generate the pages (either through the web server or compilation),
    you can use this `ready` method. Common use case, you need to grab a bunch of data from a database, and are using asynch i/o
    Statix, does nothing until the `callback` passed to this method is called, so once you are done with everything you need to do,
    simply call `callback();`
  */

  ready : function (callback) {
    callback();
  },

  /*
    Statix gives you a hook to do whatever you want before the build actually happens. You can use this method to minify js/css,
    compile scss stylesheets, etc. Just be sure to invoke the `done()` function when you are ready for Statix to do it's thing.
  */

  preBuild : function (done) {
    done();
  },

  /*
    Just like `preBuild()` but this method gets called after Statix has generated the static site. You can use this to
    cleanup some files, git commit/push, or whatever you feel like. Just be sure to invoke the `done()` function afterwards.
  */
  postBuild : function (done) {
    done();
  }

}

Hooks:

Note the ready(), preBuild() and postBuild() hooks above. Use these however you see fit, they are there to be used and abused.

Changing the Template Engine

Go into statix.js and change

template_engine : "swig",

to

template_engine : "jade",

or

template_engine : "hogan",

statix server and statix build will check your npm_modules dir when they are run, checking for the relevant dir for whatever templating engine you are using. If it is not found, it will run npm install for you.

What engines are currently supported?

For an up-to-date list of supported template engines, go here.

To add suport for a template engine, simply issue a pull request to consolidate.js.

Programmatic API

You can use statix programmatically via its API:

var statix = require("statix");

// New Project
statix.utils._new("projectName");

// Build
statix.build("path/to/statix.js");

// Server
statix.server("path/to/statix.js", "path/to/watch", port);