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
- 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":
or
"scripts":
Demos
Look in the demo code to see a typical setup.
The following open source sites are also using StaticBuild:
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.