Qwelver

What Qwelver Actually Is

Qwelver is a lightweight static site generator built for developers who already know their way around a terminal and don't want to deal with bloated frameworks. It compiles templates into flat HTML files using a simple configuration system, supports custom asset pipelines, and has essentially zero runtime dependencies once built. It's not a CMS, it's not a framework, and it won't handle authentication or databases. You hand it markdown or templated source files, it spits out a public folder. I found it when I was tired of watching build times climb past two minutes on projects where I really only needed static pages. The initial setup is about ten minutes. A full build on a mid-range project—maybe forty or fifty pages with a few custom includes—runs in roughly thirty seconds on my machine. It's fast because it does very little. That's also its biggest limitation, as you'll see.

Getting Qwelver Installed and Running

Download the latest release from the official repository at github.com/qwelver/qwelver. The binary is self-contained, so after extraction you just drop it into a directory that's in your PATH or run it directly from wherever you put it. There's no npm install step, no Java runtime, no Python library to worry about. Once it's in place, initialize a new project by running qwelver init in your target folder. This creates the standard layout: a config file, a source directory, and an output directory. The default config is minimal and will work out of the box for basic use cases. I'd suggest changing the output path immediately though, since the default points to ./public and most hosting setups expect you to deploy that folder specifically. Build the site with qwelver build. Watch mode is available via qwelver watch if you're editing templates and want live regeneration. It picks up changes within a second or two, which is reasonable. Not instantaneous, but good enough for day-to-day work.

How the Template System Works in Practice

Qwelver uses its own templating language that sits somewhere between Liquid and Jinja2. It supports variables, conditional blocks, loops, and includes. The syntax is straightforward if you've touched templating before. If you haven't, expect a few hours of frustration before it clicks. One thing beginners consistently get wrong is how Qwelver handles variable scoping across includes. Variables defined in a parent template do not automatically leak into included partials unless you explicitly pass them. I spent about forty-five minutes debugging a site where my navigation links simply vanished on subpages. The fix was adding a {{ content | assign_nav }} call in the base layout before including the navigation partial. Once I understood that scoping model, everything else fell into place. The asset pipeline is equally simple. You place CSS and JavaScript in a dedicated assets folder, reference them with standard path syntax in your templates, and Qwelver copies them into the output alongside the generated HTML. There's no minification by default. If you want that, you run a separate step or add a post-build script. I wrote a small Node script that handles uglify and CSS compression after each build. Takes about five seconds extra, totally worth it.

Common Pitfalls and What to Watch For

Qwelver does not validate your templates at build time. That means a syntax error in a template won't stop the build. It will just produce broken HTML and you might not realize it until you open the site in a browser. I learned this the hard way on a client project when a misplaced closing bracket in a loop condition caused the entire homepage to render empty. The build reported success. The output was garbage. I ended up writing a pre-commit hook that runs a lightweight syntax check on all template files before allowing anything to be committed. Saved me from repeating that mistake. Another issue is the lack of built-in pagination support. Qwelver will generate pages from your data, but if you have a blog with hundreds of posts, you're on your own for splitting them into page sets. I solved this by writing a small plugin that takes a collection and outputs paginated index files. It works fine, but it's extra code you have to maintain. If pagination is critical to your project, you might be better off looking at something like Eleventy or Hugo, which handle this natively.

When Qwelver Falls Apart

Here's the honest part. Qwelver is excellent for small to medium static sites where you value speed and simplicity. It is not suitable for large-scale projects with complex routing, dynamic content requirements, or heavy customization needs. The plugin ecosystem is essentially nonexistent. There are no themes, no community extensions, no documentation beyond the README and a handful of forum posts. If you hit a wall, you're mostly on your own. I've seen people try to force Qwelver into building documentation sites with hundreds of pages, interlinked with conditional navigation trees and search functionality. It can technically do it, but you'll spend more time building the infrastructure around it than you would have spent just using a tool designed for that purpose. In those cases, I'd recommend something like MkDocs or Docsify instead. They were built for exactly this kind of workload. The build system also lacks incremental compilation. Every build regenerates the entire site from scratch, even if you've only changed one page. For small projects this is fine. For anything larger, the rebuild time adds up. A project with two hundred pages takes roughly two minutes to build completely on my machine. With incremental compilation, that drops to maybe thirty seconds if only one page changed. Until that feature ships, you're stuck with full rebuilds.

My Final Take

Qwelver is a solid choice if you want a dead-simple static site generator that gets out of your way. It's fast, it's predictable, and it doesn't make assumptions about what your site should look like. But it's also narrow in scope. Don't expect it to grow with you. When your project outgrows it—which happens faster than you'd think with Qwelver's limitations—migration will be painful because there's no export tool and the templating syntax doesn't map cleanly onto other generators. Start with a clear idea of what you need, and only choose Qwelver if it genuinely fits.