Waffel is a Node.js static site generator built to sit on top of build tools like Brunch, Gulp, or Grunt, turning content files with YAML front matter into static HTML via Nunjucks templates.
What is Waffel?
Waffel is a static site generator for Node.js that pairs with the Brunch build tool to render Nunjucks templates into static HTML. It reads content files with YAML front matter, exposes all loaded data to templates through a data property, and outputs a complete static site without requiring a database or server. The project is created by Diego Caponera and released under the MIT License.
Key Features
- Brunch-first workflow — The recommended setup is the brunch-with-waffel skeleton; run
brunch newwith that skeleton, thennpm installandbower install, and start a local server at localhost:3333. - Nunjucks templating — Templates use the Nunjucks engine, chosen for its expressiveness and the ability to chain filters, which puts more logic in templates since there is no controller layer.
- YAML front matter — Content metadata is read from YAML front matter; other formats like JSON or TOML are not supported yet.
- Data exposed in templates — All loaded data is available through the
dataproperty, allowing arbitrary composition likedata.users[post.author]without defining a schema. - No built-in asset pipeline — CSS/JS compilation, concatenation, and minification are intentionally left to Brunch, Gulp, or Grunt.
- No CLI — Scaffolding and build tasks are delegated to the surrounding build tool instead of providing a dedicated command-line interface.
- Custom filters and helpers — Users can include complicated filters and helpers that work throughout the HTML templates.
Who is it for?
- Developers building static sites with Brunch — Scaffold a new project with the brunch-with-waffel skeleton and get a static site workflow without inventing build steps.
- Prototypers who want template-level logic — Use Nunjucks filters and helpers to compose pages without writing a server-side controller or database schema.
- Maintainers of small multi-page websites — Generate pages from content files with YAML front matter and reuse Nunjucks templates across the site.
Use cases
- Content-driven sites beyond blogs — Waffel's README explicitly targets "more concrete use cases than just your personal blog", such as microsites, documentation, or simple portfolio pages.
- Team maintaining a project skeleton — Use the brunch-with-waffel skeleton as a starting point to standardize how static pages are authored and built across a team.
How does Waffel work?
The recommended onboarding is: install Brunch globally, run brunch new with the brunch-with-waffel skeleton, install npm and Bower dependencies, then npm start and visit http://localhost:3333. Waffel reads YAML front matter from content files, makes the data available to Nunjucks templates, and outputs static HTML through the Brunch pipeline.
FAQ
Does Waffel work with front matter formats other than YAML?
No, at the moment Waffel only supports YAML front matter. The author states they would accept a pull request to make the front matter format configurable.
Does Waffel provide a CLI?
No. The author deliberately avoids a CLI because Brunch, Gulp, and Grunt already handle the build workflow.
Does Waffel handle CSS/JS compilation or minification?
No. Waffel leaves asset compilation, concatenation, and minification to Brunch, Gulp, or Grunt.
Can I change the template language from Nunjucks?
Not at the moment. Waffel is tied to Nunjucks because of its expressiveness and filter chaining, though no extension point is described for swapping templating engines.
Does Waffel support complex relational data models?
Waffel does not define a data schema. It exposes all loaded data through the data property, so you can manually compose related items. The author notes that if you need complex query mechanisms, a different stack might be necessary.
