staticbuild

(beta)

A static website generator and development server for Pug (aka Jade) and/or Nunjucks templates. Useable with Gulp, Grunt or other build automation.

Features

• Development Server - No need to maintain one in your Gulp/Grunt file.
• Path Management - Automatically maps and translates paths between source, destination, development and runtime.
• Bundling, Minification & Source Maps - Simple JSON configuration for bundling, minifying and source mapping Less, CSS and JavaScript files.
• Cache Busting with Version Hashes - Allows you to generate files at runtime named with a hashed version number from your package.
• Internationalization (i18n) - i18n methods are available to all views rendered by the development server and the generator.
• View Engines - Generate your site from Pug/Jade or Nunjucks templates. (More view engines could be added in the future.)
• View Contexts - Use the automatic global view context which provides access to build info, staticbuild methods and i18n or configure your own js file to expand upon the built-in view context.

README Contents

• Getting Started
• Demos
• Project Directory
• Configuration
• Command Line Interface
  • Help
  • Development Server
  • Setup
• API Documentation
• Why Pug (Jade) and Nunjucks?
• Roadmap

Getting Started

Global Install

Run

npm install -g staticbuild

Then, to setup a new project in the specified path:

staticbuild setup [path]

Output

Setting up basic site template....
Done.
When ready, please run: npm install && bower install
To view the site during development: npm run dev
To generate the site for production: gulp

(The path argument is optional and defaults to the current directory.)

Manual Installation

Run

npm install --save-dev staticbuild

In the package.json file for your project, add one of the following and then run it with npm run dev. Look at the demo projects for more details.

"scripts": {
  "dev": "staticbuild dev ."
}

or

"scripts": {
  "dev": "staticbuild dev path/to/staticbuild.json"
}

Demos

Look in the demo code to see a typical setup.

• Jade
• Nunjucks

The following open source sites are also using StaticBuild:

• The StaticBuild Website
• GelDesk

Project Directory

See demo/jade for an example. Run npm install in the demo and then npm run dev.

The project directory should contain a staticbuild.json configuration file or be organized according to the default configuration. A project directory organized according to the default-staticbuild.json configuration looks like this:

  /path/to/project
    - locales/...
    - src/...
    - [staticbuild.json]

The src/ directory is the root of the site which can contain static .html, .js and .css files as well as .jade, .less and/or nunjucks (.htm) files.

The locales/ directory is used by i18n-node to store json files which are created automatically during development when using the staticbuild.translate or translateNumeric function.

Configuration

Configuration is primarly read from a JSON file, named staticbuild.json by default.

Look at the demo projects and the main index.js for more information.

Command Line Interface

The default command right now is to just run the development server. That may change in the future and more commands will be added to generate files like a gulp or grunt file.

Help

staticbuild v0.12.4 - A static website generator and development server.

Usage:
  staticbuild [command] [options]

Commands:
  dev    Run the development web server.
  setup  Setup a new project.

Options:
  -v, --version  Show version number.  [boolean]
  -h, --help     Show help.  [boolean]
  -V, --verbose  Enables verbose output.  [count]

Development Server

staticbuild v0.12.4 - Development server.

    Runs a local http server to dynamically render static content during development.

Usage:
  staticbuild dev [options] <path>

Required:
  path           Path to a staticbuild.json file or directory to find one.
                 If no path is supplied, the current directory is used.

Options:
  -v, --version       Show version number.  [boolean]
  -h, --help, --help  Show help.  [boolean]
  -b, --bundling      Enable bundling.  [boolean] [default: false]
  -r, --restart       Number of seconds to delay nodemon restarts.  [number] [default: 1]
  --no-restart        Disables the built-in nodemon server restart.
  -V, --verbose       Enables verbose output.  [count]

Setup

At the time of this writing, this command simply creates a default staticbuild.json file.

staticbuild v0.12.4 - Setup.

    Interactive setup to create a new project.

Usage:
  staticbuild setup [options] [path]

Options:
  -v, --version       Show version number.  [boolean]
  -h, --help, --help  Show help.  [boolean]
  -V, --verbose       Enables verbose output.  [count]

API Documentation

See http://staticbuild.github.io/api/

Why Pug (Jade) and Nunjucks?

Any view engine can be plugged into staticbuild eventually. Pug (previously known as Jade) was initially used since it is the authors preference for emitting HTML.

Nunjucks was chosen as the first alternate to Jade since it can use templates to emit any type of text-based file format, not just HTML. This can be very useful for generating other types of fixtures for your static website such as markdown files, JSON, XML and so on.

Roadmap

• Create tests.
• Make some nicer demos.
• Create Configuration documentation.
• Improve API documentation.
  • Create examples.
• Improve the dev server code altogether to make it more plugabble.
  • Allow for per-view contexts that expand upon the global view context.
• Create a separate dev UI server command as an alternative to CLI commands.