node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org ยป


Static site generator for Web Designers


Flatsite is a simple and fast HTML static site generator. It's perfect for small sites, prototyping and HTML Apps. With Flatsite you can use HTML only templates and map content files to main template using the class attribute. Additional page informations like title and meta description are mapped using JSON files. Flatsite manage only html files so it could be used with standard css and javascript or easy integrated with other deployment tools.

Flatsite is mantained by italian web agency Valdoweb and it is currently used in a wide range of sites, prototypes and Html Apps. You can see it used in


Build Status


npm install flatsite

Basic usage

var flatsite = require('flatsite');

It accept some parameters, default are:

source: './site/',
destination: './public/',
persistent: true,
sitemap : false,
siteurl : '/',
minify : false,
ignore : '',
template : 'mustache',
overridesource : false

Setting persistent at false make flatsite generate site only once and doesn't wait for changes in source folder.

With persistence is also possible to pass a REGEXP in ignore parameter to esclude some files to be watched.

In source directory Flatsite need to find three folders:

  • pages : content files (HTML and JSON)
  • partials : partial files (HTML)
  • templates : main template file (HTML)

Also mandatory is the main template file:


Template file must contain a tag with "main" class to map content into it.

Each page in /pages folder must have a correspondant JSON file with title and meta description.

IMPORTANT: For a minimal site setup look at folder test/source.


Sitemap generation:

Passing parameter 'sitemap' as true and 'siteurl' as an absolute url like '' cause Flatsite generating a basic valid sitemap stored in sitemap.xml file. If 'siteurl' is not passed the sitemap is created but it's not a valid one.

Multi template:

It's possible to use a different template for a page specifing it inside the json settings of the single page. It's useful, for example, for building multilanguage sites specifing a different template for each language. The template can be defined in this way:

"template": "default-en.html"

Mustache support:

Flatsite support Mustache sintax inside templates like {{name}} Mustache data must be placed in template.json file located in templates folder or in the page specific JSON file that override the default one. You can exclude the template system setting following parameter template : 'none'

Page and Partials Override:

Flatsite accept a file override for Page and Partials only (not templates). Page need is json file overrided too, is not possible override the html file only. The folder with files override need to be passed with the overridesource parameter and must replicate the standard directory tree. Look at folder test/overridesource as override example.

HTML minification:

Perform minification of the html output.


  • plates
  • chokidar
  • shelljs
  • hogan.js
  • html-minifier
  • cheerio (testing only)